What does it do? 

The extension integrates Matomo Analytics easily into TYPO3. The extension supports Matomo 5.

The extension takes the Content Security Policy (CSP) into account: a nonce attribute is added to the script tag, if the feature is enabled for frontend.

When to use this extension 

This extension is useful if you want to add further Matomo method calls dependent on certain conditions — such as custom dimensions or setting the user id. Another option is to enable the Matomo tag manager and add data layer variables. PSR-14 events are available for these purposes. Also have a look at the use cases.

When not to use this extension 

If you only use Matomo's default tracking code or have only static values for additional Matomo method calls, insert the JavaScript snippet directly via TypoScript or the Fluid template.

Limitation 

This extension can only embed one tracking code for one Matomo instance. If you have to add multiple tracking codes for one or more Matomo instances you cannot use this extension and have to do it on your own.

Screenshots 

Release management 

This extension uses semantic versioning which basically means for you, that

• Bugfix updates (for example, 1.0.0 => 1.0.1) just includes small bug fixes or security-relevant stuff without breaking changes.
• Minor updates (for example, 1.0.0 => 1.1.0) includes new features and smaller tasks without breaking changes.
• Major updates (for example, 1.0.0 => 2.0.0) breaking changes which can be refactorings, features or bug fixes.

The changes between the different versions can be found in the changelog.

Site configuration 

To configure the extension, go to Site Management > Sites and select the appropriate site configuration. Click on the Matomo Integration tab:

Objects 

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

$javaScriptCode = new \Brotkrueml\MatomoIntegration\Code\JavaScriptCode(
   '/* some 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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Page types as custom dimension 

Depending on the URL structure, it is not easy to accumulate page views for one or more sections on a website. However, you can use an "action" custom dimension to measure these sections (such as "Blog", "Jobs", "Videos").

In this use case, a page type is set for a specific page when a configured section is available in the root line. The page type should only be available for the trackPageView call, so we implement an event listener based on the EnrichTrackPageViewEvent event.

The given use case results in the following code when the current page id or a parent page id is 167:

// ...
_paq.push(["trackPageView", "", {"dimension2": "Blog"}]);
// ...

1. The event listener

   To separate the configuration from the implementation, the ID of the custom dimension and the configuration of the page types are also injected.

   The $pageTypes argument is a simple associative array with the page ID of the parent page of a section as the key and the value of the custom dimension as the value of the array.

   EXT:your_extension/Classes/EventListener/AddPageTypeToMatomoTracking.php

   <?php
   declare(strict_types=1);
   
   namespace YourVender\YourExtension\EventListener;
   
   use Brotkrueml\MatomoIntegration\Event\EnrichTrackPageViewEvent;
   use TYPO3\CMS\Frontend\Controller\TypoScriptFrontendController;
   
   final class AddPageTypeToMatomoTracking
   {
      private int $customDimensionId;
      private array $pageTypes;
   
      public function __construct(
         int $customDimensionId,
         array $pageTypes
      ) {
         $this->customDimensionId = $customDimensionId;
         $this->pageTypes = $pageTypes;
      }
   
      public function __invoke(EnrichTrackPageViewEvent $event): void
      {
         $rootLine = $event->getRequest()->getAttribute('frontend.controller')->rootLine;
         $pageIds = array_keys($this->pageTypes);
         $hits = array_filter(
            $rootLine,
            static fn (array $page): bool => in_array($page['uid'], $pageIds)
         );
         if ($hits === []) {
            return;
         }
   
         $pageType = $this->pageTypes[current($hits)['uid']];
         $event->addCustomDimension($this->customDimensionId, $pageType);
      }
   }

   Copied!

2. Registration of the event listener

   We need to inject the custom dimension ID and the page types configuration into the event listener:

   EXT:your_extension/Configuration/Services.yaml

   YourVender\YourExtension\EventListener\AddPageTypeToMatomoTracking:
      arguments:
         $customDimensionId: 2
         $pageTypes:
            # key: parent page ID, value: value to set for the custom dimension
            167: Blog
            218: Jobs
            112: Videos
            # ... and possibly some more types
      tags:
         - name: event.listener
           identifier: 'your-ext/addPageTypeToMatomoTracking'

   Copied!

Some more ideas how to determine the page type:

• Set the Matomo page type dependent on the TYPO3 page type.
• Use a separate field in the page properties to select the Matomo page type.

Colour scheme as custom dimension 

If you provide your page with a light and a dark colour scheme, it might be interesting to see how many visitors prefer which colour scheme. This can be analysed in Matomo with a "visit" custom dimension.

In contrast to the use case above, where the custom dimension should only be used for tracking a page view, this custom dimension can be defined "globally" so we can use the BeforeTrackPageViewEvent event.

The given use case results in the following code:

// ...
_paq.push(["setCustomDimension", 1, window.matchMedia&&window.matchMedia("(prefers-color-scheme:dark)").matches?"dark":"light"]);
_paq.push(["trackPageView"]);
// ...

1. The event listener

   The event provides an addMatomoMethodCall() method. With this method you can insert any JavaScript code, so be careful what you do. In this example, we use the window.matchMedia() function to get the colour scheme currently in use

   As in the use case above, the ID of the custom dimension is injected via dependency injection.

   EXT:your_extension/Classes/EventListener/AddColourSchemeToMatomoTracking.php

   <?php
   declare(strict_types=1);
   
   namespace YourVendor\YourExtension\EventListener;
   
   use Brotkrueml\MatomoIntegration\Code\JavaScriptCode;
   use Brotkrueml\MatomoIntegration\Event\BeforeTrackPageViewEvent;
   
   final class AddColourSchemeToMatomoTracking
   {
      private int $customDimensionId;
   
      public function __construct(int $customDimensionId)
      {
         $this->customDimensionId = $customDimensionId;
      }
   
      public function __invoke(BeforeTrackPageViewEvent $event): void
      {
         $event->addMatomoMethodCall(
            'setCustomDimension',
            $this->customDimensionId,
            new JavaScriptCode('window.matchMedia&&window.matchMedia("(prefers-color-scheme:dark)").matches?"dark":"light"')
         );
      }
   }

   Copied!

2. Registration of the event listener

   EXT:your_extension/Configuration/Services.yaml

   YourVendor\YourExtension\EventListener\AddColourSchemeToMatomoTracking:
      arguments:
         $customDimensionId: 1
      tags:
         - name: event.listener
           identifier: 'your-ext/addColourSchemeToMatomoTracking'

   Copied!

Remove person-related parts from URL 

In one project we have person-related parts in the URL, namely tokens. They are used after submitting a form to request access to downloads or videos. These tokens are unique and can be used to identify a user through other sources and retrieve their Matomo visit data.

To be compliant with the GDPR and to simplify the analysis of URLs (the token is not needed here), the token is stripped from the URL. This can be achieved by setting a custom URL and the BeforeTrackPageViewEvent event of this extension.

The given use case results in the following code. The original URL is something like https://example.com/downloads/detail/some-download/hz6dFgz9/, where hz6dFgz9 is the token to be removed from the logged URL.

// ...
_paq.push(["setCustomUrl", "https://example.com/downloads/detail/some-download/"]);
_paq.push(["trackPageView"]);
// ...

1. The event listener

   The TYPO3 request object returns the information of the current URL, so the last part of the URL must be removed and set for Matomo's setCustomUrl method call.

   EXT:your_extension/Classes/EventListener/RemoveTokenFromUrlForMatomoTracking.php

   <?php
   declare(strict_types=1);
   
   namespace YourVendor\YourExtension\EventListener;
   
   use Brotkrueml\MatomoIntegration\Event\BeforeTrackPageViewEvent;
   use Psr\Http\Message\ServerRequestInterface;
   
   final class RemoveTokenFromUrlForMatomoTracking
   {
      public function __invoke(BeforeTrackPageViewEvent $event)
      {
         $request = $event->getRequest();
         if (!isset($request->getQueryParams()['tx_myext']['token']) {
            return;
         }
   
         $uri = $request->getUri();
         $pathParts = explode('/', $uri->getPath());
         // The path ends with a slash, which we want to preserve, so we
         // need to remove the second last part (which is the token)
         unset($pathParts[count($pathParts) - 2]);
         $tokenRemovedUri = $uri->withPath(implode('/', $pathParts));
   
         $event->addMatomoMethodCall('setCustomUrl', (string)$tokenRemovedUri);
      }
   }

   Copied!

2. Registration of the event listener

   EXT:your_extension/Configuration/Services.yaml

   YourVendor\YourExtension\EventListener\RemoveTokenFromUrlForMatomoTracking:
      tags:
         - name: event.listener
           identifier: 'your-ext/removeTokenFromUrlForMatomoTracking'

   Copied!

Extending the script tag 

Using tracking tools like Matomo within the European Union need special treatments in order to let the customer consent and agree with the tracking. Although Matomo respects the browser's "Do not track" setting, not everyone is aware of it.

Some GDPR tools like klaro.js require special attribute settings within the script tag in order to work.

1. The event listener

   Before the script tag is rendered the event EnrichScriptTagEvent dispatched from the injector. This events allow to register an id, a type and add additional data attributes.

   EXT:your_extension/Classes/EventListener/PrepareScriptTagForKlaroJs.php

   <?php
   declare(strict_types=1);
   
   namespace YourVendor\YourExtension\EventListener;
   
   use Brotkrueml\MatomoIntegration\Event\EnrichScriptTagEvent;
   
   final class PrepareScriptTagForKlaroJs
   {
      public function __invoke(EnrichScriptTagEvent $event)
      {
         $event->setType('text/plain');
         $event->addDataAttribute('type', 'application/javascript');
         $event->addDataAttribute('name', 'matomo');
      }
   }

   Copied!

2. Registration of the event listener

   EXT:your_extension/Configuration/Services.yaml

   YourVendor\YourExtension\EventListener\PrepareScriptTagForKlaroJs:
      tags:
         - name: event.listener
           identifier: 'your-ext/prepare-script-for-klaro-js'

   Copied!

Add site search metrics 

When offering a site search, the main thing you want to know is what users are searching for. Also worth knowing are, for example, the search terms without results or the query time for a search phrase. The blog post Display search metrics from TYPO3 extension ke_search in Matomo illustrates how to achieve this within the extension ke_search. The article can also serve as a blueprint for other search extensions.

Unreleased 

3.0.2 - 2026-01-28 

3.0.1 - 2026-01-28 

3.0.0 - 2025-11-26 

2.4.1 - 2026-01-28 

2.4.0 - 2025-09-17 

Documentation improvements

2.3.0 - 2024-11-25 

2.2.0 - 2024-06-11 

2.1.1 - 2024-05-22 

2.1.0 - 2024-04-19 

2.0.0 - 2024-02-09 

1.8.0 - 2023-11-19 

1.7.0 - 2023-07-31 

1.6.0 - 2023-05-21 

1.5.1 - 2023-04-01 

1.5.0 - 2022-11-06 

1.4.0 - 2022-10-05 

1.3.2 - 2022-06-13 

1.3.1 - 2022-04-07 

1.3.0 - 2022-02-15 

1.2.0 - 2022-02-02 

1.1.0 - 2021-10-13 

1.0.1 - 2021-09-28 

1.0.0 - 2021-08-30 

Initial release

From version 1.x to version 2.0 

The setting matomoIntegrationTagManagerContainerId in the site configuration has been changed to matomoIntegrationTagManagerContainerIds to reflect that it can hold multiple container IDs since version 1.6.0.

Migration: Search the YAML files of your site configuration(s) for this string and adjust it accordingly.