Developer corner

Target group: Developers

Table of Contents

Objects

A data object is available for use in the PSR-14 events:

JavaScriptCode

The \Brotkrueml\MatomoIntegration\Code\JavaScriptCode object holds a piece of arbitrary JavaScript code used in the BeforeTrackPageViewEvent, AfterTrackPageViewEvent and AddToDataLayerEvent events. This object is necessary to distinguish between a "normal" string and JavaScript code for later embedding.

Example:

$javaScriptCode = new \Brotkrueml\MatomoIntegration\Code\JavaScriptCode(
   '/* some JavaScript code */'
);

The object provides the following method:

__toString(): string: Returns the JavaScript code.

PSR-14 events

To enrich Matomo's JavaScript tracking code with additional calls, PSR-14 events are available. You can draw inspiration from the Use cases chapter.

ModifySiteConfigurationEvent

New in version 2.1.0

This event allows to modify some settings from the site configuration on runtime.

The event provides the following methods:

getRequest(): \Psr\Http\Message\ServerRequestInterface: Get the current PSR-7 request object.

getSiteIdentifier(): string: Get the site identifier.

getUrl(): string: Get the URL.

setUrl(string $url): void: Set a URL.

getSiteId(): int: Get the site ID.

setSiteId(int $siteId): void: Set a site ID.

getTagManagerContainerIds(): array: Get the list of container IDs for the Matomo Tag Manager.

setTagManagerContainerIds(array $containerIds): void: Set a list of container IDs for the Matomo Tag Manager.

Example

The example below adjusts the site ID depending on the current language:

EXT:your_extension/Classes/Matomo/ModifyMatomoSiteId.php

<?php

declare(strict_types=1);

namespace YourVender\YourExtension\Matomo;

use Brotkrueml\MatomoIntegration\Event\ModifySiteConfigurationEvent;
use TYPO3\CMS\Core\Attribute\AsEventListener;

#[AsEventListener(
    identifier: 'your-vendor/your-extension/modify-matomo-site-id',
)]
final readonly class ModifyMatomoSiteId
{
    public function __invoke(ModifySiteConfigurationEvent $event): void
    {
        if ($event->getRequest()->getAttribute('language')->getLanguageId() === 1) {
            // Override the site ID when in another language
            $event->setSiteId(42);
        }
    }
}

EnrichScriptTagEvent

With this event you can add attributes to the surrounding <script> tag. For a concrete usage have a look into the use cases.

The event provides the following methods:

getRequest(): \Psr\Http\Message\ServerRequestInterface: Get the current PSR-7 request object.

setId(string $id): void: Set the id.

setType(string $type): void: Set the type.

addDataAttribute(string $name, string $value = ''): void: Add a data attribute with the $name without the data- prefix. The value is optional, if it is not given or an empty string only the name is rendered.

Example

The example below results in the following script snippet:

<script id="some-id" data-foo="bar" data-qux>/* the tracking code */</script>

The event listener class:

EXT:your_extension/Classes/Matomo/AddAttributesToMatomoScriptTag.php

<?php

declare(strict_types=1);

namespace YourVender\YourExtension\Matomo;

use Brotkrueml\MatomoIntegration\Event\EnrichScriptTagEvent;
use TYPO3\CMS\Core\Attribute\AsEventListener;

#[AsEventListener(
    identifier: 'your-vendor/your-extension/add-attributes-to-matomo-script-tag',
)]
final readonly class AddAttributesToMatomoScriptTag
{
    public function __invoke(EnrichScriptTagEvent $event): void
    {
        // Set the id
        $event->setId('some-id');

        // Add data attributes
        $event->addDataAttribute('foo', 'bar');
        $event->addDataAttribute('qux');
    }
}

BeforeTrackPageViewEvent

This event can be used to add calls before the embedding of the trackPageView code.

This can be helpful when you want to adjust the document title or to add custom dimensions.

The event provides the following methods:

getRequest(): \Psr\Http\Message\ServerRequestInterface: Get the current PSR-7 request object.

addJavaScriptCode(string $code): void: Adds a JavaScript code snippet.

addMatomoMethodCall(string $method, ...$parameters): void: Adds a Matomo method call for the given method and optional parameters. The value can be of type: array, bool, int, float, string or \Brotkrueml\MatomoIntegration\Code\JavaScriptCode.

Example

The example below results in the following code:

// ...
_paq.push(["setDocumentTitle", "Some Document Title"]);
_paq.push(["trackPageView"]);
// ...

or (for illustration of the usage of the \Brotkrueml\MatomoIntegration\Code\JavaScriptCode object):

// ...
function getDocumentTitle { return "Some Document Title"; }
_paq.push(["setDocumentTitle", getDocumentTitle()]);
_paq.push(["trackPageView"]);
// ...

The event listener class:

EXT:your_extension/Classes/Matomo/SetDocumentTitleExample.php

<?php

declare(strict_types=1);

namespace YourVender\YourExtension\Matomo;

use Brotkrueml\MatomoIntegration\Code\JavaScriptCode;
use Brotkrueml\MatomoIntegration\Event\BeforeTrackPageViewEvent;
use TYPO3\CMS\Core\Attribute\AsEventListener;

#[AsEventListener(
    identifier: 'your-vendor/your-extension/set-document-title-example',
)]
final readonly class SetDocumentTitleExample
{
    public function __invoke(BeforeTrackPageViewEvent $event): void
    {
        // Set the document title
        $event->addMatomoMethodCall('setDocumentTitle', 'Some Document Title');

        // OR:
        // Add some JavaScript code
        $event->addJavaScriptCode('function getDocumentTitle { return "Some Document Title"; }');
        // Set the document title
        $event->addMatomoMethodCall('setDocumentTitle', new JavaScriptCode('getDocumentTitle()'));
    }
}

TrackSiteSearchEvent

The event is useful for tracking site search metrics, such as the keyword or the number of results. Especially the number of results can be interesting, since Matomo displays a list of keywords without results.

Further information can be found on the Matomo website:

Important

If this event is used and the keyword is not empty, the default trackPageView call is replaced by a trackSiteSearch call, as recommended by Matomo.

The event provides the following methods:

getRequest(): \Psr\Http\Message\ServerRequestInterface: Get the current PSR-7 request object.

setKeyword(string $keyword): void: Sets the keyword.

setCategory(string|false $category): void: Sets an optional category.

setSearchCount(int|false $searchCount): void: Sets an optional search count.

addCustomDimension(int $id, string $value): void: Adds a custom dimension with the given ID and value.

Example

The example below results in the following code:

// ...
_paq.push(["trackSiteSearch", "some search keyword", false, 42, {"dimension3": "Some custom dimension value"}]);
// ...

The event listener class:

EXT:your_extension/Classes/Matomo/SomeTrackSiteSearchExample.php

<?php

declare(strict_types=1);

namespace YourVender\YourExtension\Matomo;

use Brotkrueml\MatomoIntegration\Event\TrackSiteSearchEvent;
use TYPO3\CMS\Core\Attribute\AsEventListener;

#[AsEventListener(
    identifier: 'your-vendor/your-extension/some-track-site-search-example',
)]
final readonly class SomeTrackSiteSearchExample
{
    public function __invoke(TrackSiteSearchEvent $event): void
    {
        $event->setKeyword('some search keyword');
        $event->setSearchCount(42);
        $event->addCustomDimension(3, 'some custom dimension value');
    }
}

EnrichTrackPageViewEvent

This event can be used to enrich the trackPageView call with a page title and/or a custom dimension only for the page view.

The event provides the following methods:

getRequest(): \Psr\Http\Message\ServerRequestInterface: Get the current PSR-7 request object.

setPageTitle(string $pageTitle): void

Sets the page title.

addCustomDimension(int $id, string $value): void

Adds a custom dimension with the given ID and value.

Example

The example below results in the following code:

// ...
_paq.push(["trackPageView", "Some Page Title", {"dimension3": "Some Custom Dimension Value"}]);
// ...

The event listener class:

EXT:your_extension/Classes/Matomo/SomeEnrichTrackPageViewExample.php

<?php

declare(strict_types=1);

namespace YourVender\YourExtension\Matomo;

use Brotkrueml\MatomoIntegration\Event\EnrichTrackPageViewEvent;
use TYPO3\CMS\Core\Attribute\AsEventListener;

#[AsEventListener(
    identifier: 'your-vendor/your-extension/some-enrich-track-page-view-example',
)]
final readonly class SomeEnrichTrackPageViewExample
{
    public function __invoke(EnrichTrackPageViewEvent $event): void
    {
        // You can set another page title
        $event->setPageTitle('Some Page Title');
        // And/or you can set a custom dimension only for the track page view call
        $event->addCustomDimension(3, 'Some Custom Dimension Value');
    }
}

AfterTrackPageViewEvent

This event can be used to add calls after the embedding of the trackPageView code.

The event provides the following methods:

getRequest(): \Psr\Http\Message\ServerRequestInterface: Get the current PSR-7 request object.

addJavaScriptCode(string $code): void: Adds a JavaScript code snippet.

addMatomoMethodCall(string $method, ...$parameters): void: Adds a Matomo method call for the given method and optional parameters. The value can be of type: array, bool, int, float, string or \Brotkrueml\MatomoIntegration\Code\JavaScriptCode.

Example

The example below results in the following code:

// ...
_paq.push(["trackPageView"]);
_paq.push(["enableHeartBeatTimer", 30]);
// ...

The event listener class:

        EXT:your_extension/Classes/Matomo/EnableHeartBeatTimerWithActiveSecondsExample.php
    

<?php

declare(strict_types=1);

namespace YourVender\YourExtension\Matomo;

use Brotkrueml\MatomoIntegration\Event\AfterTrackPageViewEvent;
use TYPO3\CMS\Core\Attribute\AsEventListener;

#[AsEventListener(
    identifier: 'your-vendor/your-extension/enable-heartbeat-timer-with-active-seconds-example',
)]
final readonly class EnableHeartBeatTimerWithActiveSecondsExample
{
    public function __invoke(AfterTrackPageViewEvent $event): void
    {
        $event->addMatomoMethodCall('enableHeartBeatTimer', 30);
    }
}

AddToDataLayerEvent

With this event you can add variables to the Matomo tag manager data layer.

The event provides the following method:

getRequest(): \Psr\Http\Message\ServerRequestInterface: Get the current PSR-7 request object.

addVariable(string $name, $value): void: Adds a variable with a name and value. The value can be of type: string, int, float or \Brotkrueml\MatomoIntegration\Code\JavaScriptCode.

Example

The example below results in the following code:

var _mtm=window._mtm||[];
_mtm.push({"mtm.startTime": (new Date().getTime()), "event": "mtm.Start", "orderTotal": 4545.45, "orderCurrency": "EUR"});
// ...

The mtm.startTime and event variables are added always by default.

The event listener class:

EXT:your_extension/Classes/Matomo/AddOrderDetailsToDataLayerExample.php

<?php

declare(strict_types=1);

namespace YourVender\YourExtension\Matomo;

use Brotkrueml\MatomoIntegration\Event\AddToDataLayerEvent;
use TYPO3\CMS\Core\Attribute\AsEventListener;

#[AsEventListener(
    identifier: 'your-vendor/your-extension/add-order-details-to-datalayer-example',
)]
final readonly class AddOrderDetailsToDataLayerExample
{
    public function __invoke(AddToDataLayerEvent $event): void
    {
        $event->addVariable('orderTotal', 4545.45);
        $event->addVariable('orderCurrency', 'EUR');
    }
}

Developer corner

Objects

JavaScriptCode

__toString(): string

PSR-14 events

ModifySiteConfigurationEvent

getRequest(): \Psr\Http\Message\ServerRequestInterface

getSiteIdentifier(): string

getUrl(): string

setUrl(string $url): void

getSiteId(): int

setSiteId(int $siteId): void

getTagManagerContainerIds(): array

setTagManagerContainerIds(array $containerIds): void

Example

EnrichScriptTagEvent

getRequest(): \Psr\Http\Message\ServerRequestInterface

setId(string $id): void

setType(string $type): void

addDataAttribute(string $name, string $value = ''): void

Example

BeforeTrackPageViewEvent

getRequest(): \Psr\Http\Message\ServerRequestInterface

addJavaScriptCode(string $code): void

addMatomoMethodCall(string $method, ...$parameters): void

Example

TrackSiteSearchEvent

getRequest(): \Psr\Http\Message\ServerRequestInterface

setKeyword(string $keyword): void

setCategory(string|false $category): void

setSearchCount(int|false $searchCount): void

addCustomDimension(int $id, string $value): void

Example

EnrichTrackPageViewEvent

getRequest(): \Psr\Http\Message\ServerRequestInterface

setPageTitle(string $pageTitle): void

addCustomDimension(int $id, string $value): void

Example

AfterTrackPageViewEvent

getRequest(): \Psr\Http\Message\ServerRequestInterface

addJavaScriptCode(string $code): void

addMatomoMethodCall(string $method, ...$parameters): void

Example

AddToDataLayerEvent

getRequest(): \Psr\Http\Message\ServerRequestInterface

addVariable(string $name, $value): void

Example