Nova Metrics Laravel Package

Product Decisions This Supports

• Closing a trust gap in the admin analytics surface. Nova resolves metric cards in their own request context, so a dashboard card and the filtered index table beneath it can legitimately disagree. If users have ever said "the chart doesn't match my table," this is a concrete, scoped feature bet: ship filter-aware metric cards as a v1 admin capability and validate the UX cheaply before committing engineering to custom code.
• Build vs. buy — framed honestly as pilot vs. shim. The in-house alternative is marshaling ResourceFilter state (filter keys, defaults, authorization, edge cases) into every metric query, plus ongoing Nova-version upkeep. That's a few days of engineering a small MIT package can replace — if it stays compatible with your Nova version. With 27 stars and zero dependents, the decision is really "pilot a cheap dependency with a fork-and-own exit ramp," not "adopt a platform."
• Roadmap sequencing and risk budgeting. Use it to ship one internal admin capability quickly and measure whether filtered metrics are actually used. Do not use it to promise analytics parity, cross-resource reporting, or warehouse-grade BI — that is a different product, and Nova metrics plus filters is the wrong layer.
• Use cases worth prioritizing. Sales pipeline value filtered by owner/region/stage; support ticket trends filtered by team/status; ops volume filtered by environment or tenant — any admin surface where the trust complaint already exists and filters are simple, deterministic predicates users already rely on. Prefer Value cards for anything expensive; Trend cards issue one query per bucket, so a whereHas filter turns 30 cheap predicates into 30 correlated subqueries.
• Defining success before rollout. Installation is not success. Pick the signals up front: fewer "numbers don't match" tickets, actual usage of filtered cards, reduced time-to-answer in ops/sales reviews, and whether stakeholders stop exporting to spreadsheets. Also decide that a filtered number must be visibly labeled as filtered — a silently wrong number is worse than a 500 because it looks trustworthy, and someone will screenshot it in a business review.
• Committing to an analytics-UX mental model. Once metrics honor filters, you can promise "what I filter on the index is what I see in the cards." That promise is only credible if a parity test asserts filtered metric value == filtered index count == hand-written query with identical constraints, across no-filter, single-filter, and multi-filter cases.

When to Consider This Package

Consider it when all of these hold:

• You are on Laravel Nova and admin users already lean on resource filters; the mismatch complaint is real, not hypothetical.
• Your metrics fit Nova metric cards (value, trend, partition, progress) rather than bespoke BI queries — this extends Nova's model, it does not replace it.
• You can verify compatibility with your Nova major (4 vs 5), Laravel, and PHP versions, and are comfortable reading the source. The code surface should be small enough to audit — under ~500 LOC makes fork-and-own a 1–2 day job and changes the whole risk calculus.
• The blast radius is low: an internal admin panel, not a customer-facing surface and not financial reporting without extra controls. Rollback is a deploy revert — read-path only, no data migration.
• You will pin an exact version (no caret ranges on a zero-dependent package) and vendor or fork it if it becomes load-bearing — with zero dependents, assume you are the QA department.
• You can build a parity harness in CI: filtered metric value == filtered index count == hand-written query with identical constraints, covering no-filter and multi-filter cases.
• You have checked filter semantics: canSee/authorization honored server-side in the metric request, user-dependent options() behaving correctly (it now runs on every card load), whether filter state actually travels into the dashboard render context, and whether whereHas/subquery filters make cards slow.
• Your caching story is safe. If you cache, the key must include both resolved filter state and authenticated user ID — otherwise a tenant- or owner-scoped metric can leak a cached number across users. This is the highest-severity mistake available in this integration.

Look elsewhere when:

• You are not on Nova or plan to leave it — this value dies with the platform.
• You need real analytics: cross-resource joins, warehouse aggregation, scheduled or precomputed computation, cohorts, funnels, or self-serve BI.
• Your metrics are async, cached, or precomputed and filters don't map cleanly onto aggregates — debugging filtered-metric correctness is worse than shipping no filter.
• Filters are highly authorization-sensitive or tenant-scoped and you cannot audit that the metric request honors the same access rules as the index page. A metric that ignores an owner/tenant filter is a cross-tenant data exposure, not a cosmetic bug.
• You require support SLAs, security artifacts, or guaranteed version tracking — MIT, community-only, single-maintainer signal.
• The capability is a nice-to-have; integration may be cheap, but so is the value, and you shouldn't spend roadmap credibility on it without a pilot proving user value.

How to Pitch It (Stakeholders)

For executives: Our Nova admin shows dashboard metrics that ignore the filters users apply to the underlying lists, so the numbers disagree and trust in the admin erodes. square1/nova-metrics is a small, MIT-licensed add-on that makes Nova metric cards honor those resource filters. Cost is negligible and it is scoped to internal tooling, so it's a low-risk way to test whether filter-aware admin analytics improves trust and reduces "the numbers don't match" complaints. The caveat is maturity: it's a low-adoption, likely single-maintainer package coupled to closed-source Nova internals. I recommend a pilot in one admin area with a fork-and-own fallback, not a platform commitment — ship behind one surface, measure whether filtered metrics are actually used, and revisit make-vs-buy only if it spreads.

For engineering: This saves us from writing filter-state plumbing into every metric query. Before adoption, confirm Nova/Laravel/PHP compatibility and read the source — correctness depends on non-public Nova behaviour, so it must be proven against the installed version empirically, not inferred from public docs. Pin an exact version — no caret ranges on a zero-dependent package — and add a parity test asserting a filtered metric equals the index page and a hand-written query with identical constraints. Isolate usage behind an internal base card class in app/Nova/Metrics/ so swapping the package for first-party code is a one-file change, and single-source filter definitions from Resource::filters() so the card and the index can't drift into two hand-copied where clauses. Verify server-side filter application (never opaque client-supplied filter state), canSee/authorization behavior across two users of different scopes, options() cost per card load, and query plans for trend metrics where per-bucket filtered queries multiply cost. If the diff is small, forking is acceptable; assign an internal owner either way and add "verify metric cards" to the permanent Nova upgrade checklist.