Matomo Analytics for Laravel

Privacy-first Matomo tracking for Laravel. The package covers both sides of a Matomo integration — the server-side Tracking API and the client-side JavaScript tracker — plus the read-side Reporting API, the GDPR data-subject tools and the Annotations plugin. It works identically against a self-hosted Matomo and Matomo Cloud: only the host differs.

Three properties shape every design decision in it:

• A tracking error never surfaces in your application, and in queue and batch mode the hits are delivered out of band, so tracking does not block a response either. (sync mode sends inline by design — see transmission modes.)
• It is built not to lose hits. Queued jobs retry with escalating backoff; the batch buffer keeps hits until Matomo confirms a 200; a batch that cannot be delivered lands in a dead-letter table you can inspect and re-queue. There is one precondition worth knowing before you pick the redis driver — an instance allowed to evict its keys drops buffered hits with every signal staying green. See reliability.
• It is private by default. Cookieless visitor identification, Do-Not-Track and Sec-GPC honored server-side, URL redaction on by default, and bots and AI crawlers excluded unless you ask for them.

Start here

• Installation — composer require, matomo:install, the two environment variables that switch tracking on, and the connectivity check.
• Configuration — how the published config file relates to the package defaults, which settings belong in .env, and what each block covers.
• Matomo Cloud — the same code path as self-hosted, plus the three Cloud-specific things worth knowing.

Tracking

• Server-side tracking — the Matomo facade, automatic page views through middleware, and how a visitor is identified without cookies.
• Client-side tracking — the @matomoScript snippet, Tag Manager, the opt-out control, and the Content-Security-Policy nonce.
• SPA and soft navigation — virtual page views for Livewire, Inertia and any History-based router.
• Page performance and Web Vitals — Matomo's native page-timing report, and Google's Core Web Vitals as Matomo events.
• Ecommerce · Site search · Custom dimensions and content tracking

Delivery

• Transmission modes — queue, sync and batch, and what changes operationally when you pick one.
• Scaling — where the real ceiling is, the load simulator, and how the package composes with Matomo's QueuedTracking plugin.
• Reliability — retries, throttled alerting, poison batches and the dead-letter queue.

Privacy and gating

• The tracking gate — the single decision point that answers "is this request tracked?", and every reason it can say no.
• Bots and AI crawlers · AI assistants — how the three kinds of AI traffic Matomo distinguishes are each covered.
• Consent and redaction · GDPR requests

Reading data back

• Reporting overview — the MatomoReports facade, the curated helpers, caching and error handling.
• Queries and segments — the fluent query builder, the segment builder and the named-segment registry.
• Premium plugin reports

Reference

• Configuration reference — every key, its environment variable and its shipped default.
• Command reference · Events · Contracts · Database tables

Guides

• Release annotations — mark deploys on the reports timeline.
• Laravel Octane · Testing · Troubleshooting · Upgrading

Requirements

• PHP 8.4+
• Laravel 12 or 13

The package depends on focused illuminate/* components rather than the whole framework, so it stays light in an application that only needs part of Laravel.

License and source

MIT. The source lives at github.com/pushery/matomo-analytics-for-laravel; vulnerabilities go to the security policy rather than a public issue. Built and maintained by PUSHERY.