PHPackages                             pagemachine/matomo-tracking - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. pagemachine/matomo-tracking

ActiveLibrary[API Development](/categories/api)

pagemachine/matomo-tracking
===========================

Server-side Matomo tracking API with emphasis on privacy: consentless tracking, GDPR/TDDDG-compliant, respects DNT/GPC

1.2.0(1y ago)011.4k↓14.4%[2 PRs](https://github.com/pagemachine/matomo-tracking/pulls)1GPL-3.0-or-laterPHPPHP ^8.1CI passing

Since Apr 4Pushed 2mo ago1 watchersCompare

[ Source](https://github.com/pagemachine/matomo-tracking)[ Packagist](https://packagist.org/packages/pagemachine/matomo-tracking)[ RSS](/packages/pagemachine-matomo-tracking/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (4)Dependencies (15)Versions (8)Used By (1)

Matomo Tracking API
===================

[](#matomo-tracking-api)

Server-side tracking of actions (e.g. page views) in [Matomo](https://matomo.org)using the [Matomo Tracking HTTP API](https://developer.matomo.org/api-reference/tracking-api).

Features
--------

[](#features)

- Framework-agnostic, uses [PSR-7: HTTP message interfaces](https://www.php-fig.org/psr/psr-7), [PSR-17: HTTP Factories](https://www.php-fig.org/psr/psr-17) and [PSR-18: HTTP Client](https://www.php-fig.org/psr/psr-18)
- Container/dependency injection friendly
- Track page views from server requests
- Track actions without requests
- Track visitor IP address (requires Matomo Auth Token)
- Attributes for tracking of Matomo Site Id, URL, etc.
- Add custom attributes

### Privacy by design

[](#privacy-by-design)

- Visitor IDs are random
- No cookies are set or forwarded
- Action attributes are sent to Matomo via `POST` to prevent them from showing up in access logs (thus no Log Analytics)
- Respects [Do Not Track](https://www.w3.org/TR/tracking-dnt/#dnt-header-field)
- Respects [Global Privacy Control](https://w3c.github.io/gpc/)

Installation
------------

[](#installation)

```
composer require pagemachine/matomo-tracking

```

Usage
-----

[](#usage)

Actions can be tracked with the `Matomo` class. Make sure you have implementations for `UriFactoryInterface`, `RequestFactoryInterface`, `ClientInterface` and `LoggerInterface`.

*You should configure the HTTP client with a sane timeout.* This ensures pages load quickly in case a Matomo instance is not responding. Tracking will be skipped in this case.

In case of most frameworks the dependency injection container will cover most dependencies and you only need to manually configure the URL of your Matomo instance. E.g. with Symfony:

```
services:
  Pagemachine\MatomoTracking\Matomo:
    arguments:
      $uri: '%env(MATOMO_URL)%'
```

Then have `Matomo` injected:

```
use Pagemachine\MatomoTracking\Matomo;

final class Example
{
    public function __construct(
        private readonly Matomo $matomo,
    ) {}

    public function someAction(): void
    {
        $this->matomo->track(...);
    }
}
```

Alternatively use standalone solutions like `guzzlehttp/guzzle`, `guzzlehttp/psr7`and some useful logger or the PSR `NullLogger`:

```
use GuzzleHttp\Client;
use GuzzleHttp\Psr7\HttpFactory;
use GuzzleHttp\RequestOptions;
use Pagemachine\MatomoTracking\Matomo;
use Pagemachine\MatomoTracking\Tracking\ActionFactory;
use Pagemachine\MatomoTracking\Tracking\ActionTracker;
use Psr\Log\NullLogger;

$matomoUrl = 'https://...';
$httpFactory = new HttpFactory();

$matomo = new Matomo(
    $matomoUrl,
    new ActionFactory(),
    new ActionTracker(
        $httpFactory,
        $httpFactory,
        new Client([
            RequestOptions::TIMEOUT => 3,
        ]),
        new NullLogger(),
    ),
    new NullLogger(),
);

$matomo->track(...);
```

### Server requests

[](#server-requests)

A PSR-7 `ServerRequestInterface` can directly be tracked as page view:

```
use Pagemachine\MatomoTracking\Matomo;
use Pagemachine\MatomoTracking\Tracking\Attributes\ActionName;
use Pagemachine\MatomoTracking\Tracking\Attributes\SiteId;
use Psr\Http\Message\ServerRequestInterface;

final class Example
{
    public function __construct(
        private readonly Matomo $matomo,
    ) {}

    public function someAction(ServerRequestInterface $request): void
    {
        // Url attribute is determined from request
        $request = $request->withAttribute('matomo.attributes', [
            new SiteId(1),
            new ActionName('Some action'),
        ]));

        $this->matomo->track($request);
    }
}
```

As shown the custom `matomo.attributes` request attribute can be set for tracking [attributes](#attributes).

By default URLs (current, referrer) and client info (user agent, language) are determined from the server request.

### Actions

[](#actions)

Aside from PSR-7 server requests, actions not directly related to a request can also be tracked. Use the `ActionFactoryInterface` (frameworks) or the `ActionFactory` (standalone) to track an action with [attributes](#attributes):

```
use Pagemachine\MatomoTracking\Matomo;
use Pagemachine\MatomoTracking\Tracking\Attributes\ActionName;
use Pagemachine\MatomoTracking\Tracking\Attributes\SiteId;
use Pagemachine\MatomoTracking\Tracking\Attributes\Url;

final class Example
{
    public function __construct(
        private readonly Matomo $matomo,
        private readonly ActionFactoryInterface $actionFactory,
    ) {}

    public function someAction(): void
    {
        $action = $this->actionFactory->createAction()
            ->withAttribute(new SiteId(1))
            ->withAttribute(new Url('https://example.org/demo'))
            ->withAttribute(new ActionName('Demo Page'));

        $this->matomo->track($action);
    }
}
```

You can also create an action from a PSR-7 `ServerRequestInterface` if desired:

```
use Pagemachine\MatomoTracking\Matomo;
use Pagemachine\MatomoTracking\Tracking\Attributes\ActionName;
use Pagemachine\MatomoTracking\Tracking\Attributes\SiteId;
use Psr\Http\Message\ServerRequestInterface;

final class Example
{
    public function __construct(
        private readonly Matomo $matomo,
        private readonly ActionFactoryInterface $actionFactory,
    ) {}

    public function someAction(ServerRequestInterface $request): void
    {
        // Url attribute is determined from request
        $action = $this->actionFactory->createActionFromRequest($request)
            ->withAttribute(new SiteId(1))
            ->withAttribute(new ActionName('Demo Page'));

        $this->matomo->track($action);
    }
}
```

### Action factories

[](#action-factories)

If there are additional attributes which should be added to actions by default, you can add a custom `ActionFactoryInterface`. This should wrap or [decorate](https://symfony.com/doc/current/service_container/service_decoration.html)the default `ActionFactory` to ensure all default attributes are added:

```
use Pagemachine\MatomoTracking\Tracking\ActionFactoryInterface;
use Pagemachine\MatomoTracking\Tracking\ActionInterface;
use Psr\Http\Message\ServerRequestInterface;

final class ExampleActionFactory implements ActionFactoryInterface
{
    public function __construct(
        private readonly ActionFactoryInterface $decorated,
    ) {}

    public function createAction(): ActionInterface
    {
        $action = $this->decorated->createAction()
            ->withAttribute(...);

        return $action;
    }

    public function createActionFromRequest(ServerRequestInterface $serverRequest): ActionInterface
    {
        $action = $this->decorated->createActionFromRequest($serverRequest)
            ->withAttribute(...);

        return $action;
    }
}
```

This pattern can be used to add the mandatory `SiteId` attribute to all tracked actions.

### Attributes

[](#attributes)

Attributes contain tracking values and cover one or more of the [Matomo Tracking HTTP API](https://developer.matomo.org/api-reference/tracking-api)parameters:

AttributeMatomo API parameters`ActionName``action_name``ApiVersion` (\*)`apiv``AuthToken``token_auth``BotTracking``bots``CustomAction``ca``Download``download`, `url`, `ca``DownloadUrl``download``Language``lang``NoResponse` (\*)`send_image``Random` (\*)`rand``Recording` (\*)`rec``ReferrerUrl``urlref``Search``search`, `search_count`, `search_cat`, `ca``SearchCategory``search_cat``SearchKeyword``search``SearchResultCount``search_count``SiteId``idsite``Url``url``UserAgent``ua``VisitorId``_id``VisitorIpAddress``cip`(Attributes marked with \* are added internally and always sent.)

You **must** at least add a `SiteId` attribute for tracking in Matomo. All other attributes may be used on demand.

Some attributes like `VisitorIpAddress` require an auth token which must be provided with the `AuthToken` attribute. See [Matomo Tracking HTTP API: Other parameters](https://developer.matomo.org/api-reference/tracking-api#other-parameters-require-authentication-via-token_auth)for details when an auth token is required.

#### Custom attributes

[](#custom-attributes)

Custom attributes can be added by implementing the `AttributeInterface`:

```
use Pagemachine\MatomoTracking\Tracking\AttributeInterface;

final class ExampleDimension implements AttributeInterface
{
    public function __construct(private string $example) {}

    public function toParameters(): iterable
    {
        return ['dimension1' => $this->example];
    }
}
```

The keys of the iterable (`array`, `\Generator`, etc.) returned by `toParameters()`must be parameters of the [Matomo Tracking HTTP API](https://developer.matomo.org/api-reference/tracking-api).

###  Health Score

42

—

FairBetter than 90% of packages

Maintenance70

Regular maintenance activity

Popularity26

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity51

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 96.7% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~8 days

Total

4

Last Release

383d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/10812548?v=4)[Pagemachine AG](/maintainers/pagemachine)[@pagemachine](https://github.com/pagemachine)

---

Top Contributors

[![mbrodala](https://avatars.githubusercontent.com/u/5037116?v=4)](https://github.com/mbrodala "mbrodala (29 commits)")[![renovate[bot]](https://avatars.githubusercontent.com/in/2740?v=4)](https://github.com/renovate[bot] "renovate[bot] (1 commits)")

---

Tags

dntgdprgpcmatomoprivacytdddgtracking

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan, Rector

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/pagemachine-matomo-tracking/health.svg)

```
[![Health](https://phpackages.com/badges/pagemachine-matomo-tracking/health.svg)](https://phpackages.com/packages/pagemachine-matomo-tracking)
```

###  Alternatives

[sylius/sylius

E-Commerce platform for PHP, based on Symfony framework.

8.4k5.6M651](/packages/sylius-sylius)[theodo-group/llphant

LLPhant is a library to help you build Generative AI applications.

1.5k311.5k5](/packages/theodo-group-llphant)[swisnl/json-api-client

A PHP package for mapping remote JSON:API resources to Eloquent like models and collections.

211473.2k12](/packages/swisnl-json-api-client)[wordpress/php-ai-client

A provider agnostic PHP AI client SDK to communicate with any generative AI models of various capabilities using a uniform API.

26236.6k14](/packages/wordpress-php-ai-client)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

245.2k](/packages/aedart-athenaeum)[phpro/http-tools

HTTP tools for developing more consistent HTTP implementations.

28137.8k](/packages/phpro-http-tools)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)