---
title: "Developer corner"
manual: "Matomo Integration"
version: "main"
permalink: "https://docs.typo3.org/permalink/brotkrueml/typo3-matomo-integration:developer@main"
source: "Developer/Index.rst"
rendered: "2026-09-22T16:58:05+00:00"
---

# Developer corner {#developer}

Target group: **Developers**

**Table of Contents**

-   [Objects](https://docs.typo3.org/permalink/brotkrueml/typo3-matomo-integration:objects@main)
-   [PSR-14 events](https://docs.typo3.org/permalink/brotkrueml/typo3-matomo-integration:psr-14-events@main)

## Objects {#objects}

A data object is available for use in the [PSR-14 events](https://docs.typo3.org/permalink/brotkrueml/typo3-matomo-integration:psr14-events@main):

### JavaScriptCode {#object-javascriptcode}

The `\Brotkrueml\MatomoIntegration\Code\JavaScriptCode` object holds a piece
of arbitrary JavaScript code used in the [BeforeTrackPageViewEvent](https://docs.typo3.org/permalink/brotkrueml/typo3-matomo-integration:beforetrackpageviewevent@main),
[AfterTrackPageViewEvent](https://docs.typo3.org/permalink/brotkrueml/typo3-matomo-integration:aftertrackpageviewevent@main) and [AddToDataLayerEvent](https://docs.typo3.org/permalink/brotkrueml/typo3-matomo-integration:addtodatalayerevent@main) events. This
object is necessary to distinguish between a "normal" string and JavaScript code
for later embedding.

Example:

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

The object provides the following method:

-   **\_\_toString(): string**

    Returns the JavaScript code.

## PSR-14 events {#psr14-events}

To enrich Matomo's JavaScript tracking code with additional calls,
PSR-14 events are available. You can draw inspiration from the [Use cases](https://docs.typo3.org/permalink/brotkrueml/typo3-matomo-integration:use-cases@main)
chapter.

> [!NOTE]
> **See also**
>
> You can find more information about PSR-14 events in the blog article
> [PSR-14 Events in TYPO3](https://usetypo3.com/psr-14-events.html)
> and the official [TYPO3 documentation](https://docs.typo3.org/m/typo3/reference-coreapi/14.3/en-us/ApiOverview/Events/EventDispatcher/Index.html#EventDispatcher).

### ModifySiteConfigurationEvent {#modifysiteconfigurationevent}

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 {#example}

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

**EXT:your_extension/Classes/Matomo/ModifyMatomoSiteId.php**

```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 {#enrichscripttagevent}

With this event you can add attributes to the surrounding `<script>` tag.
For a concrete usage have a look into the
[use cases](https://docs.typo3.org/permalink/brotkrueml/typo3-matomo-integration:use-case-extend-script-tag@main).

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 {#example-1}

The example below results in the following script snippet:

```html
<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
<?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 {#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](https://developer.matomo.org/guides/tracking-javascript-guide#custom-page-title) or to add
[custom dimensions](https://developer.matomo.org/guides/tracking-javascript-guide#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 {#example-2}

The example below results in the following code:

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

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

```js
// ...
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
<?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 {#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:

-   [Site search tracking and reporting](https://matomo.org/guide/reports/site-search/)
-   [JavaScript Tracking Client - Internal search tracking](https://developer.matomo.org/guides/tracking-javascript-guide#internal-search-tracking)

> [!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 {#example-3}

The example below results in the following code:

```js
// ...
_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
<?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 {#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](https://developer.matomo.org/guides/tracking-javascript-guide#tracking-a-custom-dimension-for-one-specific-action-only).

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 {#example-4}

The example below results in the following code:

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

The event listener class:

**EXT:your_extension/Classes/Matomo/SomeEnrichTrackPageViewExample.php**

```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 {#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 {#example-5}

The example below results in the following code:

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

The event listener class:

**EXT:your_extension/Classes/Matomo/EnableHeartBeatTimerWithActiveSecondsExample.php**

```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 {#addtodatalayerevent}

With this event you can add variables to the Matomo tag manager [data layer](https://developer.matomo.org/guides/tagmanager/datalayer).

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 {#example-6}

The example below results in the following code:

```js
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
<?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');
    }
}

```