Nova Metrics Laravel Package

Technical Evaluation

Architecture fit. square1-io/nova-metrics is a single-purpose Nova extension: a Laravel package (composer-installed, service-provider registered, no migrations, no queues, no external services) that bridges Nova's resource filters onto metric cards. That's a narrow, well-defined seam. It fits cleanly if — and only if — Nova is already the system of record for your admin/analytics surface and users are already fluent in the resource-filter vocabulary (date pickers, status selects, tenant filters). It contributes no new abstraction and no data model; it just closes a specific gap between two Nova features that don't talk to each other natively. Value outside Nova is zero.

Integration feasibility. Installation is trivial; adoption is a per-metric-card trait or card-class swap plus a declaration of which resource's filters should surface. The whole source is readable in an hour by a mid-level Laravel developer. The real integration work is not wiring — it's validating that each filter behaves on a card exactly as it does on the resource index.

Technical risk. Ranked:

• Silent wrong numbers. The dominant risk class. A metric that errors is visible; a metric that quietly ignores an applied filter renders a plausible, authoritative-looking number that is wrong. This is a trust failure, not a bug.
• Dependency on Nova internals. Nova is closed-source and commercial. Card rendering and filter plumbing have shifted across Nova 3 → 4 → 5. A Nova patch release can break rendering or, worse, degrade to the silent no-op above.
• Filter-class fidelity. Filters differ enormously: simple column compares, query-builder closures, request-dependent (RequestFilter), conditional-visibility (canSee), multi-select, and date ranges. Only a subset is likely to translate cleanly, and the package description doesn't enumerate which.
• Adoption signal. 27 stars, thin issue surface, likely a single maintainer, opportunity score 1.89. Not disqualifying for a thin shim — but it caps how much risk you can transfer upstream.

Key questions to resolve before committing:

1. Which Nova major/minor versions are pinned in composer.json, and is Nova 5 supported?
2. Does it honor canSee/authorizedToSee on filters, or render everything regardless of viewer policy?
3. How are filter values handed to calculate() — the native $request->filters contract, or a package-specific mechanism?
4. Is behavior uniform across Value / Trend / Partition / Progress, and does it interact correctly with Nova's built-in date-range selector?
5. Does it support closure-based and RequestFilter filters, or only simple ones?
6. Is filter state encoded in the URL (shareable/bookmarkable filtered dashboards)?
7. Is there a CI matrix across Nova versions, and what's the test coverage?

Integration Approach

Stack fit. Laravel + Nova only. Strong fit when product and ops users already filter resource indexes and reasonably expect the same controls on the metric cards sitting beside them. Poor fit if metrics are served from scheduled aggregates rather than query-time computation — filtering at read time is the wrong model there.

Migration path. Additive, zero-blast-radius. No schema changes, no backfill, no data migration. Adoption is per-card, so you can pilot on one metric and leave the rest on native metric filters indefinitely. Rollback is removing a trait reference; the package can remain installed and unused.

Compatibility. Gate on the composer constraint matrix for PHP, Laravel, and Nova against your exact Nova minor. Then run a filter inventory of the app: enumerate every resource filter and classify as (a) simple column compare, (b) query-builder closure, (c) request-dependent, (d) conditional-visibility. Classes (c) and (d) are the likely failure set and should be explicitly excluded from the supported list until proven.

Sequencing.

1. Spike (1–2 days). Install on a branch, wire one Value metric to one resource's filters, and verify the output against a hand-written SQL query with the same predicate. This is the go/no-go gate — if reconciliation fails here, stop.
2. Fidelity audit. Complete the filter classification; publish a supported-filter matrix per metric.
3. Pilot. One dashboard, real users. Instrument for mismatched values, not just errors.
4. Roll out card-by-card, with the supported-filter list documented alongside each metric.
5. Fallback. If upstream gaps block you, fork. The surface area is small enough that a maintained internal fork is cheaper than reimplementing Nova's card UI, and MIT licensing makes that trivial.

Operational Impact

Maintenance. Low steady-state: nothing to run, monitor, or back up. The cost is upgrade-coupled — every Nova major, and some minors, warrants a regression pass on filter application plus a dashboard smoke test. Budget roughly half a day per Nova upgrade. Treat the upstream repo's release cadence and Nova version support as the leading indicator of abandonment.

Support. At 27 stars, the community answer pool is effectively you. Plan to read source rather than search issues. Pin a version or maintain an internal fork so your upgrade cadence isn't hostage to the maintainer's.

Scaling. Infrastructure cost is negligible; query cost is not. Every filter change re-executes the metric query, and Trend/Partition metrics multiply that per data point. A filter combination that's cheap on an index page can be expensive across a 90-day trend on a large table. Validate on production-sized data, not seeds. Separately: if metric results are cached, filter state must be in the cache key or you will serve one user's filtered number to another.

Failure modes, by cost.

• Silent filter no-op → wrong numbers presented as authoritative. Highest severity. Mitigate with a standing reconciliation check comparing a filtered card against an equivalent direct query.
• Authorization leak — filters whose canSee should hide them rendered to unauthorized viewers, or filter semantics revealing data outside a policy scope.
• Version drift after a Nova upgrade → blank cards or render exceptions.
• Partial filter support — correct on simple filters, ignored on closures — producing inconsistent numbers across a single dashboard, which erodes trust faster than a clean outage.
• Cache collisions across filter states.

Ramp-up. Shallow. A mid-level Laravel developer needs under a day to install, read the source, and wire a card; the only prerequisite is Nova's mental model (calculate() plus NovaRequest::filters()). The non-obvious work — the fidelity audit and the reconciliation harness — should sit with whoever owns dashboard trust, not with whoever did the install. Document the supported-filter matrix in-repo so the next maintainer doesn't rediscover it under pressure.

Bottom line. Worth a 1–2 day spike if resource-filter parity on metric cards is a genuine user ask. Technical risk is contained by the package's small footprint; the deciding factor is correctness risk, since the failure mode is quietly wrong executive numbers. The low opportunity score suggests the gap is narrow enough that an in-house implementation remains a credible alternative.