- How do I install square1/nova-metrics in a Laravel Nova application?
- Install it with composer require square1/nova-metrics and commit the lockfile change. Before you do, check the package's composer.json for declared Nova, Laravel, and PHP constraints and whether a prebuilt JavaScript asset ships with it, since a PHP-only card package is materially safer across Nova upgrades. Once installed, register your metric cards on the Nova dashboard where they should appear. Because Nova is closed-source and commercial, confirm behavior against your installed Nova version rather than inferring it from public source.
- Which Nova, Laravel, and PHP versions does square1/nova-metrics support?
- The authoritative source is the require and require-dev blocks in the package's composer.json plus its CI matrix. Check that the declared Nova major matches the one you run, that the Laravel and PHP constraints line up with your application, and that CI actually exercises the declared Nova version. Nova 4 to 5 moved to Vue 3 and Nova.booting, and card packages historically break across that line. If the package does not test your major, treat compatibility as unproven until you verify it yourself.
- How do I define a metric card with square1/nova-metrics?
- Metrics are defined in PHP through a fluent API, so a value card is a short definition that returns a number from a query instead of hand-written card boilerplate. Value, trend, partition, and progress card types are supported, along with custom formatting, ranges, and display options. Keep the underlying query in an Eloquent builder so the logic stays readable, auditable, and easy to reuse on a resource index page.
- How do I add a trend metric to a Nova dashboard with this package?
- Trend cards are declared the same way as other metrics, with the package handling the bucketed series and its presentation on the dashboard. Watch the query cost: a trend backed by an expensive whereHas condition can issue one query per bucket, so measure it before shipping it to a busy dashboard. If the number is slow, precompute the series into a table and point the card at that instead.
- How does caching work in square1/nova-metrics and how do I control refresh intervals?
- The package exposes configurable caching and refresh intervals, which matters because dashboard cards re-resolve their queries on load. Key every cache entry on both the resolved filter payload and the authenticated user ID. Also check whether user-dependent options() queries now run once per card on every dashboard load and what that costs, then tune the refresh interval against your actual query timings.
- Do Nova metrics built with square1/nova-metrics respect dashboard resource filters?
- Do not assume they do. Nova applies resource filters to index and detail requests, but Value, Trend, Partition, and Progress cards call calculate(NovaRequest $request) and resolve their own query, so filter state is not automatically threaded through. The practical consequence is that a dashboard card and the table directly beneath it can legitimately disagree, which is exactly the numbers-don't-match bug. Verify what actually arrives in the metric request, including whether defaults apply on first load, and confirm that Filter::apply runs server-side rather than accepting opaque client-supplied state.
- Can square1/nova-metrics leak data between tenants if metrics are cached?
- It can if caching is not keyed correctly. Every cache entry must incorporate the resolved filter payload and the authenticated user ID, otherwise one tenant's aggregate can be served to another. Verify with two users of different scopes that they receive different numbers, and check canSee() behavior in the metric request context, where it behaves differently than on an index request. Treat a metric that silently ignores an owner or tenant filter as a data exposure, not a cosmetic bug.
- How do I format metric values, ranges, and display options?
- The package supports custom formatting, ranges, and display options per metric, so values can be rendered as currency, percentages, or abbreviated numbers, with sensible bounds for progress and partition cards. Configure these on the metric definition itself to keep dashboard code declarative. Keep formatting logic out of the query so the underlying number stays easy to test.
- How do I test metric cards built with square1/nova-metrics?
- Test the metric class the way you test any query object: assert the value or series it returns for a known dataset, and assert authorization by resolving the same metric as two users with different scopes. Because Nova is closed-source, also add a smoke test that renders the dashboard in your CI matrix against your installed Nova major, so an upgrade fails loudly instead of silently. If the package is small enough, forking it makes this kind of coverage far easier to own.
- Is square1/nova-metrics actively maintained, and what are the alternatives?
- It is a small package: roughly 27 stars, no dependents, and a single-maintainer signal, so you are effectively the QA department and upstream breakage will surface during your Nova upgrade with no committed fix timeline. The alternative is writing custom Nova metric cards in-house, which is realistic if the package stays under about 500 lines of code and you can fork and own it in a day or two. For warehouse- or third-party-API-backed metrics, or precomputed aggregates where applying a filter has no clean semantic, neither approach fits well and a dedicated BI layer is the better fit.