Skip to main content

GDPR data-subject requests

"Right to be forgotten" and access requests are handled through Matomo's PrivacyManager API. You identify a person with a segment — a userId, a visitIp, anything Matomo can segment on — and then export or erase every matching visit.

use MatomoAnalytics\Facades\MatomoGdpr;

MatomoGdpr::findDataSubjects('visitIp==203.0.113.7'); // preview the matching visits
MatomoGdpr::exportAll('userId==alice@example.com'); // export every visit of the subject
MatomoGdpr::forget('userId==alice@example.com'); // erase; returns deletion counts

These operations need an admin-access token. The read or tracking token is usually not enough. They are also never cached — a deletion that returned a cached answer would be worse than useless.

What forget() erases, and where​

Two places, and the second one is easy to forget because it is yours:

  • At Matomo, through PrivacyManager.deleteDataSubjects, for every visit the segment matched.
  • In this application's own stores. The batch buffer and the dead-letter table hold whole hits — cip, ua, url, urlref, uid — and a dead letter stays there for as long as batch.dead_letter.retention_days keeps it: 30 days by default, without limit at 0, and only while the scheduler runs the daily prune (see how long dead letters are kept). Erasing only at Matomo would let you report a request fulfilled while the same person's address was still in your database. The buffer is searched through whichever driver batch.driver names: database, redis, file or array, including batches a flush has claimed but not yet confirmed.

The return value keeps them apart, because they are different systems:

[
'log_visit' => 2, // Matomo's own counts
'log_link_visit_action' => 7,
'erased_visits' => 2, // visits erased at Matomo, across every round
'erased_completely' => true, // false: run it again, see below
'local_buffer' => 1, // rows removed from matomo_tracking_buffer
'local_dead_letters' => 1, // hits removed from matomo_dead_letters
'local_segment_understood' => true, // whether the local half could act at all
'local_queue_searched' => true, // false in the queue mode, see below
]

Matomo answers a lookup with at most 401 visits. Its findDataSubjects stops there, so forget() erases in rounds: it deletes what a lookup found and looks again while the lookup came back full. erased_completely is false when the rounds ended with visits still matching, after a hundred rounds or a lookup that brought back the visits it had just deleted; run the erasure again. matomo:forget says so and exits with a failure.

export() reads one lookup, so for a person with more than 401 visits its export is partial. exportAll() reads past it: while a lookup comes back full, it looks the visits up again in ranges of the day they ended, Matomo's visitEndServerDate, halves a range whose lookup is still full, and exports the visits in parts of at most 401:

$export = MatomoGdpr::exportAll('userId==alice@example.com');

$export['data']; // Matomo's export: the rows of every part under their log table
$export['exported_visits']; // how many visits it holds
$export['exported_completely']; // false when it could not reach every visit, see below

A day is the narrowest range a date can name, so exported_completely is false when a single day holds more than 401 of the person's visits, or when the export ran out of lookups after two hundred. The export then holds the visits the lookups found. Like the other calls, exportAll() answers null when a call to Matomo failed. matomo:forget --export exports this way. When the export is partial it says so on the error output, which keeps the JSON on standard output clean, and exits with a failure.

The local half understands exactly two segment forms: userId==<value> and visitIp==<value>. A Matomo segment is an expression Matomo evaluates against its own schema, and re-implementing that here against stored payloads would be a guess — a wrong guess deletes somebody else's data. Anything else sets local_segment_understood to false, which is a different answer from "nothing matched": the local stores were not searched, and if the request needs them, run it again with one of the two forms.

Both halves read the value the way Matomo reads it: decoded up to three times, and each pass turns a + into a space, so userId==alice+news@example.com names alice news@example.com. An address in visitIp is compared as an address, as Matomo compares it, so visitIp==2001:db8::1 also finds a hit stored as 2001:DB8::1. To name a value exactly, build the segment with the builder, which encodes it for those passes:

use MatomoAnalytics\Reporting\Segment;

MatomoGdpr::forget(Segment::where('userId', '==', 'alice+news@example.com')->definition());

The local half runs even when Matomo matched nothing, because the buffer holds hits that have not reached Matomo yet.

In the queue mode, the queue itself is out of reach. There a request's hits wait as a queued job until a worker sends them, and a job that runs out of attempts keeps its hits in failed_jobs. Neither can be searched from here, so local_queue_searched is false in that mode. Let the workers drain the queue and run the erasure again, so that whatever they delivered is erased at Matomo too, and prune the failed jobs that still hold the person's hits (php artisan queue:prune-failed).

A tenant that leaves takes its site with it. Where each tenant is counted on a site of its own, SitesClient::delete() deletes that site and every visit Matomo recorded for it, which erases the tenant's visitors as a whole rather than one person at a time. See reports for one tenant's site.

Preview before you erase​

findDataSubjects() returns the matching visit rows, each carrying its site and visit id. Run it first, always. A segment that matches more than you expect erases more than you expect, and the operation is not reversible.

$matches = MatomoGdpr::findDataSubjects('userId==alice@example.com');

if ($matches === null) {
// The call failed — check MatomoGdpr::lastError()
} elseif ($matches === []) {
// Nothing matched. That is an answer: this person produced no visits.
}

The three-valued return is the same convention as the reporting client: null means the call failed, [] means it succeeded and matched nothing.

lastError() holds Matomo's own text, which repeats the segment and with it the identifier of the person the request is about. Show it to the operator who made the request rather than logging it. The package's own report of the failure names the API and the method only.

Export and erase​

export() returns the data subject's data, for handing to the person who asked. forget() erases every matching visit and returns deletion counts keyed by storage area, so you can record what was actually removed.

Both find the subject by segment first, so they operate on exactly what findDataSubjects() showed you — provided nothing new arrived in between.

For the case where you already have the specific visits — from a previous findDataSubjects() call you have vetted — deleteVisits() and exportVisits() take the visit rows directly:

MatomoGdpr::deleteVisits([['idsite' => 1, 'idvisit' => 10]]);

From the command line​

The command previews the match count and asks before deleting:

php artisan matomo:forget "userId==alice@example.com" # confirm, then erase
php artisan matomo:forget "userId==alice@example.com" --force # no prompt
php artisan matomo:forget "userId==alice@example.com" --export # export instead
php artisan matomo:forget "userId==alice@example.com" --site=all

--site takes a site id, or all to search every site the token can see. Without it, the configured site_id is searched — which is a real trap if the person used more than one of your sites, so consider --site=all for genuine erasure requests.

--force exists for scripted erasure, and a script needs it: a run that cannot ask, under -n, -q or --silent or from a job, deletes nothing without it and exits non-zero. If you are wiring this into a self-service privacy flow, do the findDataSubjects() preview in your own code and keep a record of it, because --force produces no preview to keep.

The audit trail​

A DataSubjectForgotten event fires on every erasure, carrying the number of visits erased and the per-area deletion counts:

use Illuminate\Support\Facades\Event;
use MatomoAnalytics\Events\DataSubjectForgotten;

Event::listen(function (DataSubjectForgotten $event): void {
// $event->visits, $event->deleted
});

Listen for it and you have a record of what was erased and when, which is exactly what a data-protection audit asks for. The event carries counts, not the erased data — it is an audit trail, not a backup.

Testing it​

MatomoGdpr::fake() stubs the lookup and can simulate a failing mutation, so an erasure flow can be tested without an admin token or a real Matomo. See testing.