Output & results
toArray() on any metric returns the same envelope, so a front-end can render every tile with one component:
[
'name' => 'New users', // name(), or the humanized class name
'description' => '', // description()
'prefix' => '', // prefix()
'suffix' => '', // suffix()
'range' => [
'current' => 'TODAY', // the selected Period value
'available' => ['7' => '7 Days', '14' => '14 Days', /* … */ 'ALL' => 'All'],
'custom' => ['start' => null, 'end' => null],
],
'result' => [ // the type-specific result
'value' => 42.0,
'previous' => 30.0,
'change' => ['percentage' => 40.0, 'is_increase' => true],
],
]Result shapes
The result block is the metric’s own Result::toArray(), plus a formatted entry when formatUsing() is set:
// Value — without a comparison, 'previous', 'change.percentage' and 'change.is_increase' are null
['value' => 42.0, 'previous' => 30.0, 'change' => ['percentage' => 40.0, 'is_increase' => true]]
// Trend — 'series' only when grouped with groupBy()
['trends' => ['2024-06-01' => 12.0, '2024-06-02' => 0.0], 'series' => [/* … */]]
// Progress — without a comparison, every 'change' field is null
[
'value' => 8200.0, 'progress' => 82.0,
'previous' => 6500.0, 'previous_progress' => 65.0,
'target' => 10000.0, 'avoid' => false,
'change' => ['percentage' => 26.0, 'is_increase' => true, 'progress' => 17.0, 'value' => 1700.0],
]
// Partition — 'labels' only with labelUsing()
['partitions' => ['pro' => 120.0, 'free' => 80.0], 'labels' => ['pro' => 'Pro', 'free' => 'Free']]Typed result objects
result() returns each type’s result as a typed object implementing RoundlyConsulting\Metrics\Types\Result. The typed bases narrow the return type — result() on a Value metric is a ValueResult, on a Progress metric a ProgressResult (which is also a ValueResult), and so on. Besides toArray(), each exposes getters for chart consumers:
| Result | Accessors |
|---|---|
ValueResult | value(), previous(), change(), isIncrease() |
TrendResult | trends(), series(), labels(), values() |
ProgressResult | value(), progress(), target(), previous(), previousProgress(), change(), avoid(), isIncrease() |
PartitionResult | partitions(), labels(), keys(), values() |
Without a comparison, previous() and change() return null and isIncrease() returns false.
Result::fromArray() rebuilds a result from its array form — the result cache stores plain data, and result() restores the typed object from it:
use RoundlyConsulting\Metrics\Types\Value\ValueResult;
$array = Metrics::value()->count(User::query())->result()->toArray();
ValueResult::fromArray($array); // rebuilds the typed object — how cached results come backJSON responses
Metrics and dashboards implement Illuminate\Contracts\Support\Responsable — toResponse() wraps toArray() in a JsonResponse, so returning one from a controller is enough. The keyed maps — trends, series, partitions, labels and formatted — always encode as JSON objects, even when their keys happen to run 0, 1, … (PHP would otherwise encode those as arrays, so the shape would change with the data). toArray() itself returns plain PHP arrays.
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 cryptoBy donating, you agree to our donation terms.
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.