### List Themes Response Example

Source: https://github.com/mautic/developer-documentation-new/blob/7.1/docs/rest_api/themes.md

Example JSON response when listing themes. It contains a 'themes' object with details for each installed theme.

```json
{
    "themes": {
        "blank": {
            "name": "Blank",
            "key": "blank",
            "config": {
                "name": "Blank",
                "author": "Mautic team",
                "authorUrl": "https://mautic.org",
                "features": [
                    "page",
                    "email",
                    "form"
                ]
            }
        }
    }
}

```

--------------------------------

### Get Theme Response Example

Source: https://github.com/mautic/developer-documentation-new/blob/7.1/docs/rest_api/themes.md

Example JSON response when a theme is successfully retrieved. It indicates the path to the downloaded ZIP file.

```json
{
    "file": "/absolute/path/to/the/system/temp/dir/with/the/theme/zip/file"
}

```

--------------------------------

### Start DDEV Environment

Source: https://github.com/mautic/developer-documentation-new/blob/7.1/docs/testing/e2e_test_suite.md

Start the DDEV environment for Mautic development. Ensure DDEV is installed prior to running this command.

```bash
ddev start
```

--------------------------------

### HTTP Request Example

Source: https://github.com/mautic/developer-documentation-new/blob/7.1/docs/rest_api/campaigns.md

Demonstrates the GET request format to retrieve a campaign. Replace ID with the actual campaign identifier.

```http
GET /campaigns/ID
```

--------------------------------

### Fetch API Keys from Integration Configuration

Source: https://github.com/mautic/developer-documentation-new/blob/7.1/docs/plugin_integrations/integrations_configuration.md

Retrieve API keys for an integration using the integration helper. This example shows how to get the 'username' from the stored API keys.

```php
<?php
$apiKeys  = $integrationHelper->get(HelloWorldIntegration::NAME)->getIntegrationConfiguration()->getApiKeys();
$username = $apiKeys['username'];
```

--------------------------------

### Start DDEV Environment for Mautic

Source: https://github.com/mautic/developer-documentation-new/blob/7.1/docs/development-environment/how_to_install_with_ddev.md

Navigate to the Mautic directory and start the DDEV environment.

```bash
cd mautic
ddev start
```

--------------------------------

### Run Mautic Command-Line Installation

Source: https://github.com/mautic/developer-documentation-new/blob/7.1/docs/development-environment/setup.md

Execute this bash command to initiate the Mautic installation process via the command line, specifying the installation URL.

```bash
php bin/console mautic:install https://mautic.example.com
```

--------------------------------

### Get User API Response Example

Source: https://github.com/mautic/developer-documentation-new/blob/7.1/docs/rest_api/users.md

Provides an example of a successful JSON response when retrieving user details. It includes various properties of the user object.

```json
{
   "user": {
       "isPublished": true,
       "dateAdded": "2026-02-21T05:19:56+00:00",
       "dateModified": "2026-02-21T05:20:13+00:00",
       "createdBy": 1,
       "createdByUser": "Admin Mautic",
       "modifiedBy": 1,
       "modifiedByUser": "Admin Mautic",
       "id": 3,
       "username": "r.green",
       "firstName": "Rachel",
       "lastName": "Green",
       "email": "rachel.green@acme.com",
       "position": "Marketing Staff",
       "role": {
           "createdByUser": "Admin Mautic",
           "modifiedByUser": null,
           "id": 2,
           "name": "Email Permissions",
           "description": null,
           "isAdmin": false,
           "rawPermissions": {
               "email:categories": [
                   "full"
               ],
               "email:emails": [
                   "full"
               ]
           }
       },
       "timezone": "Europe/Paris",
       "locale": null,
       "lastLogin": "2026-02-22T04:28:00+00:00",
       "lastActive": "2026-02-22T04:28:00+00:00",
       "signature": "Best regards, \r\nRachel Green"
   }
}

```

--------------------------------

### Plugin Database Migration Example

Source: https://github.com/mautic/developer-documentation-new/blob/7.1/docs/plugins/installation.md

Example of a Mautic plugin migration file. The `isApplicable` method checks if the migration needs to run, and the `up` method defines the SQL schema changes.

```php
<?php

declare(strict_types=1);

namespace MauticPlugin\HelloWorldBundle\Migrations;

use Doctrine\DBAL\Schema\Schema;
use Doctrine\DBAL\Schema\SchemaException;
use Mautic\IntegrationsBundle\Migration\AbstractMigration;

class Version_1_0_1 extends AbstractMigration
{
    private $table = 'hello_world';

    protected function isApplicable(Schema $schema): bool
    {
        try {
            return !$schema->getTable($this->concatPrefix($this->table))->hasColumn('is_enabled');
        } catch (SchemaException $e) {
            return false;
        }
    }

    protected function up(): void
    {
        $this->addSql("ALTER TABLE `{$this->concatPrefix($this->table)}` ADD `is_enabled` tinyint(1) 0");

        $this->addSql("CREATE INDEX {$this->concatPrefix('is_enabled')} ON {$this->concatPrefix($this->table)}(is_enabled);");
    }
}
```

--------------------------------

### Get Stage Response Example

Source: https://github.com/mautic/developer-documentation-new/blob/7.1/docs/rest_api/stages.md

Example JSON response when successfully retrieving an individual Stage. This includes properties like publication status, dates, creator, and stage-specific details.

```json
{
   "stage": {
       "isPublished": true,
       "dateAdded": "2026-02-13T16:11:07+00:00",
       "dateModified": null,
       "createdBy": 1,
       "createdByUser": "John Doe",
       "modifiedBy": 1,
       "modifiedByUser": "John Doe",
       "id": 7,
       "name": "Stage A",
       "category": null,
       "weight": 0,
       "description": "This is my first stage created via API.",
       "publishUp": "2026-02-13T17:00:00+00:00",
       "publishDown": "2026-02-20T17:00:00+00:00"
   }
}

```

--------------------------------

### List Assets Response Example

Source: https://github.com/mautic/developer-documentation-new/blob/7.1/docs/rest_api/assets.md

An example of the JSON response when listing assets. It includes total count and an array of asset objects.

```json
{
    "total": 1,
    "assets": [
        {
            "id": 1,
            "title": "Product Whitepaper",
            "description": "Some description",
            "alias": "whitepaper",
            "language": "en",
            "isPublished": true,
            "publishUp": "2015-06-07T06:28:27+00:00",
            "publishDown": "2015-06-30T06:28:27+00:00",
            "dateAdded": "2015-06-07T06:28:27+00:00",
            "createdBy": 1,
            "createdByUser": "Wayne Costa",
            "dateModified": "2015-06-010T09:30:47+00:00",
            "modifiedBy": 1,
            "modifiedByUser": "Wayne Costa",
            "downloadCount": 10,
            "uniqueDownloadCount": 8,
            "revision": 1,
            "category": null,
            "extension": "pdf",
            "mime": "application/pdf",
            "size": 269128,
            "downloadUrl": "https://example.com/asset/1:whitepaper"
        }
    ]
}

```

--------------------------------

### HTTP Request Examples for Reports

Source: https://github.com/mautic/developer-documentation-new/blob/7.1/docs/rest_api/reports.md

Examples of HTTP GET requests to retrieve report data. Demonstrates fetching a report by ID and specifying query parameters for filtering and pagination.

```http
GET /reports/ID
```

```http
GET /reports/3?dateFrom=2017-01-01&dateTo=2018-01-01&limit=5&page=3
```

--------------------------------

### Get Tag Response Example

Source: https://github.com/mautic/developer-documentation-new/blob/7.1/docs/rest_api/tags.md

Example JSON response when successfully retrieving an individual Tag. It includes the tag's ID, name, and description.

```json
{
    "tag": {
        "id": 34,
        "tag": "tagA",
        "description": "A tag for grouping contacts"
    }
}

```

--------------------------------

### Lead Event Subscriber Example

Source: https://github.com/mautic/developer-documentation-new/blob/7.1/docs/plugins/event_listeners.md

This example demonstrates how to create an event subscriber to listen for lead-related events like post-save and post-delete. Ensure the subscriber class is correctly namespaced and implements `EventSubscriberInterface`.

```php
<?php
//plugins\HelloWorldBundle\EventListener\LeadSubscriber

namespace MauticPlugin\HelloWorldBundle\EventListener;

use Mautic\LeadBundle\LeadEvent;
use Mautic\LeadBundle\LeadEvents;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

final class LeadSubscriber extends EventSubscriberInterface
{
    static public function getSubscribedEvents(): array
    {
        return [
            LeadEvents::LEAD_POST_SAVE     => ['onLeadPostSave', 0],
            LeadEvents::LEAD_POST_DELETE   => ['onLeadDelete', 0],
        ];
    }

    public function onLeadPostSave(LeadEvent $event): void
    {
        $lead = $event->getLead();

        // do something
    }

    public function onLeadDelete(LeadEvent $event): void
    {
        $lead = $event->getLead();

        $deletedId = $lead->deletedId;

        // do something
    }
}
// ...
```

--------------------------------

### Example Acceptance Test Class Structure

Source: https://github.com/mautic/developer-documentation-new/blob/7.1/docs/testing/e2e_test_suite.md

Defines the basic structure of an acceptance test class in Codeception. Includes setup and teardown methods, and a sample test scenario for login.

```PHP
<?php

class TestSuiteNameCest
{
    public function _before(AcceptanceTester $I)
    {
        // Code to run before each test
    }

    public function _after(AcceptanceTester $I)
    {
        // Code to run after each test
    }

    // Define your test methods

    public function login(AcceptanceTester $I)
    {
        $I->amOnPage('/s/login');
        $I->fillField('#username', $name);
        $I->fillField('#password', $password);
        $I->click('button[type=submit]');
        $I->see('Dashboard');
    }
}
```

--------------------------------

### List All Installed Themes

Source: https://github.com/mautic/developer-documentation-new/blob/7.1/docs/rest_api/themes.md

Retrieves a list of all installed themes, including details from their respective `config.json` files.

```php
<?php

//...
$response = $themesApi->getList();

```

--------------------------------

### Set Temporary File Path Response Example

Source: https://github.com/mautic/developer-documentation-new/blob/7.1/docs/rest_api/themes.md

Example JSON response after successfully changing the temporary file path. It confirms the new path and indicates a ZIP file within it.

```json
{
    "file": "/absolute/path/to/a/different/temp/dir/zipfile"
}

```

--------------------------------

### Complete Accordion Component Example

Source: https://github.com/mautic/developer-documentation-new/blob/7.1/docs/design_templates/accordion.md

A comprehensive example demonstrating the integration of the Accordion Component, including defining content with a set block and including the component with specific item configurations.

```twig
{% set utmTagsContent %}
    {% for i, utmTag in form.utmTags %}
        {{ form_row(utmTag) }}
    {% endfor %}
{% endset %}

{% include '@MauticCore/Helper/accordion.html.twig' with {
    'items': [
        {
            'id': 'UTM',
            'title': 'mautic.email.utm_tags',
            'padding_inline': false,
            'content': utmTagsContent,
        }
    ]
} %}
```

--------------------------------

### FormController Example

Source: https://github.com/mautic/developer-documentation-new/blob/7.1/docs/plugins/mvc.md

Demonstrates extending Mautic's FormController to create custom actions for managing forms and handling user input. Includes examples for retrieving data, creating forms, and processing submissions.

```php
<?php
// plugins/HelloWorldBundle/Controller/DefaultController.php

namespace MauticPlugin\HelloWorldBundle\Controller;

use Mautic\CoreBundle\Controller\FormController;

class DefaultController extends FormController
{
    public function worldAction(string $world = 'earth', WorldModel $model): Response
    {
        // Retrieve details about the world
        $worldDetails = $model->getWorldDetails($world);

        return $this->delegateView(
            [
                'viewParameters'  => [
                    'world'   => $world,
                    'details' => $worldDetails
                ],
                'contentTemplate' => 'HelloWorldBundle:World:details.html.php',
                'passthroughVars' => [
                    'activeLink'    => 'plugin_helloworld_world',
                    'route'         => $this->generateUrl('plugin_helloworld_world', ['world' => $world]),
                    'mauticContent' => 'helloWorldDetails'
                ]
            ]
        );
    }

    public function contactAction(ContactModel $model): Response
    {
        // Create the form object
        $form = $this->formFactory->create(ContactFormType::class);

        // Handle form submission if POST
        if ($this->request->getMethod() == 'POST') {
            $flashes = [];

            // isFormCancelled() checks if the cancel button was clicked
            if ($cancelled = $this->isFormCancelled($form)) {

                // isFormValid() will bind the request to the form object and validate the data
                if ($valid = $this->isFormValid($form)) {

                    // Send the email
                    $model->sendContactEmail($form->getData());

                    // Set success flash message
                    $flashes[] = [
                        'type'    => 'notice',
                        'msg'     => 'plugin.helloworld.notice.thank_you',
                        'msgVars' => [
                            '%name%' => $form['name']->getData()
                        ]
                    ];
                }
            }

            if ($cancelled || $valid) {
                // Redirect to /hello/world

                return $this->postActionRedirect(
                    [
                        'returnUrl'       => $this->generateUrl('plugin_helloworld_world'),
                        'contentTemplate' => 'MauticPlugin\HelloWorldBundle\Controller\DefaultController:worldAction',
                        'flashes'         => $flashes
                    ]
                );
            } // Otherwise show the form again with validation error messages
        }

        // Display the form
        return $this->delegateView(
            [
                'viewParameters'  => [
                    'form' => $form->createView()
                ),
                'contentTemplate' => '@HelloWorld/Contact/form.html.twig',
                'passthroughVars' => [
                    'activeLink' => 'plugin_helloworld_contact',
                    'route'      => $this->generateUrl('plugin_helloworld_contact')
                ]
            ]
        );
    }
}

```

--------------------------------

### Plugin Install and Update Event Listener

Source: https://github.com/mautic/developer-documentation-new/blob/7.1/docs/plugins/installation.md

Implement this listener to react to plugin installation and update events. Available since Mautic 4.2.0.

```php
<?php

declare(strict_types=1);

namespace MauticPlugin\HelloWorldBundle\EventListener;

use Mautic\PluginBundle\Event\PluginInstallEvent;
use Mautic\PluginBundle\Event\PluginUpdateEvent;
use Mautic\PluginBundle\PluginEvents;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class InstallUpdateSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            PluginEvents::ON_PLUGIN_INSTALL => ['onPluginInstall', 0],
            PluginEvents::ON_PLUGIN_UPDATE  => ['onPluginUpdate', 0],
        ];
    }

    public function onPluginInstall(PluginInstallEvent $event)
    {
        // Handle your logic here
    }

    public function onPluginUpdate(PluginUpdateEvent $event)
    {
        // Handle your logic here
    }
}
```

--------------------------------

### List Notifications Response Example

Source: https://github.com/mautic/developer-documentation-new/blob/7.1/docs/rest_api/notifications.md

An example of the JSON response when listing notifications. It includes total count and an array of notification objects.

```json
{
    "total":1,
    "notifications":[
        {
            "isPublished":true,
            "dateAdded":"2016-09-14T14:03:05+00:00",
            "createdBy":1,
            "createdByUser":"John Doe",
            "dateModified":"2016-09-15T08:40:46+00:00",
            "modifiedBy":1,
            "modifiedByUser":"John Doe",
            "id":1,
            "name":"The first notification",
            "heading":"The first notification Heading",
            "message":"The first notification Message",
            "url":"http:\/\/mautic.org",
            "language":"en",
            "category":null,
            "publishUp":null,
            "publishDown":null,
            "readCount":0,
            "sentCount":0
        }
    ]
}

```

--------------------------------

### List Themes

Source: https://github.com/mautic/developer-documentation-new/blob/7.1/docs/rest_api/themes.md

Lists all installed Themes along with details extracted from their `config.json` files.

```APIDOC
## List Themes

### Description
Lists all installed Themes with details from their `config.json` files.

### Method
GET

### Endpoint
`/themes`

### Response
#### Success Response (200)
- **themes** (object) - A dictionary where keys are theme keys and values are theme objects.

#### Theme object properties
- **name** (string) - Display name of the Theme.
- **key** (string) - Directory name and unique identifier of the Theme.
- **config** (object) - Theme configuration from `config.json`.

#### Config object properties
- **name** (string) - Theme name.
- **author** (string) - Theme author.
- **authorUrl** (string) - Author’s website URL.
- **features** (array) - List of supported features such as `page`, `email`, or `form`.
- **builder** (array) - Optional list of compatible builders such as `legacy` or `grapeJs`.

### Response Example
```json
{
    "themes": {
        "blank": {
            "name": "Blank",
            "key": "blank",
            "config": {
                "name": "Blank",
                "author": "Mautic team",
                "authorUrl": "https://mautic.org",
                "features": [
                    "page",
                    "email",
                    "form"
                ]
            }
        }
    }
}
```
```

--------------------------------

### List Themes HTTP Request

Source: https://github.com/mautic/developer-documentation-new/blob/7.1/docs/rest_api/themes.md

This is the HTTP request format for listing all installed themes.

```http
GET /themes

```

--------------------------------

### Configure OAuth2 Credentials and Initiate Token Process

Source: https://github.com/mautic/developer-documentation-new/blob/7.1/docs/plugin_integrations/integrations_authentication.md

This example demonstrates how to retrieve integration configuration, generate a redirect URI, and set up the necessary credentials for OAuth2 authentication. It prepares the client for the token exchange process using the authorization code.

```php
<?php
use kamermans\OAuth2\Persistence\TokenPersistenceInterface;
use MauticPlugin\HelloWorldBundle\Integration\HelloWorldIntegration;
use Mautic\IntegrationsBundle\Auth\Provider\Oauth2ThreeLegged\Credentials\CodeInterface;
use Mautic\IntegrationsBundle\Auth\Provider\Oauth2ThreeLegged\Credentials\CredentialsInterface;
use Mautic\IntegrationsBundle\Auth\Provider\Oauth2ThreeLegged\Credentials\RedirectUriInterface;
use Mautic\IntegrationsBundle\Auth\Provider\Oauth2TwoLegged\Credentials\ScopeInterface;
use Mautic\IntegrationsBundle\Auth\Provider\Oauth2TwoLegged\HttpFactory;
use Mautic\IntegrationsBundle\Auth\Support\Oauth2\ConfigAccess\ConfigTokenPersistenceInterface;
use Mautic\IntegrationsBundle\Helper\IntegrationsHelper;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\Routing\Router;

/** @var $integrationsHelper IntegrationsHelper */
$integration = $integrationsHelper->getIntegration(HelloWorldIntegration::NAME);

/** @var Router $router */
$redirectUrl = $router->generate('mautic_integration_public_callback', ['integration' => HelloWorldIntegration::NAME]);

$configuration = $integration->getIntegrationConfiguration();
$apiKeys       = $configuration->getApiKeys();

/** @var Request $request */
$code = $request->get('code');

$credentials = new class(
    'https://example.com/api/oauth/authorize',
    'https://example.com/api/oauth/token',
    $redirectUrl,
    'scope1,scope2',
    $apiKeys['client_id'],
    $apiKeys['client_secret'],
    $code
) implements CredentialsInterface, RedirectUriInterface, ScopeInterface, CodeInterface {
    private $authorizeUrl;
    private $tokenUrl;
    private $redirectUrl;
    private $scope;
    private $clientId;
    private $clientSecret;
    private $code;

    public function __construct(string $authorizeUrl, string $tokenUrl, string $redirectUrl, string $scope, string $clientId, string $clientSecret, ?string $code)
    {
        $this->authorizeUrl = $authorizeUrl;
        $this->tokenUrl     = $tokenUrl;
        $this->redirectUrl  = $redirectUrl;
        $this->scope        = $scope;
        $this->clientId     = $clientId;
        $this->clientSecret = $clientSecret;
        $this->code         = $code;
    }

    public function getAuthorizationUrl(): string
    {
        return $this->authorizeUrl;
    }

    public function getTokenUrl(): string
    {
        return $this->tokenUrl;
    }

    public function getRedirectUri(): string
    {
        return $this->redirectUrl;
    }

    public function getClientId(): ?string
    {
        return $this->clientId;
    }

    public function getClientSecret(): ?string
    {
        return $this->clientSecret;
    }

    public function getScope(): ?string
    {

```

--------------------------------

### Implement AuthenticationInterface for Hello World Integration

Source: https://github.com/mautic/developer-documentation-new/blob/7.1/docs/plugin_integrations/integrations_authentication.md

Provides the full implementation of the AuthenticationInterface for a sample 'Hello World' integration. It includes methods to check authentication status and handle the authentication process by obtaining an access token.

```php
<?php
namespace MauticPlugin\HelloWorldBundle\Integration\Support;

use MauticPlugin\HelloWorldBundle\Connection\Client;
use MauticPlugin\HelloWorldBundle\Integration\HelloWorldIntegration;
use Mautic\IntegrationsBundle\Integration\ConfigurationTrait;
use Mautic\IntegrationsBundle\Integration\Interfaces\AuthenticationInterface;
use Symfony\Component\HttpFoundation\Request;

class AuthSupport implements AuthenticationInterface
{
    use ConfigurationTrait;

    private Client $client;

    public function __construct(Client $client)
    {
        $this->client = $client;
    }

    public function getName(): string
    {
        return HelloWorldIntegration::NAME;
    }

    public function getDisplayName(): string
    {
        return 'Hello World';
    }

    /**
     * Returns true if the integration has already been authorized with the third party service.
     *
     * @return bool
     */
    public function isAuthenticated(): bool
    {
        $apiKeys = $this->getIntegrationConfiguration()->getApiKeys();

        return !empty($apiKeys['access_token']) && !empty($apiKeys['refresh_token']);
    }

    /**
     * Authenticate and obtain the access token
     *
     * @param Request $request
     *
     * @return string
     */
    public function authenticateIntegration(Request $request): string
    {
        $code = $request->query->get('code');

        $this->client->authenticate($code);

        return 'Success!';
    }
}
```

--------------------------------

### Get User HTTP Request Example

Source: https://github.com/mautic/developer-documentation-new/blob/7.1/docs/rest_api/users.md

Illustrates the HTTP GET request format for retrieving a specific user by their ID. The endpoint is /users/ID.

```http
GET /users/ID
```

--------------------------------

### Combining Flex Utilities

Source: https://github.com/mautic/developer-documentation-new/blob/7.1/docs/design/utilities.md

This example demonstrates combining multiple flex utilities to create a responsive and centered layout. It sets up a flex container that behaves as a column on small screens and a row on medium screens and up, with wrapping, centering, and a fixed gap between items.

```html
<div class="d-flex fd-row-md fd-column fw-wrap jc-center ai-center gap-15">
  <!-- Flex items here -->
</div>
```

--------------------------------

### Include List Toolbar with Quick Filters

Source: https://github.com/mautic/developer-documentation-new/blob/7.1/docs/design/quick_filters.md

This example shows how to include the 'list_toolbar.html.twig' template and pass an array of quick filter definitions. Ensure the 'quickFilters' key is present in the passed options.

```twig
{{ include('@MauticCore/Helper/list_toolbar.html.twig', {
    'searchValue': searchValue,
    'searchHelp': 'mautic.form.form.help.searchcommands',
    'searchId': 'list-search',
    'action': currentRoute,
    'quickFilters': [
        {
            'search': 'has:results',
            'label': 'mautic.core.search.quickfilter.form_results',
            'tooltip': 'mautic.core.search.quickfilter.form_results.tooltip',
            'icon': 'ri-file-list-2-line'
        }
    ]
}) }}
```

--------------------------------

### Client Credentials Grant Example

Source: https://github.com/mautic/developer-documentation-new/blob/7.1/docs/plugin_integrations/integrations_authentication.md

Demonstrates the client credentials grant for a service requiring a scope. Assumes token persistence is configured for a one-hour token validity.

```php
<?php
use kamermans\OAuth2\Persistence\TokenPersistenceInterface;
use MauticPlugin\HelloWorldBundle\Integration\HelloWorldIntegration;
use Mautic\IntegrationsBundle\Auth\Provider\Oauth2TwoLegged\Credentials\ClientCredentialsGrantInterface;
use Mautic\IntegrationsBundle\Auth\Provider\Oauth2TwoLegged\Credentials\ScopeInterface;
use Mautic\IntegrationsBundle\Auth\Provider\Oauth2TwoLegged\HttpFactory;
use Mautic\IntegrationsBundle\Auth\Support\Oauth2\ConfigAccess\ConfigTokenPersistenceInterface;
use Mautic\IntegrationsBundle\Helper\IntegrationsHelper;

/** @var $integrationsHelper IntegrationsHelper */
$integration = $integrationsHelper->getIntegration(HelloWorldIntegration::NAME);

$configuration = $integration->getIntegrationConfiguration();
$apiKeys       = $configuration->getApiKeys();

$credentials = new class(
    'https://example.com/api/oauth/token',
    'scope1,scope2',
    $apiKeys['client_id'],
    $apiKeys['client_secret']
) implements ClientCredentialsGrantInterface, ScopeInterface {
    private $authorizeUrl;
    private $scope;
    private $clientId;
    private $clientSecret;

    public function getAuthorizationUrl(): string
    {
        return $this->authorizeUrl;
    }

    public function getClientId(): ?string
    {
        return $this->clientId;
    }

    public function getClientSecret(): ?string
    {
        return $this->clientSecret;
    }

    public function getScope(): ?string
    {
        return $this->scope;
    }
};

/** @var $tokenPersistenceFactory TokenPersistenceFactory */
$tokenPersistence = $tokenPersistenceFactory->create($integration);
$config           = new class($tokenPersistence) implements ConfigTokenPersistenceInterface {
    private $tokenPersistence;

    public function __construct(TokenPersistenceInterface$tokenPersistence)
    {
        $this->tokenPersistence = $tokenPersistence;
    }

    public function getTokenPersistence(): TokenPersistenceInterface
    {
        return $this->tokenPersistence;
    }
};

/** @var $factory HttpFactory */
$client   = $factory->getClient($credentials, $config);
$response = $client->get('https://example.com/api/fetch');

```

--------------------------------

### Get Form Response Example

Source: https://github.com/mautic/developer-documentation-new/blob/7.1/docs/rest_api/forms.md

This JSON structure represents a successful response when retrieving a specific form. It includes details about the form's properties, creator, and cached HTML.

```json
{
   "form": {
       "isPublished": true,
       "dateAdded": "2026-02-19T07:06:12+00:00",
       "dateModified": "2026-02-19T07:10:06+00:00",
       "createdBy": 1,
       "createdByUser": "Admin Mautic",
       "modifiedBy": 1,
       "modifiedByUser": "Admin Mautic",
       "id": 2,
       "name": "Acme Global Conference Registration",
       "alias": "acme_globa",
       "category": {
           "createdByUser": "Admin Mautic",
           "modifiedByUser": null,
           "id": 1,
           "title": "Company attendees",
           "alias": "company-attendees",
           "description": null,
           "color": null,
           "bundle": "form"
       },
       "description": "<p><span style=\"color:rgb(186,33,33);\"><span class=\"s2\" style=\"box-sizing:border-box;\">Acme Global Conference registration.</span></span></p>",
       "cachedHtml": "\n<style type=\"text/css\" scoped>\n    .mauticform_wrapper { max-width: 600px; margin: 10px auto; }\n    .mauticform-innerform {}\n    .mauticform-post-success {}\n    .mauticform-name { font-weight: bold; font-size: 1.5em; margin-bottom: 3px; }\n    .mauticform-description { margin-top: 2px; margin-bottom: 10px; }\n    .mauticform-error { margin-bottom: 10px; color: red; }\n    .mauticform-message { margin-bottom: 10px; color: green; }\n    .mauticform-row { display: block; margin-bottom: 20px; }\n    .mauticform-label { font-size: 1.1em; display: block; font-weight: bold; margin-bottom: 5px; }\n    .mauticform-row.mauticform-required .mauticform-label:after { color: #e32; content: \" *\"; display: inline; }\n    .mauticform-helpmessage { display: block; font-size: 0.9em; margin-bottom: 3px; }\n    .mauticform-errormsg { display: block; color: red; margin-top: 2px; }\n    .mauticform-selectbox, .mauticform-input, .mauticform-textarea { width: 100%; padding: 0.5em 0.5em; border: 1px solid #CCC; background: #fff; box-shadow: 0px 0px 0px #fff inset; border-radius: 4px; box-sizing: border-box; }\n    .mauticform-checkboxgrp-row {}\n    .mauticform-checkboxgrp-label { font-weight: normal; }\n    .mauticform-checkboxgrp-checkbox {}\n    .mauticform-radiogrp-row {}\n    .mauticform-radiogrp-label { font-weight: normal; }\n    .mauticform-radiogrp-radio {}\n    .mauticform-button-wrapper .mauticform-button.btn-ghost, .mauticform-pagebreak-wrapper .mauticform-pagebreak.btn-ghost { color: #5d6c7c;background-color: #ffffff;border-color: #dddddd;}\n    .mauticform-button-wrapper .mauticform-button, .mauticform-pagebreak-wrapper .mauticform-pagebreak { display: inline-block;margin-bottom: 0;font-weight: 600;text-align: center;vertical-align: middle;cursor: pointer;background-image: none;border: 1px solid transparent;white-space: nowrap;padding: 6px 12px;font-size: 13px;line-height: 1.3856;border-radius: 3px;-webkit-user-select: none;-moz-user-select: none;-ms-user-select: none;user-select: none;}\n    .mauticform-button-wrapper .mauticform-button.btn-ghost[disabled], .mauticform-pagebreak-wrapper .mauticform-pagebreak.btn-ghost[disabled] { background-color: #ffffff; border-color: #dddddd; opacity: 0.75; cursor: not-allowed; }\n    .mauticform-pagebreak-wrapper .mauticform-button-wrapper {  display: inline; }\n\n    /**\n    * @see https://github.com/TarekRaafat/autoComplete.js/blob/master/dist/css/autoComplete.02.css.\n    */\n    .autoComplete_wrapper {position: relative;}\n    .autoComplete_wrapper > input::placeholder {transition: all 0.3s ease;}\n    .autoComplete_wrapper > ul {position: absolute;max-height: 226px;overflow-y: scroll;top: 100%;left: 0;right: 0;padding: 0;margin: 0.5rem 0 0 0;border-radius: 4px;background-color: #fff;border: 1px solid rgba(33, 33, 33, 0.1);z-index: 1000;outline: none;}\n    .autoComplete_wrapper > ul > li {padding: 10px 20px;list-style: none;text-align: left;font-size: 16px;color: #212121;transition: all 0.1s ease-in-out;border-radius: 3px;background-color: rgba(255, 255, 255, 1);white-space: nowrap;overflow: hidden;text-overflow: ellipsis;transition: all 0.2s ease;}\n    .autoComplete_wrapper > ul > li > span {float: right;}\n    .autoComplete_wrapper > ul > li::selection {color: rgba(#ffffff, 0);background-color: rgba(#ffffff, 0);}\n    .autoComplete_wrapper > ul > li:hover {cursor: pointer;background-color: rgba(123, 123, 123, 0.1);}\n    .autoComplete_wrapper > ul > li mark {background-color: transparent;font-weight: bold;}\n    .autoComplete_wrapper > ul > li mark::selection {background-color: rgba(#ffffff, 0);}\n    .autoComplete_wrapper > ul > li[aria-selected=\"true\"] {background-color: rgba(123, 123, 123, 0.1);}\n    @media only screen and (max-width: 600px) {\n      .autoComplete_wrapper > input {width: 18rem;}\n    }\n</style>\n\n<style type=\"text/css\" scoped>\n    .mauticform-field-hidden { display:none }\n</style>\n<div id=\"mauticform_wrapper_acmeglobalconferenceregistration\" class=\"mauticform_w" 
   }
}
```

--------------------------------

### Basic Authentication Example

Source: https://github.com/mautic/developer-documentation-new/blob/7.1/docs/rest_api/authentication.md

Demonstrates how to use Basic Authentication for Mautic API requests by encoding credentials and including them in the Authorization header.

```APIDOC
## Basic Authentication

### Description
Use Basic Authentication for quick API access. Ensure it's enabled in Mautic's configuration.

### Method
GET (or other HTTP methods for specific endpoints)

### Endpoint
`https://mautic.example.com/api/{endpoint}`

### Parameters
#### Request Headers
- **Authorization** (string) - Required - `Basic BASE64_ENCODED_USERNAME:PASSWORD`

### Request Example
```bash
curl -H "Authorization: Basic dXNlcjpwYXNzd29yZA==" https://mautic.example.com/api/contacts
```
```

--------------------------------

### Example Campaign Response (JSON)

Source: https://github.com/mautic/developer-documentation-new/blob/7.1/docs/rest_api/campaigns.md

Illustrates the structure of a successful JSON response when fetching a campaign. Includes campaign details and event configurations.

```json
{
    "campaign": {
        "id": 3,
        "name": "Email A/B Test",
        "description": null,
        "isPublished": true,
        "publishUp": null,
        "publishDown": null,
        "dateAdded": "2015-07-15T15:06:02-05:00",
        "createdBy": 1,
        "createdByUser": "Delfina Henderson",
        "dateModified": "2015-07-20T13:11:56-05:00",
        "modifiedBy": 1,
        "modifiedByUser": "Iris Durand",
        "category": null,
        "events": {
            "28": {
                "id": 28,
                "type": "lead.changepoints",
                "eventType": "action",
                "name": "Adjust lead points",
                "description": null,
                "order": 1,
                "properties": {
                  "points": 20
                },
                "triggerDate": null,
                "triggerInterval": 1,
                "triggerIntervalUnit": "d",
                "triggerMode": "immediate",
                "children": [],
                "parent": null,
                "decisionPath": null
            }
        }
    }
}

```

--------------------------------

### Get Company Response Example

Source: https://github.com/mautic/developer-documentation-new/blob/7.1/docs/rest_api/companies.md

This JSON object represents a successful response when retrieving a company's details. It includes core company information such as address, contact details, and name.

```json
{
   "company": {
       "id": 1,
       "score": 150,
       "fields": {
           "core": {
               "companyaddress1": {
                   "id": "29",
                   "label": "Address 1",
                   "alias": "companyaddress1",
                   "type": "text",
                   "group": "core",
                   "object": "company",
                   "is_fixed": "1",
                   "properties": "a:0:{}",
                   "default_value": null,
                   "value": "123 Main St",
                   "normalizedValue": "123 Main St"
               },
               "companyaddress2": {
                   "id": "30",
                   "label": "Address 2",
                   "alias": "companyaddress2",
                   "type": "text",
                   "group": "core",
                   "object": "company",
                   "is_fixed": "1",
                   "properties": "a:0:{}",
                   "default_value": null,
                   "value": "Suite 100",
                   "normalizedValue": "Suite 100"
               },
               "companyemail": {
                   "id": "31",
                   "label": "Company Email",
                   "alias": "companyemail",
                   "type": "email",
                   "group": "core",
                   "object": "company",
                   "is_fixed": "1",
                   "properties": "a:0:{}",
                   "default_value": null,
                   "value": "info@acme.com",
                   "normalizedValue": "info@acme.com"
               },
               "companyphone": {
                   "id": "32",
                   "label": "Phone",
                   "alias": "companyphone",
                   "type": "tel",
                   "group": "core",
                   "object": "company",
                   "is_fixed": "1",
                   "properties": "a:0:{}",
                   "default_value": null,
                   "value": "+1-555-123-4567",
                   "normalizedValue": "+1-555-123-4567"
               },
               "companycity": {
                   "id": "33",
                   "label": "City",
                   "alias": "companycity",
                   "type": "text",
                   "group": "core",
                   "object": "company",
                   "is_fixed": "1",
                   "properties": "a:0:{}",
                   "default_value": null,
                   "value": "Anytown",
                   "normalizedValue": "Anytown"
               },
               "companystate": {
                   "id": "34",
                   "label": "State",
                   "alias": "companystate",
                   "type": "region",
                   "group": "core",
                   "object": "company",
                   "is_fixed": "1",
                   "properties": "a:0:{}",
                   "default_value": null,
                   "value": "New York",
                   "normalizedValue": "New York"
               },
               "companyzipcode": {
                   "id": "35",
                   "label": "Zip Code",
                   "alias": "companyzipcode",
                   "type": "text",
                   "group": "core",
                   "object": "company",
                   "is_fixed": "1",
                   "properties": "a:0:{}",
                   "default_value": null,
                   "value": "12345",
                   "normalizedValue": "12345"
               },
               "companycountry": {
                   "id": "36",
                   "label": "Country",
                   "alias": "companycountry",
                   "type": "country",
                   "group": "core",
                   "object": "company",
                   "is_fixed": "1",
                   "properties": "a:0:{}",
                   "default_value": null,
                   "value": "United States",
                   "normalizedValue": "United States"
               },
               "companyname": {
                   "id": "37",
                   "label": "Company Name",
                   "alias": "companyname",
                   "type": "text",
                   "group": "core",
                   "object": "company",
                   "is_fixed": "1",
                   "properties": "a:0:{}",
                   "default_value": null,
                   "value": "Acme Corporation",
                   "normalizedValue": "Acme Corporation"
               },
               "companywebsite": {
                   "id": "38",
                   "label": "Website",
                   "alias": "companywebsite",
                   "type": "url",
                   "group": "core",
                   "object": "company",
                   "is_fixed": "1",
                   "properties": "a:0:{}",
                   "default_value": null,
                   "value": "http://www.acme.com",
                   "normalizedValue": "http://www.acme.com"
               }
           }
       }
   }
}
```

--------------------------------

### Initialize Mautic API Library for Fields

Source: https://github.com/mautic/developer-documentation-new/blob/7.1/docs/rest_api/fields.md

Initialize the Mautic API library and get the context for Contact or Company fields. Ensure you have the Mautic API Library installed and configured with your API credentials and URL.

```php
<?php
use Mautic\MauticApi;
use Mautic\Auth\ApiAuth;

// ...
$initAuth = new ApiAuth();
$auth     = $initAuth->newAuth($settings);
$apiUrl   = "https://example.com";
$api      = new MauticApi();
$assetApi = $api->newApi("assets", $auth, $apiUrl);

// Get Contact field context:
$fieldApi = $api->newApi("contactFields", $auth, $apiUrl);

// Or use 'companyFields' for company fields:
$fieldApi = $api->newApi("companyFields", $auth, $apiUrl);
```

--------------------------------

### Basic services.php Configuration for Autowiring

Source: https://github.com/mautic/developer-documentation-new/blob/7.1/docs/plugins/autowiring.md

This snippet demonstrates a basic `services.php` file structure for a Mautic plugin. It enables autowiring and autoconfiguration for services within the plugin's namespace and excludes specified directories.

```php
<?php

declare(strict_types=1);

use Mautic\CoreBundle\DependencyInjection\MauticCoreExtension;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

return function (ContainerConfigurator $configurator) {
    $services = $configurator->services()
        ->defaults()
        ->autowire()
        ->autoconfigure()
        ->public();

    $excludes = [
        'SomeDirectoryYouWantToExclude',
    ];

    $services->load('MauticPlugin\[YourPluginName]Bundle\', '../')
        ->exclude('../{'.implode(',', array_merge(MauticCoreExtension::DEFAULT_EXCLUDES, $excludes)).'}');
};
```

--------------------------------

### Behavior Action Filter Example

Source: https://github.com/mautic/developer-documentation-new/blob/7.1/docs/rest_api/segments.md

Filter leads based on their behavior actions, specifically by checking if a URL title starts with a given string using the 'startsWith' operator. This is useful for segmenting users who interacted with specific content.

```json
{
    "glue": "and",
    "field": "url_title",
    "object": "behaviors",
    "type": "text",
    "operator": "startsWith",
    "properties": {
        "filter": "acme"
    }
}
```

--------------------------------

### cURL Example with Query Parameters

Source: https://github.com/mautic/developer-documentation-new/blob/7.1/docs/rest_api/stats.md

Demonstrates how to make a GET request to the Stats API using cURL, including how to properly encode array parameters like 'where' for the query string. This is useful for command-line data retrieval.

```bash
curl "https://example.com/api/stats/asset_downloads?where%5B0%5D%5Bcol%5D=id&where%5B0%5D%5Bexpr%5D=eq&where%5B0%5D%5Bval%5D=3"

```

--------------------------------

### Form Validation Start Hook: onValidateStart()

Source: https://github.com/mautic/developer-documentation-new/blob/7.1/docs/form_hooks/validation_hooks.md

The onValidateStart hook is called at the very beginning of the default form validation process. This hook is useful for performing any setup or initial checks before validation commences. It is not called if an onValidate hook returns TRUE.

```javascript
MauticFormCallback['formname'] = {
    onValidateStart: function () {
        // do some custom stuff
    },
};
```

--------------------------------

### Build Test Dependencies

Source: https://github.com/mautic/developer-documentation-new/blob/7.1/docs/testing/e2e_test_suite.md

Build the necessary test dependencies for the Codeception framework. This command prepares the testing environment.

```bash
bin/codecept build
```

--------------------------------

### Initiate Sync Engine Command

Source: https://github.com/mautic/developer-documentation-new/blob/7.1/docs/plugin_integrations/integrations_sync.md

Use this command to start the bidirectional sync process between Mautic and an integration. Specify the integration name and the date range for the sync.

```bash
php bin/console mautic:integrations:sync HelloWorld --start-datetime="2020-01-01 00:00:00" --end-datetime="2020-01-02 00:00:00"
```

--------------------------------

### Send Email Response Example

Source: https://github.com/mautic/developer-documentation-new/blob/7.1/docs/rest_api/emails.md

Example of a successful response when sending an email to segments.

```json
{
    "success": 1,
    "sentCount": 1,
    "failedRecipients": 0
}

```

--------------------------------

### Example Response for Listing Text Messages

Source: https://github.com/mautic/developer-documentation-new/blob/7.1/docs/rest_api/text_messages.md

An example of the JSON response when listing text messages.

```json
{
    "total":1,
    "smses":[
        {
            "isPublished":true,
            "dateAdded":"2016-09-14T12:14:45+00:00",
            "createdBy":1,
            "createdByUser":"Kevin Bulgarelli",
            "dateModified":null,
            "modifiedBy":null,
            "modifiedByUser":null,
            "id":1,
            "name":"Message A",
            "message":"Hello",
            "language":"en",
            "category":null,
            "publishUp":null,
            "publishDown":null,
            "sentCount":0
        }
    ]
}

```

--------------------------------

### List Campaigns using PHP API Client

Source: https://github.com/mautic/developer-documentation-new/blob/7.1/docs/rest_api/campaigns.md

Demonstrates how to fetch a list of campaigns using the Mautic PHP API client. Ensure the API client is properly initialized before use.

```php
<?php
// ...

$campaigns = $campaignApi->getList($searchFilter, $start, $limit, $orderBy, $orderByDir, $publishedOnly, $minimal);

```