--- title: "Metrics for Laravel — docs | Roundly" description: "Developer docs for Metrics for Laravel: value, trend, progress and partition metrics from Eloquent, date ranges, dashboards, caching and testing." url: https://roundly-consulting.com/open-source/docs/metrics-for-laravel language: en --- [All packages](https://roundly-consulting.com/open-source.md) Open source # Metrics for Laravel Install `composer require roundly-consulting/metrics-for-laravel` Requires: PHP ^8.4 · Laravel ^12.0|^13.0 [GitHub](https://github.com/roundly-consulting/metrics-for-laravel) [Packagist](https://packagist.org/packages/roundly-consulting/metrics-for-laravel) [Donate (opens in a new tab)](https://donate.stripe.com/dRmeVe8FX5PF1Qd9pXcEw00) [Patreon](https://www.patreon.com/cw/roundly) ## Overview A native metrics engine for Laravel. Point it at any Eloquent query and get a dashboard-ready metric back — a single value with period-over-period change, a time series for charts, progress against a target, or a grouped breakdown for pie and bar charts. It handles date ranges, aggregation, time bucketing, caching and number formatting, and returns clean JSON-friendly data for any front-end — Nova-style metrics without Nova. No migrations, no tables, no UI; MIT-licensed and built on official Laravel components plus two small Roundly helper packages. ### What you get #### Four metric types Value, trend, progress and partition — the four shapes behind nearly every dashboard tile, inline or as reusable classes. #### Ranges & comparison 20 preset periods, custom windows and per-metric timezones, with change against the previous period or any range you pick. #### Chart-ready trends Minute-to-year buckets, gap-filled axes and multi-series splits, portable across MySQL, MariaDB, PostgreSQL and SQLite. #### Readable partitions Top-N breakdowns with a rolled-up “Other” bucket and display labels mapped from raw group keys. #### Registry & dashboards Register metrics under keys, resolve a whole dashboard in one call, and return either straight from a controller as JSON. #### Caching & events Opt-in result caching with targeted invalidation on any store, and a MetricCalculated event for slow-metric logging. #### Facade or DI, with a recording fake Use the Metrics facade or inject MetricsManager for the same API; Metrics::fake() stubs results and records what was resolved. ### Documentation #### [Installation](https://roundly-consulting.com/open-source/docs/metrics-for-laravel/installation.md) Install via Composer — the provider and the Metrics facade are auto-discovered, there are no migrations, and the config is optional. #### [Configuration](https://roundly-consulting.com/open-source/docs/metrics-for-laravel/configuration.md) Every config key and its default — reporting timezone, default range, unit and precision, result caching, the partition label and trend drivers. #### [Quick start](https://roundly-consulting.com/open-source/docs/metrics-for-laravel/quick-start.md) Build a metric inline in one fluent expression with the Metrics facade, then read its typed result or return its JSON-ready envelope. #### [The Metrics facade](https://roundly-consulting.com/open-source/docs/metrics-for-laravel/facade.md) The whole API on one facade — inline builders, the metric registry, dashboards, cache invalidation and the recording fake. #### [Without the facade](https://roundly-consulting.com/open-source/docs/metrics-for-laravel/without-facade.md) Inject MetricsManager for the same API without static calls, or use metric classes on their own — no registry, no facade. #### [Metric classes](https://roundly-consulting.com/open-source/docs/metrics-for-laravel/metric-classes.md) Define reusable Value, Trend, Progress and Partition classes with calculate() and setup(), plus the fluent API every metric shares. #### [Aggregate helpers](https://roundly-consulting.com/open-source/docs/metrics-for-laravel/aggregates.md) count, average, sum, max and min over any Eloquent query — the aggregated column, the date column, and how scopes are respected. #### [Date ranges](https://roundly-consulting.com/open-source/docs/metrics-for-laravel/date-ranges.md) 20 preset periods from today to last year, custom windows, per-metric timezones and the Period enum toolkit for pickers and validation. #### [Period comparison](https://roundly-consulting.com/open-source/docs/metrics-for-laravel/comparison.md) Show change against the previous period, or compare against any range with compareTo() — for value and progress metrics. #### [Trends](https://roundly-consulting.com/open-source/docs/metrics-for-laravel/trends.md) Time series bucketed by minute to year, with gap filling, multi-series groupBy() and date grouping portable across four databases. #### [Partitions](https://roundly-consulting.com/open-source/docs/metrics-for-laravel/partitions.md) Grouped breakdowns for pie and bar charts — largest first, capped to the top N with an “Other” bucket, and mapped to display labels. #### [Output & results](https://roundly-consulting.com/open-source/docs/metrics-for-laravel/output.md) The envelope every metric returns, the result shape of each metric type, and the typed result() objects with their accessors. #### [Number formatting](https://roundly-consulting.com/open-source/docs/metrics-for-laravel/formatting.md) Present values as currency, percentages or abbreviated figures with formatUsing() — the raw numbers stay untouched alongside. #### [Registry](https://roundly-consulting.com/open-source/docs/metrics-for-laravel/registry.md) Register metrics under short keys as classes, closures or instances, then resolve one or all of them by name from anywhere. #### [Dashboards](https://roundly-consulting.com/open-source/docs/metrics-for-laravel/dashboards.md) Resolve many registered metrics in one call into a single keyed payload that shares one range and, optionally, one timezone. #### [Caching](https://roundly-consulting.com/open-source/docs/metrics-for-laravel/caching.md) Opt-in result caching — globally or per metric with cache(), cacheFor(), cacheKey() and dontCache() — plus forget() and flushCache(). #### [Events](https://roundly-consulting.com/open-source/docs/metrics-for-laravel/events.md) MetricCalculated fires on every resolution with the key, range, duration and cache-hit flag — ready for slow-metric logging. #### [Artisan commands](https://roundly-consulting.com/open-source/docs/metrics-for-laravel/commands.md) List every registered metric and resolve one from the terminal to inspect its envelope, with an optional range override. #### [Extending](https://roundly-consulting.com/open-source/docs/metrics-for-laravel/extending.md) Add trend support for another database with a QueryExpression, and feed metrics from any package’s domain events. #### [Exceptions](https://roundly-consulting.com/open-source/docs/metrics-for-laravel/exceptions.md) Every exception extends MetricsException — what each one means, when it is thrown, and how to catch the whole family at once. #### [Testing](https://roundly-consulting.com/open-source/docs/metrics-for-laravel/testing.md) Stub metric results with Metrics::fake(), assert which metrics were resolved or forgotten, and test the numbers against seeded rows. #### [Requirements](https://roundly-consulting.com/open-source/docs/metrics-for-laravel/requirements.md) PHP 8.4+ and Laravel 12 or 13, with MySQL, MariaDB, PostgreSQL or SQLite for trend metrics out of the box. ## Show your open-source love This package is free and MIT-licensed. If it saves you time, a one-off donation or a Patreon membership keeps it maintained, tested and documented. [More ways to support, including crypto](https://roundly-consulting.com/support-us.md) By donating, you agree to our [donation terms](https://roundly-consulting.com/donation-terms.md). [Support our open source work (opens in a new tab)](https://donate.stripe.com/dRmeVe8FX5PF1Qd9pXcEw00) [Join us on Patreon (opens in a new tab)](https://www.patreon.com/cw/roundly) ## Want this built into your product? We integrate our packages into custom Laravel and AI builds. Tell us what you're working on and we'll reply within 48 hours. [Get a quote in 48 hours](https://roundly-consulting.com/contact.md) [Browse all packages](https://roundly-consulting.com/open-source.md)