Configuration reference

Every key, its environment variable and the value shipped in the package. This page — not your published config/matomo-analytics.php — is the authoritative list, because a key your file does not contain still has its default. See configuration for why.

A key with an environment variable can be set either way. A key without one is a structure, and is edited in the file.

Connection and master switch

Key	Env	Default	Meaning
enabled	MATOMO_ENABLED	false	Master switch. Installing the package tracks nobody until you set this to true.
host	MATOMO_HOST	—	Base URL of your Matomo. Everything else is derived from it.
site_id	MATOMO_SITE_ID	—	The Matomo site id.
site_id_resolver	—	null	fn(): ?int — an invokable class-string or closure that may name the site for the hit being built. A positive int names the site, and so does a string of digits, the form a site id takes in configuration; null, or anything else, falls back to site_id. For multi-tenant applications; see below.
require_tls	MATOMO_REQUIRE_TLS	false	Refuse to track over a plaintext host. With it on, an http:// host counts as unconfigured and nothing is tracked — the same no-op a missing host takes, never an exception. Off by default because Matomo on a private network without TLS is a legitimate deployment. What it protects: token_auth travels in the request body on every server-side hit.
token	MATOMO_TOKEN	—	token_auth, server-side only. Needed for the real client IP, the time of a hit delivered more than a day late, and the read side.
tracker_path	MATOMO_TRACKER_PATH	matomo.php	Path to the tracking endpoint, relative to host.
js_path	MATOMO_JS_PATH	matomo.js	Path to the JavaScript tracker.
timeout	MATOMO_TIMEOUT	5	Request timeout in seconds for tracking calls.
http_options	—	[]	Extra Guzzle request options for every tracking call, single and bulk, for an application whose HTTP middleware reads an option of its own. The sender's own options win over one of the same name: the timeouts, HTTP/1.1 and the refusal to follow a redirect. The Reporting API does not take them.

Tracking is a no-op while host or site_id is missing. See installation.

One site id per request

site_id_resolver is the seam for an application that tracks each tenant into its own Matomo site. It is called while the hit's payload is built, so it decides per hit rather than per process:

'site_id_resolver' => fn (): ?int => Tenant::current()?->matomo_site_id,

It takes no arguments on purpose — the tenant is a property of your own request context, which the callback already has.

A buffered batch may therefore carry hits for several sites, and that is fine. Each buffered hit holds its own idsite, and Matomo's Bulk endpoint accepts a mixed batch. This is why the seam is a resolver rather than a per-request connection: rebuilding the connection would not fix the buffer, and this does.

Anything other than a positive int falls back to site_id — null, a string, a negative, and a resolver that throws. Tracking never breaks the caller, and that has to include an extension point the package cannot see.

These seven values are read once and then held for the life of the process. In an ordinary request that is invisible, because the process ends with the response. In a long-lived one — a queue:work or matomo:work worker, or Octane — the values the process resolved first are the values it keeps, and changing the configuration underneath it does nothing until it restarts.

It matters in one shape: an application that repoints this package per request or per tenant, so that each tenant tracks into its own Matomo site. There the worker sends every tenant's hits to whichever site it saw first. The way to do it is a tracking gate plus custom dimensions, which read live configuration on every hit — not by swapping the connection under a running worker, which does not work for the reason the Octane guide sets out.

Transmission

Key	Env	Default	Meaning
mode	MATOMO_MODE	queue	queue, sync or batch.
schedule.run_in_background	MATOMO_SCHEDULE_BACKGROUND	true	Runs both scheduled commands off your scheduler, so a slow Matomo never delays another task. Costs you the failure report: from Laravel 12.11 on, Laravel raises a scheduled command's non-zero exit only in the foreground, so a background one reaches neither ScheduledTaskFailed nor your exception handler. Set it to false when that report matters more than the wait, or attach onFailure() through configureSchedule(), which sees a failed run on every supported version.
queue.connection	MATOMO_QUEUE_CONNECTION	null	Queue connection; null uses the default.
queue.queue	MATOMO_QUEUE	matomo	Queue name. Your worker must serve it.
queue.tries	MATOMO_QUEUE_TRIES	5	Delivery attempts before the batch is dead-lettered. A value that is not a whole number of at least 1 keeps 5.
queue.backoff	—	[30, 120, 300, 900]	Seconds between retries, escalating.
queue.retry_until_minutes	MATOMO_QUEUE_RETRY_UNTIL_MINUTES	1440	Outer bound on retrying. queue.tries normally ends the loop first. A value that is not a whole number of at least 1 keeps 1440.

See transmission modes.

Batch buffer

Key	Env	Default	Meaning
batch.driver	MATOMO_BATCH_DRIVER	database	Buffer store: database, redis, file or array.
batch.size	MATOMO_BATCH_SIZE	200	Hits per Bulk request, and therefore how many requests a backlog costs — 2000 hits against a Matomo answering in 20ms take 1021ms at 50, 276ms at 200 and 125ms at 500. It is also the memory knob: a claimed batch is held at roughly 2.3 KB per hit.
batch.flush_interval	MATOMO_BATCH_INTERVAL	60	Seconds between passes of the matomo:work daemon.
batch.max_per_flush	MATOMO_BATCH_MAX_PER_FLUSH	2000	Cap on hits moved by a single flush pass.
batch.stale_after_minutes	MATOMO_BATCH_STALE_AFTER_MINUTES	15	Reclaim a claimed-but-unacknowledged batch after this long. Floored at one minute: at zero every claim expires the moment it is made, and at-least-once delivery becomes guaranteed double delivery.
batch.redis_connection	MATOMO_BATCH_REDIS	default	Redis connection for the redis driver.
batch.table	—	matomo_tracking_buffer	Table for the database driver.
batch.path	MATOMO_BATCH_PATH	null	Spool directory for the file driver; unset means storage/app/matomo-analytics.
batch.max_attempts	MATOMO_BATCH_MAX_ATTEMPTS	25	Consecutive failed flushes before a stuck batch is dead-lettered.
batch.dead_letter.enabled	—	true	Move undeliverable batches to the dead-letter store.
batch.dead_letter.retention_days	MATOMO_DEAD_LETTER_RETENTION_DAYS	30	Days a dead letter is kept before the daily prune deletes it. 0 keeps them forever; a negative value, or one that is not a whole number, keeps 30.
batch.dead_letter.table	—	matomo_dead_letters	Dead-letter table.

The max_attempts counter lives in the cache and therefore needs a persistent cache store — see reliability.

Resilience and alerting

Key	Env	Default	Meaning
resilience.never_throw	—	true	Tracking errors never bubble into the application.
resilience.connect_timeout	MATOMO_CONNECT_TIMEOUT	2	Connection timeout in seconds.
resilience.reporting.report_after_attempts	MATOMO_REPORT_AFTER_ATTEMPTS	3	Report only after this many failures.
resilience.reporting.channel	MATOMO_REPORT_CHANNEL	report	report (exception handler plus log), log, or silent.
resilience.reporting.level	—	warning	Log level for a reported failure.
resilience.reporting.transient_level	—	null	Log level for each retry; null logs none.
resilience.reporting.throttle_minutes	MATOMO_REPORT_THROTTLE_MINUTES	15	Throttle window per error signature. 0 disables throttling.

Reporting (read side)

Key	Env	Default	Meaning
reporting.path	MATOMO_REPORTING_PATH	index.php	Path to the Reporting API.
reporting.timeout	MATOMO_REPORTING_TIMEOUT	10	Request timeout in seconds for report calls.
reporting.default_period	MATOMO_REPORTING_PERIOD	day	Period used when a call omits one.
reporting.default_date	MATOMO_REPORTING_DATE	today	Date used when a call omits one.
reporting.segments	—	[]	Named-segment registry: key to Matomo segment definition.
reporting.cache.enabled	—	true	Cache report responses.
reporting.cache.store	MATOMO_REPORTING_CACHE_STORE	null	Cache store; null uses the default.
reporting.cache.prefix	—	matomo-analytics:report	Cache key prefix.
reporting.cache.ttl.live	—	60	Seconds for realtime counters.
reporting.cache.ttl.today	—	300	Seconds for a span that reaches today: today, lastN, the current week, month or year, a range ending today.
reporting.cache.ttl.recent	—	900	Seconds for a span that ended yesterday, and for previousN.
reporting.cache.ttl.historical	—	3600	Seconds for fully archived past periods.

See reporting and queries and segments.

Visitor identity

Key	Env	Default	Meaning
visitor.rotate	—	daily	Cookieless salt rotation: daily, weekly or never.
visitor.user_id	—	null	auth attaches the authenticated user id as the Matomo User ID; null attaches none.
anonymize_ip	—	true	Truncate the client IP before sending it: an IPv4 address to its first three octets (a /24), an IPv6 address to its first 48 bits.
ip_header	MATOMO_IP_HEADER	null	Forwarding header carrying the real client IP, read from the right of the chain. Trusted without verification — read the warning.
ip_header_trusted_hops	MATOMO_IP_HEADER_TRUSTED_HOPS	1	How many trusted proxies append to ip_header; the client is that many entries from the right.

Tracking gate

Key	Env	Default	Meaning
tracking.environments	—	null	Restrict tracking to these environments; null or [] means all. @matomoScript follows it as well.
tracking.track_authenticated	—	true	Track logged-in users.
tracking.skip_prefetch	—	true	Refuse every hit of a request the browser announced as speculative, an event or a page view your application sends while rendering it included. See Prefetched and prerendered pages.
tracking.except_abilities	—	[]	Skip users who pass any of these Gate abilities.
tracking.except_ips	—	[]	Skip these client IPs or CIDR ranges.
tracking.except_routes	—	['horizon*', 'telescope*', 'nova*', 'up', 'health*', 'livewire/*', 'livewire-*/*']	Skip these request-path patterns. A hit from a Livewire component action is matched by the page it was sent from. @matomoScript renders nothing on a matching page.
tracking.gate	—	null	Invokable class-string or closure for full control.

See the tracking gate.

Privacy

Key	Env	Default	Meaning
privacy.honor_dnt	—	true	Skip tracking on DNT: 1 or Sec-GPC: 1.
privacy.cookieless	—	true	Push disableCookies in the client snippet.
privacy.consent	—	none	Client consent posture: none, cookie or full. Any other value is read as full.
privacy.opt_out.respect	—	true	Honor the first-party opt-out cookie.
privacy.opt_out.cookie	—	matomo_opt_out	Name of that cookie.
privacy.redact.enabled	—	true	Strip secrets and PII from tracked URLs.
privacy.redact.replacement	—	REDACTED	Value a redacted parameter is replaced with.
privacy.redact.query_params	—	A list of token, password, secret, signature and session parameter names, and the signature and credentials of a presigned S3 or GCS URL	Parameters whose value is replaced; the key is kept. Matched case-insensitively.
privacy.redact.path_params	—	['token']	Route parameters whose value is a secret in a path. Every registered route whose URI names one has that segment redacted; the password-reset link is covered whatever the list says.
privacy.redact.patterns	—	[]	Regular expressions applied to the URL. One PCRE cannot compile is refused with its own wording. One the URL makes fail, on bytes that are no UTF-8 under /u or past a backtracking limit, sends the replacement in place of the whole URL.
privacy.redact.keys	—	['url', 'urlref', 'link', 'download', 'c_t', 'c_p']	Which payload fields are redacted. urlref covers _ref as well, the referrer matomo.js keeps for conversion attribution.

See consent and redaction for the full shipped parameter list and how to extend it.

Bots

Key	Env	Default	Meaning
bots.track	—	false	Record bots and crawlers instead of excluding them.
bots.detect_ai_crawlers	—	true	Use the maintained AI/LLM crawler token list.
bots.detect_generic	—	true	Use the generic crawler signals.
bots.allow	—	[]	User-Agent tokens always treated as human. Overrides every other layer.
bots.deny	—	[]	User-Agent tokens always treated as bots.
bots.detector	—	null	Extra invokable class-string or closure, consulted last.

See bots and AI crawlers.

AI chatbot telemetry

Key	Env	Default	Meaning
ai_chatbots.track	—	false	Master switch for AI-chatbot telemetry.
ai_chatbots.auto	—	false	Auto-register the matomo.chatbots middleware on the web group.
ai_chatbots.rec_mode	—	1	1 records bots only (Matomo discards non-bots); 2 lets Matomo decide.
ai_chatbots.source	—	Laravel	Label identifying this collector.
ai_chatbots.user_agents	—	null	Recognized fetchers; null uses the built-in on-demand list.

See AI assistants.

Page-view middleware

Key	Env	Default	Meaning
middleware.auto	—	false	Auto-register the page-view middleware on the web group.
middleware.only_get	—	true	Track GET requests only.
middleware.only_successful	—	true	Track delivered pages only: 2xx and 304.
middleware.only_html	—	true	Track pages only: an HTML response or an Inertia visit, not JSON, a file, an image, a feed or a download.
middleware.skip_livewire	—	true	Skip Livewire update requests.
middleware.skip_partials	—	true	Skip htmx fragments, Turbo Frames, XHR and Inertia partial reloads that load part of a page.
middleware.skip_prefetch	—	true	Skip a request the browser announced as speculative (Sec-Purpose or Purpose carrying prefetch). A pointer resting on a link is not a visit. See Prefetched and prerendered pages.
middleware.strip_query	—	false	Drop the query string from the tracked URL, campaign parameters included.
middleware.client_hints	—	false	Ask the browser for the client hints that name the platform version, the device model and the full browser version (Accept-CH on HTML responses). See device and operating system.
middleware.performance	—	false	Stamp the server generation time onto the page view.

See server-side tracking.

Client-side snippet

Key	Env	Default	Meaning
js.enabled	MATOMO_JS_ENABLED	true	Render the client snippet at all. Governs both @matomoScript and the <noscript> pixel.
js.host	MATOMO_JS_HOST	null	Separate asset host for the tracker script; tracking stays on host.
js.tag_manager	—	null	Full Tag Manager container URL. When set, the container renders instead of the tracker.
js.enable_link_tracking	—	true	Track outbound links and downloads.
js.performance	—	true	false pushes disablePerformanceTracking.
js.custom_dimensions	—	[]	Map of dimension id to value, set on every page view.
js.content_tracking	—	false	false, 'all' or 'visible'.
js.heartbeat	—	15	Heartbeat timer in seconds; 0 disables it.
js.noscript	—	true	Render a <noscript> tracking pixel.
js.dns_prefetch	—	true	Emit a dns-prefetch hint for the Matomo origin.

See client-side tracking.

SPA

Key	Env	Default	Meaning
spa.enabled	MATOMO_SPA	false	Record a virtual page view on each soft navigation.
spa.adapters	—	['livewire', 'inertia']	Which adapters to attach: livewire, inertia, generic.
spa.performance	—	true	Forward an app-provided timing object per virtual page view.

See SPA and soft navigation.

Web Vitals

Key	Env	Default	Meaning
web_vitals.enabled	—	false	Enable the ingest route and the directive.
web_vitals.path	—	matomo-analytics/web-vitals	Route path for the beacon endpoint.
web_vitals.category	—	Web Vitals	Matomo event category the samples are recorded under.
web_vitals.metrics	—	['LCP', 'CLS', 'INP', 'FCP', 'TTFB']	Accepted metrics. Also the allowlist the route validates against.
web_vitals.throttle	MATOMO_WEB_VITALS_THROTTLE	60,1	Route throttle, "requests,minutes", counted per client address and per /64 for IPv6. null disables it; an absent key falls back to the shipped value rather than to no limit.
web_vitals.middleware	—	[]	Extra middleware for the ingest route. Empty by default, because the browser beacons it with sendBeacon() and that carries no CSRF token — which also means no session is started there, so tracking.track_authenticated and tracking.except_abilities see a guest on this path. EncryptCookies followed by MatomoAnalytics\Http\Middleware\ReadSessionWithoutWriting applies them without writing the session; ['web'] applies them too, writes the session, and needs a CSRF exemption for this one route on your side.
web_vitals.library	—	null	Script URL for the web-vitals library; null means your app provides it.

See Web Vitals.

Prefetched and prerendered pages

Key	Env	Default	Meaning
prefetch_beacon.enabled	—	false	Enable the beacon route and the @matomoPrefetchPageView directive.
prefetch_beacon.path	—	matomo-analytics/page-view	Route path for the beacon endpoint.
prefetch_beacon.throttle	MATOMO_PREFETCH_BEACON_THROTTLE	60,1	Route throttle, "requests,minutes", counted per client address and per /64 for IPv6. null disables it; an absent key falls back to the shipped value rather than to no limit.
prefetch_beacon.middleware	—	[]	Extra middleware for the beacon route. Empty for the same reason as web_vitals.middleware: sendBeacon() carries no CSRF token, so no session is started on this path. The same read-only session pair applies the visitor rules here.

See Prefetched and prerendered pages.

Hits from the browser

Key	Env	Default	Meaning
hit_beacon.enabled	—	false	Enable the hit route and the @matomoHitBeacon directive.
hit_beacon.path	—	matomo-analytics/hit	Route path for the hit endpoint.
hit_beacon.throttle	MATOMO_HIT_BEACON_THROTTLE	60,1	Route throttle, "requests,minutes", counted per client address and per /64 for IPv6. null disables it; an absent key falls back to the shipped value rather than to no limit.
hit_beacon.middleware	—	[]	Extra middleware for the hit route. Empty for the same reason as web_vitals.middleware: sendBeacon() carries no CSRF token, so no session is started on this path. The same read-only session pair applies the visitor rules here.
hit_beacon.event_categories	—	[]	The only event categories a page may send. Empty allows every category.

See Hits without matomo.js.

Annotations

Key	Env	Default	Meaning
annotations.release	MATOMO_ANNOTATE_RELEASES	false	Enable matomo:annotate --release.
annotations.starred	—	false	Star release annotations.
annotations.release_prefix	—	Deployed	Release note is the prefix followed by the version.

See release annotations.

Events

Key	Env	Default	Meaning
events	—	true	Fire the package's Laravel events.

See events.

Keys your published config may still carry

These keys are gone from the shipped config file. If you published the config in an earlier version, your copy still has them — and they do nothing. Deleting the lines changes nothing:

• resilience.durability (and its MATOMO_DURABILITY variable) — never read by any code path; removed from the shipped config in 0.19.0
• bots.record_ai_dimension — removed earlier

They are listed here rather than quietly dropped, because a reference that omits a key you can see in your own file is worse than one that explains it. Publishing the config again with --force gives you the current set, but overwrites your edits.

Every environment variable

MATOMO_ENABLED=true
MATOMO_HOST=
MATOMO_SITE_ID=
MATOMO_TOKEN=
MATOMO_TRACKER_PATH=matomo.php
MATOMO_JS_PATH=matomo.js
MATOMO_TIMEOUT=5

MATOMO_MODE=queue
MATOMO_REQUIRE_TLS=false

MATOMO_QUEUE_CONNECTION=
MATOMO_QUEUE=matomo
MATOMO_QUEUE_TRIES=5
MATOMO_QUEUE_RETRY_UNTIL_MINUTES=1440

MATOMO_BATCH_DRIVER=database
MATOMO_BATCH_SIZE=200
MATOMO_BATCH_INTERVAL=60
MATOMO_BATCH_REDIS=default
MATOMO_BATCH_PATH=
MATOMO_BATCH_STALE_AFTER_MINUTES=15
MATOMO_BATCH_MAX_ATTEMPTS=25
MATOMO_DEAD_LETTER_RETENTION_DAYS=30

MATOMO_SCHEDULE_BACKGROUND=true

MATOMO_REPORT_CHANNEL=report
MATOMO_REPORTING_PATH=index.php
MATOMO_REPORTING_TIMEOUT=10
MATOMO_REPORTING_PERIOD=day
MATOMO_REPORTING_DATE=today
MATOMO_REPORTING_CACHE_STORE=

MATOMO_IP_HEADER=
MATOMO_JS_ENABLED=true
MATOMO_JS_HOST=
MATOMO_SPA=false
MATOMO_ANNOTATE_RELEASES=false

Only MATOMO_HOST and MATOMO_SITE_ID have no usable default — everything else can be left unset. MATOMO_ENABLED has a default, but it is false, so it is the one you must set to start tracking.

MATOMO_URL is not read. It was accepted as an alias until 0.16.0, which meant an application configuring its own, separate Matomo integration through that key was activating this package as well.