Reporting overview
The read side is a thin, cached client over Matomo's Reporting API. It reuses the
host, site_id and token you already configured — a token with at least view
access is required — and posts the token_auth in the request body, never in the
query string, so it does not end up in an access log.
use MatomoAnalytics\Facades\MatomoReports;
$summary = MatomoReports::visitsSummary(['period' => 'day', 'date' => 'today']);
$pages = MatomoReports::topPageUrls(['period' => 'month', 'date' => '2026-01']);
// Anything not covered by a helper:
$goals = MatomoReports::get('Goals.get', ['period' => 'week', 'date' => 'today']);
reporting.default_period and reporting.default_date fill in what you omit, so a
call with no parameters is a valid call.
Failure never throws
Every read returns null on failure and surfaces Matomo's own error envelope through
lastError():
if ($summary === null) {
logger()->warning('Matomo reporting failed: '.MatomoReports::lastError());
}
That is the whole error convention, and it exists because a reporting widget should degrade, not take the page down. A failed call is never cached, so the next request retries rather than serving a cached failure for an hour. Failures also go through the same throttled alerting as tracking.
lastError() is Matomo's own text, and Matomo quotes the request's segment in an error. A
segment such as userId==… or visitIp==… names a person, so the package's own alert
carries the API and the method instead of that text. Where your segments can name someone,
log the method rather than lastError().
Curated helpers
The curated helpers cover the reports most applications actually want, each wrapping a Reporting API method with sensible parameters:
| Helper | Answers |
|---|---|
visitsSummary() | Visits, unique visitors, actions, bounce rate, time on site |
liveCounters($lastMinutes) | Who is on the site right now |
lastVisits($count) | The most recent visits, in detail |
topPageUrls() · topPageTitles() | The most-visited pages, by URL and by title |
entryPageUrls() · exitPageUrls() | The pages visits began and ended on, one row per URL |
siteSearchKeywords() | What visitors searched for |
siteSearchNoResultKeywords() | What visitors searched for and did not find |
transitionsForPageUrl($pageUrl) | How visitors reached one page and where they went from it |
topReferrers() · referrerTypes() | Where visitors came from, and through which channel |
countries() · deviceTypes() · browsers() | Who they are |
goals() · eventCategories() | Conversions and custom events |
customDimension($idDimension) | One custom dimension's values |
contentNames() · contentPieces() | Content-tracking impressions |
Every helper takes the same optional $params array as get(), so you can override
period, date, segment or any report filter on any of them. On the helpers that need a value
of their own it is the second argument, after that value — liveCounters(),
lastVisits(), customDimension(), funnelFlow() and transitionsForPageUrl():
MatomoReports::topPageUrls(['period' => 'week']);
MatomoReports::liveCounters(30, ['period' => 'week']); // not liveCounters(['period' => 'week'])
entryPageUrls() and exitPageUrls() ask for the flat report, so a page comes back as one
row with its full URL rather than inside a folder; pass ['flat' => 0] for the tree.
Anything not in the list is one get() call away — the helpers are a convenience, not
a boundary.
One round-trip for several reports
A dashboard usually needs five reports, not one. bulk() sends them as a single
API.getBulkRequest:
[$visits, $actions] = MatomoReports::bulk([
'VisitsSummary.get',
['method' => 'Actions.get', 'period' => 'week'],
]);
Each entry is either a method name or an array with a method key plus that request's
own parameters, and results come back aligned by index.
A slot is null when the whole bulk call failed, not when one sub-request did. The
{"result":"error"} envelope is detected on the OUTER response — if that fires, every slot
is null and lastError() says why. A sub-request that Matomo reports as failed comes back
as whatever Matomo put in that slot, and an error object is still an object, so it survives
into your data. Check the shape before you use it:
[$visits, $actions] = MatomoReports::bulk([...]);
if (($actions['result'] ?? null) === 'error') {
// this one request failed; $visits may still be good
}
On Matomo Cloud this matters for a second reason: the Reporting API is the endpoint most likely to be throttled, and one bulk request counts once.
Caching
'cache' => [
'enabled' => true,
'store' => env('MATOMO_REPORTING_CACHE_STORE'), // null = default store
'prefix' => 'matomo-analytics:report',
'ttl' => [
'live' => 60, // Live.* realtime counters
'today' => 300, // spans reaching today: today, lastN, the current week, month or year
'recent' => 900, // spans that ended yesterday, and previousN
'historical' => 3600, // fully archived past periods
],
],
The TTL is date-aware, which is the point: last March's numbers will never change
again, so caching them for an hour costs nothing, while a realtime counter cached for an
hour would be a bug. The client picks the bucket from the report and the span it covers:
the date and the period together, so the current month asked for by its first day, a
range that ends today and last7 all take the today bucket.
Invalidate everything at once:
MatomoReports::flushCache();
That is a versioned-prefix bump rather than a key sweep, so it works on every cache store — including the ones that cannot enumerate keys — and it is cheap regardless of how much is cached.
A report is cached under the request Matomo receives, with its host, site, period and date, so two applications or environments that share a cache store never read each other's reports.
Set store to keep report caching off your application's main cache store. Set
enabled to false while debugging a report, so you see Matomo's live answer.
Reports for one tenant's site
An application that counts each tenant on a site of its own, through site_id_resolver, reads
that site's reports through forSite(). It answers the same client for the site you name:
every report, single or bulk, asks Matomo for that site, its cache entries are its own, and the
configured site_id stays where it was.
use MatomoAnalytics\Facades\MatomoReports;
$site = MatomoReports::forSite($tenant->matomo_site_id);
$pages = $site->topPageUrls(['period' => 'month', 'date' => 'today']);
$searches = $site->siteSearchKeywords(['period' => 'month', 'date' => 'today']);
Take the id from the tenant the request belongs to, never from what a user sent. The token reads every site it was granted, so an id from a form or a query string reads another tenant's numbers.
The sites themselves go through SitesClient: create a site when a tenant goes live, change its
name or its addresses when the tenant moves to a domain of its own, and delete it with the
tenant. Creating and deleting a site needs a superuser's token, changing one admin access to it.
use MatomoAnalytics\Contracts\SitesClient;
$sites = app(SitesClient::class);
$id = $sites->create('Help center', ['https://help.example.com']); // the new id, or null
$sites->update($id, urls: ['https://help.shop.example']); // true once Matomo confirms
$sites->delete($id); // with every visit it recorded
A failed call answers null or false and leaves the reason in $sites->lastError(), as the
reporting client does. In a test, bind a double of SitesClient in the container.
Timeouts
reporting.timeout is separate from the tracking timeout and defaults higher — a
report over a long date range legitimately takes longer than a tracking hit. If a
dashboard query times out, raise this rather than the tracking timeout.
Next
- Queries and segments — the fluent builder, filters, and segments.
- Premium plugin reports — thin adapters for the licensed plugins.
matomo:report— run any method from the command line.