matomo-org/matomo-php-tracker

PHP Client for Matomo Analytics Tracking API

The PHP Tracker Client provides all features of the Matomo Javascript Tracker, such as Ecommerce Tracking, Custom Variables, Event Tracking and more.

Documentation and examples

Check out our Matomo-PHP-Tracker developer documentation and Matomo Tracking API guide.

// Required variables
$matomoSiteId = 6;                  // Site ID
$matomoUrl = "https://example.tld"; // Your matomo URL
$matomoToken = "";                  // Your authentication token

// Optional variable
$matomoPageTitle = "";              // The title of the page

// Load object
require_once("MatomoTracker.php");

// Matomo object
$matomoTracker = new MatomoTracker((int)$matomoSiteId, $matomoUrl);

// Set authentication token
$matomoTracker->setTokenAuth($matomoToken);

// Track page view
$matomoTracker->doTrackPageView($matomoPageTitle);

Requirements:

• PHP 8.1 or newer
• JSON extension (json_decode, json_encode)
• cURL or stream extension (to issue the HTTPS request to Matomo)

Installation

Composer

composer require matomo/matomo-php-tracker

Manually

Alternatively, you can download the files and require the Matomo tracker manually:

require_once("MatomoTracker.php");

Error handling and timeouts

By default a tracking request that fails to reach Matomo (DNS, connection or timeout errors) throws a RuntimeException, so if you call the tracker inline in a page you should either wrap it in a try/catch or opt into fail-safe behavior:

$matomoTracker->setExceptionsEnabled(false); // failed requests return false instead of throwing

The default timeouts are intentionally short so a slow or unreachable Matomo cannot block the calling page for long: 5 seconds total and 2 seconds to connect. Raise them for slow endpoints or large synchronous imports:

$matomoTracker->setRequestTimeout(30);         // seconds, total
$matomoTracker->setRequestConnectTimeout(5);   // seconds, connect

Combined, this means an unreachable Matomo throws (or, in fail-safe mode, returns false) after at most a few seconds rather than hanging the request. Bulk tracking (doBulkTrack()) uses a more generous timeout automatically and keeps the queued actions if a batch fails so it can be retried.

Development

Install the development dependencies with Composer and use the provided scripts:

composer install
composer test      # run the PHPUnit test suite
composer phpstan   # run static analysis (PHPStan, max level)
composer phpcs     # check the coding standard (Matomo)
composer phpcbf    # auto-fix coding standard violations

PHPStan and PHP_CodeSniffer are also run for every pull request via GitHub Actions.

License

Released under the BSD License