Pagemetrics for Matomo

Pagemetrics for Matomo adds privacy-friendly, server-side analytics to WordPress by
leveraging the pagemachine/matomo-tracking PHP library. When enabled, the
plugin sends page view and optional download events from your WordPress site
directly to a Matomo instance without loading Matomo’s JavaScript tracker.

Key benefits:

• Track page views on the server with full control over attributes such as title, URL and referrer.
• Optional download tracking rewrites file links and records the click before redirecting visitors.
• Multisite aware – network admins can define defaults, individual sites can override them.
• Respects Do Not Track and Global Privacy Control headers through the underlying library.
• Logs issues to the WordPress debug log when WP_DEBUG is enabled.

Looking for expert help with Matomo or server-side tracking? Pagemachine offers
consulting, implementation and ongoing support via our Pagemetrics solution.
More info: Pagemetrics.eu

Developer Hooks

• pm_matomo_tracking_should_track_request — Return false to skip tracking for the current request.
• pm_matomo_tracking_should_rewrite_downloads — Return false to keep original download URLs for the current post.
• pm_matomo_tracking_is_download_url — Decide whether a specific URL should be rewritten (receives URL and default extension list).
• pm_matomo_tracking_download_extensions — Adjust the list of file extensions that count as downloads.
• pm_matomo_tracking_download_url — Customize the generated redirect URL used for download tracking.
• pm_matomo_tracking_download_redirect_status — Change the HTTP status code used when redirecting to the original file.
• pm_matomo_tracking_log_message — Listen to debug messages emitted while WP_DEBUG is enabled.

Example usages

// Skip tracking for administrators.
add_filter('pm_matomo_tracking_should_track_request', static function ($shouldTrack) {
    return current_user_can('manage_options') ? false : $shouldTrack;
});

// Keep original download URLs on the privacy policy page.
add_filter('pm_matomo_tracking_should_rewrite_downloads', static function ($shouldRewrite) {
    return is_page('privacy-policy') ? false : $shouldRewrite;
});

// Force CDN assets to be treated as downloads.
add_filter('pm_matomo_tracking_is_download_url', static function ($decision, $url) {
    return str_contains($url, 'cdn.example.com/assets/') ? true : $decision;
}, 10, 2);

// Add extra file types to download tracking.
add_filter('pm_matomo_tracking_download_extensions', static function ($extensions) {
    $extensions = array_merge($extensions, ['svg', 'heic']);
    return array_unique($extensions);
});

// Append a checksum to rewritten download URLs.
add_filter('pm_matomo_tracking_download_url', static function ($trackingUrl, $target, $label) {
    $checksum = substr(hash('sha256', $target . $label), 0, 12);
    return add_query_arg('pm_checksum', $checksum, $trackingUrl);
}, 10, 3);

// Use a 307 redirect instead of the default 302.
add_filter('pm_matomo_tracking_download_redirect_status', static function () {
    return 307;
});

// Forward debug messages to the PHP error log while developing.
add_action('pm_matomo_tracking_log_message', static function ($level, $message) {
    if (!defined('WP_DEBUG') || WP_DEBUG !== true) {
        return;
    }

    // phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_error_log
    error_log(sprintf('[Pagemetrics for Matomo][%s] %s', strtoupper((string) $level), $message));
}, 10, 2);

1. Upload the pagemetrics-for-matomo plugin directory (including the bundled vendor/
   folder) to your site’s wp-content/plugins path.
2. Activate the plugin through the Plugins → Pagemetrics for Matomo screen in WordPress.
3. Open Settings → Pagemetrics for Matomo and configure:
   • Matomo URL (e.g. https://matomo.example.com/)
   • Default Matomo site ID
   • Optional auth token (required for IP tracking and other privileged attributes)
   • HTTP timeout for Matomo requests
   • Download tracking toggle, if you want the plugin to rewrite file links automatically
4. (Multisite) Network administrators can define defaults under Network Admin → Settings → Pagemetrics for Matomo. Individual sites can override those values on their local settings page.

The plugin starts sending data as soon as the Matomo URL and site ID are set.

1. 

   Pagemetrics for Matomo settings

1.0.0

• Initial release with server-side page view tracking, optional download tracking and multisite support.