Site search

Matomo's site-search report tells you what people expected to find. The searches that returned nothing are the most actionable rows in it, so the API makes a zero count explicit rather than something you have to remember to omit.

From your search handler

use MatomoAnalytics\Facades\Matomo;

Matomo::siteSearch('invoices', category: 'docs', count: 7);

keyword is required; category scopes the search (a section, a filter, a tab) and count is the number of results.

Reading the keyword straight off the request saves repeating yourself:

Matomo::searchFromRequest(keywordKey: 'q', categoryKey: 'category', count: $results->total());

Both the keyword and the category come from the query string; if the keyword parameter is missing or blank, nothing is tracked — so this is safe to call on a controller that also renders an empty search page.

Track the no-result searches

Matomo::siteSearch($keyword, count: 0);

Passing 0 is not the same as passing nothing. A count of 0 records a search that found nothing, which is what populates Matomo's no-result report. Omitting the count records a search whose result count is unknown.

Automatically, per route

Route::get('/search', SearchController::class)->middleware('matomo.search:q,category');

The middleware arguments are the query-parameter names — the first is the keyword key, the second (optional) the category key. It records a search on any GET response below status 400 — so a 3xx redirect counts, not only a 2xx — and only when the keyword parameter is actually present, so it does not fire on the bare search page.

The middleware cannot know the result count, because it runs after the response is built and does not inspect it. If you want counts — and you do want them, for the no-result report — call Matomo::siteSearch() or Matomo::searchFromRequest() from your handler instead, where the count is available.

What reaches Matomo

The keyword becomes Matomo's search term, the category its search category, and the count its result count. A hit with a search term is a search action rather than a page view, so it appears in the site-search reports instead of inflating your page list.

Like every hit, it passes through the tracking gate. Note that URL redaction applies to the tracked URL, not to the search term — a search keyword is the data you asked to collect. If your search box can receive sensitive input, do not track it.