Nova Matomo Analytics Laravel Package

Technical Evaluation

Architecture fit. This is a presentation-layer plugin: a Nova card that surfaces Matomo reports inside the admin panel via a published config file holding a Matomo URL, site ID, and API token. It introduces no schema, no migrations, no queue workers, and no new datastore. That is the shape a TPM wants — blast radius confined to the admin UI, adoption reversible, rollback is "remove the card registration." The dependency that actually governs the decision is not Laravel, it is Nova: a paid, closed-source product whose card and asset APIs have moved across majors since this package's April 2021 release. Frame it as a plugin pinned to a vendor product you are separately obligated to keep upgrading, not as a library you integrate once. Keep it strictly at the edge of the stack: an internal ops/marketing pulse view for people who already hold Nova accounts. Never a source of truth for billing, SLAs, or external reporting.

Integration feasibility. Mechanically this is a sub-day job — composer require, publish config and assets, register the card in NovaServiceProvider, populate four config values. The gate is not effort, it is compatibility and provenance. Twenty-two stars, zero dependents, and a four-year-old last release mean no ecosystem has validated this against current Nova/Laravel/PHP, and there is no public evidence of production use. Two things must close before any estimate:

• Documentation inconsistency. The description describes iframe embedding of Matomo widgets with token-based access for private instances. The v0.5.0 changelog describes card aggregation changes (sum instead of latest value) and a renamed avg_time_generation metric — which implies a Reporting API client, not an embed wrapper. Those are different implementations with different security reviews, scaling models, and failure modes. Read the source before planning; this is a scoping blocker, not a doc nit.
• Nova major version. "Does it install and render on our Nova version" is the primary feasibility question. Discover the answer in a spike, not mid-sprint.

Technical risk. Medium-high, concentrated almost entirely in abandonment and credential handling rather than code quality.

• Staleness. Four-plus years without a release against a fast-moving closed-source host. Assume a fork is in your future and price it in now.
• Token exposure. A Matomo token for a private instance is the sensitive asset. Wherever it lands — server-side config, a signed iframe URL, a browser-visible attribute — it is one careless src from being readable in devtools by any Nova user. Confirm read-only scope and rotatability before rollout.
• Embedding preconditions (if it is an iframe). Matomo must permit framing; your CSP frame-src and X-Frame-Options must permit the Matomo origin; no mixed content. None of this is a package setting — it is infra change that surfaces to users as a blank rectangle with no error.
• Aggregation semantics. If sum-vs-latest is real, it silently redefines every number on the dashboard under an unchanged label. That is a correctness risk that lands on whoever owns the dashboard, not on the package.
• Authorization. No reason to believe the card honors Nova's per-resource permission model. Assume dashboard visibility implies analytics visibility to every Nova user.
• Failure behavior. Unclear whether an unreachable Matomo yields a blank card, a cached value, or an exception in the dashboard render path. A broken dashboard is worse than no card.

Key questions.

• Which Nova major and PHP/Laravel versions does the current code support, and does it install cleanly on ours?
• Is the card an iframe, a Reporting API client, or both? Where does the token live and who can read it?
• Does it respect Nova authorization, or does dashboard access equal analytics access?
• Are 180/365-day ranges backed by Matomo retention, and does query cost land on Matomo or our app?
• What happens on Matomo timeout — blank, cached, or exception?
• Is there any caching layer, or does every dashboard load hit the Matomo API?
• Who owns this when the maintainer stops responding? (Treat that as already true.)
• What is the bounded cost of the in-house fallback — a first-party Nova card against the Matomo Reporting API — so we choose this deliberately rather than by default?

Integration Approach

Stack fit. Good for a conventional Laravel + Nova admin with an internal audience that already holds Nova accounts and today context-switches to a separate Matomo tab. The value proposition is consolidation of context — one fewer login, faster routine answers — not new analytical capability. The numbers stay Matomo's, unchanged, which is a genuine advantage over hand-rolled cards that drift from the source of truth. Poor fit for anything customer-visible, anything requiring audit-grade metric definitions, anything needing consolidated cross-site reporting, or any panel exposed to external users. Multi-brand setups force one card per site ID with duplicated config — a real product gap, not a tuning problem, and worth recording in the backlog.

Migration path. There is no migration because there is no incumbent. Frame it correctly as a timeboxed greenfield pilot on a non-critical dashboard with an explicit go/no-go, not a rollout. Do the version-compatibility spike first, on a throwaway branch, before spending any effort on config, CSP, or design. Define success criteria and the abandonment trigger before the spike starts so the decision is made on evidence rather than drift.

Compatibility. Four surfaces, ordered by likelihood of blocking:

1. Nova major — highest risk; card APIs have moved. Hard stop if it does not render.
2. PHP/Laravel version — 2021-era code against current runtime; expect deprecations at minimum.
3. Matomo instance — API response shape, framing headers, token permissions, retention window for the long ranges.
4. Hosting/infra — CSP frame-src, X-Frame-Options, mixed content, and whether the Matomo host is reachable from the admin environment.

Pin the exact version in composer.json and commit the lockfile. Do not float on a ^0.5 constraint.

Sequencing.

1. Read the source to settle iframe-vs-API-client and locate the token. Nothing else starts until this is answered.
2. Compatibility spike on a throwaway branch against our Nova/PHP/Laravel versions.
3. Security review: token scope (read-only), storage location, rotation runbook, and whether an analytics token in the admin surface clears policy.
4. Infra change if embedded: CSP frame-src allowance and Matomo framing confirmation.
5. Config and card registration on staging; verify authorization behavior with a low-privilege Nova account.
6. Pilot with a named internal audience and a defined measurement window.
7. Go/no-go review against the pre-agreed criteria and kill triggers.

Fallback. Size the first-party Nova card against the Matomo Reporting API before committing. If the spike fails, that bounded option is well understood and often cheaper than resurrecting a stale dependency. MIT licensing means fork-on-first-breakage is viable either way.

Operational Impact

Maintenance. There is effectively no upstream. Treat the team as the maintainer from day one. Budget roughly half a day per Nova/Laravel/PHP upgrade cycle to re-validate rendering, metric definitions, and config compatibility — and assign that owner by name before the pilot, not after. Pin versions, and expect to fork rather than wait for a fix.

Support. No SLA, single maintainer, negligible adoption, no community to lean on. Internal support is a documentation and ownership problem: someone must own "this number looks wrong," and the answer must be "ask Matomo," because the package renders Matomo's views and does not compose new ones. Publish that in the card's internal readme to preempt the ticket queue.

Scaling. App-side load is trivial for a handfu of cards on one dashboard; the cost model depends on which implementation it turns out to be. If it is a Reporting API client, each card view is a live API call to Matomo — multiplied by card count, site count, and every dashboard refresh, with no guarantee of caching. That is Matomo load and rate-limit exposure, not Laravel load. If it is an iframe, rendering cost sits in the browser and the Matomo instance. Either way, multi-site duplication multiplies queries linearly; there is no consolidated cross-site view and none should be promised.

Failure modes.

• Matomo unreachable → blank card, stale value, or exception in the Nova dashboard render path. Test this explicitly by blocking the host on staging.
• Token rotated or expired → silent failure or a card that renders zeroes without saying why.
• Matomo upgrade changes the Reporting API response → numbers shift or the card breaks, with no upstream fix coming.
• Nova upgrade changes the card/asset API → card fails to register or renders unstyled.
• CSP or framing misconfiguration → blank rectangle, no error surfaced to the user, likely misdiagnosed as a Matomo outage.
• Aggregation semantics drift (sum vs. latest) → numbers silently change meaning under an unchanged label.

Ramp-up. Low for the integration itself — hours for a Laravel developer. The real ramp is the perimeter: security review of token placement and scope, CSP and framing changes, authorization validation with a low-privilege account, owner assignment, and pre-agreed pilot metrics. Plan for the governance cost to exceed the engineering cost, and say so to stakeholders up front.

Pilot metrics and kill triggers. Track weekly active viewers of the card, reduction in Matomo logins and tab-switching, time-to-answer for routine traffic questions, and ticket volume for "this number looks wrong." Pre-agree kill triggers — Nova incompatibility, unresolved token-exposure concern, or recurring maintenance exceeding a first-party rebuild — and commit to acting on them at the review date.