Quick start

Build a metric inline with the Metrics facade — no class required. Pick a type, an aggregate over an Eloquent query, and a range:

use App\Models\User;
use RoundlyConsulting\Metrics\Enums\Period;
use RoundlyConsulting\Metrics\Facades\Metrics;

$data = Metrics::value()
    ->count(User::query())
    ->name('New users')
    ->range(Period::Today)
    ->withChangeAgainstPreviousPeriod()
    ->toArray();

The facade exposes one builder per metric type — Metrics::value(), Metrics::trend(), Metrics::progress() and Metrics::partition():

Metrics::value()->count(User::query())->range(Period::Today)->toArray();
Metrics::trend()->count(User::query(), 'created_at')->daily()->range(Period::MonthToDate)->toArray();
Metrics::progress()->sum(Order::query(), 'total')->target(10000)->range(Period::MonthToDate)->toArray();
Metrics::partition()->count(User::query(), 'plan')->toArray();

Reading a result

Every metric gives two views of the same calculation: result() — the typed result object (ValueResult, TrendResult, ProgressResult or PartitionResult) for PHP code that works with the numbers — and toArray(), the JSON-ready envelope for a front-end. Both go through the result cache:

$revenue = Metrics::value()->sum(Order::query(), 'total')->range(Period::ThisMonth)->result();

$revenue->value();       // 15230.0
$revenue->change();      // percentage change, when a comparison was requested

Metrics::trend()->count(User::query(), 'id')->daily()->result()->values();   // list<float>
Metrics::get('revenue')->result()->value();   // the typed result of a registered metric

The envelope

toArray() resolves the metric and returns a consistent envelope — presentation fields, the selected and available ranges, and the type-specific result:

[
    '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],
    ],
]

Give inline metrics a name(): without one, the envelope’s name is the humanized class name, which for an inline builder is the builder itself (“Pending Value”).

Return it from a controller

Every metric is Responsable, so a controller can return it directly and Laravel sends the envelope as JSON. Authorization stays your app’s responsibility:

use App\Models\User;
use RoundlyConsulting\Metrics\Enums\Period;
use RoundlyConsulting\Metrics\Facades\Metrics;

final class NewUsersController
{
    public function __invoke()
    {
        return Metrics::value()
            ->count(User::query())
            ->name('New users')
            ->range(Period::Today)
            ->withChangeAgainstPreviousPeriod();
    }
}

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

By donating, you agree to our donation terms.

Support our open source work Join us on Patreon

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 Browse all packages