Matomo Analytics For Laravel Laravel Package

Product Decisions This Supports

• Build vs. buy for analytics delivery. This package owns the unglamorous part of shipping server-side events to Matomo: queued jobs, batch claiming, retries, stale-batch reclaim, and dead-letter retention. Choosing it is a decision to not staff an internal pipeline team for a non-differentiating capability.
• Delivery-guarantee positioning. MATOMO_QUEUE_TRIES and MATOMO_QUEUE_RETRY_UNTIL_MINUTES externalize the completeness-versus-freshness tradeoff. This is a product decision, not a config detail: a longer retry window buys more delivered events at the cost of late-arriving data in reports. PM should pick and document the target rather than inherit defaults.
• Operational tuning without a release. All three new env vars (MATOMO_QUEUE_TRIES, MATOMO_QUEUE_RETRY_UNTIL_MINUTES, MATOMO_BATCH_STALE_AFTER_MINUTES) let ops and on-call change retry and reclaim behavior per environment. This removes "ship a config change" from the incident path and supports staging/production parity and, in multi-tenant setups, per-tenant tuning.
• Infrastructure cost and data-integrity tradeoffs. batch.stale_after_minutes governs how aggressively abandoned claims are reclaimed; set it too low and you reprocess work (duplicate risk), too high and stuck batches strand events. Dead-letter retention governs storage growth and the replay window. Both are levers a PM can reason about in cost and SLAs.
• Roadmap signal. The migration fix (publishing Support\TableLookup as public API) is API hygiene aimed at consumers' CI and static analysis. It indicates the maintainer is hardening the integration surface rather than adding features — a good sign for a component you intend to leave running unattended.
• Use cases supported: server-side conversion and funnel tracking, first-party analytics for privacy-sensitive flows where client-side JS is blocked, backfilling historical events, and centralizing event emission behind one queue-backed path.

When to Consider This Package

Consider it when:

• You run Laravel and Matomo is already, or is becoming, your analytics system of record.
• Event volume makes synchronous HTTP calls to Matomo unacceptable in the request path.
• You already operate queue workers and have somewhere to observe failed jobs and dead letters.
• You need different retry/retention behavior per environment or per tenant, and want that in deployment config rather than code.
• You want the batch-claim and stale-reclaim mechanics handled for you instead of writing them.

Look elsewhere when:

• You need real-time or sub-second reporting; queueing introduces inherent lag.
• You need exactly-once semantics. Claiming, stale reclaim, and retries imply at-least-once delivery — deduplication is your responsibility. Do not promise exactly-once to stakeholders on this foundation.
• You require vendor-backed SLAs or a stable 1.x API contract. This is pre-1.0; pin versions and read every changelog.
• Matomo is not central to your analytics strategy — the operational overhead of a queue plus dead-letter queue is not worth it for low-volume or exploratory tracking.

Release-specific cautions:

• Setting MATOMO_DEAD_LETTER_RETENTION_DAYS to a negative value no longer disables pruning; it now falls back to the shipped 30 days. Only 0 means keep indefinitely. Anyone using -1 as an "off switch" will silently start losing dead letters after 30 days. Audit env files before upgrading.
• Non-integer or sub-1 values for the three new variables are silently ignored in favor of shipped defaults — validation is permissive, so a typo'd env var fails quietly. Add a config assertion in your test suite.

How to Pitch It (Stakeholders)

For executives: This is a maintenance release that improves operability rather than expanding scope — the lowest-risk kind of change. Three settings that previously required a code change to adjust (retry attempts, retry window, stale-batch reclaim) are now deployment configuration, which shortens incident response and lets us treat staging and production identically. One behavior change affects teams that used a negative retention value to mean "keep forever"; it now means "keep 30 days," which we should communicate to whoever owns analytics infrastructure. The remaining fix removes static-analysis noise from the migrations we publish into the host application, so consuming teams stop seeing CI warnings they cannot resolve without editing a vendor file. Net: no new surfaces to learn, better knobs, one migration note.

For engineering: Pin the version — this is 0.35.x and the public API surface is still being defined, evidenced by Support\TableLookup being promoted from internal to public specifically because published migrations call it. When you upgrade: check all env files for negative MATOMO_DEAD_LETTER_RETENTION_DAYS; replace with 0 if the intent was unlimited retention. Add the three new variables to your environment matrix and to a test that asserts parsed config values, since invalid values are dropped silently rather than raising. Monitor dead-letter depth and stale-batch reclaim counts after tuning MATOMO_BATCH_STALE_AFTER_MINUTES — lowering it increases reprocessing and therefore duplicate submissions. Treat delivery as at-least-once and make deduplication explicit downstream if report accuracy depends on it.