Date ranges

Filter any metric with range(). It accepts a Period case or its string value — the two are interchangeable — plus an explicit start and end for a custom window:

use RoundlyConsulting\Metrics\Enums\Period;

$metric->range('MTD');                 // month to date
$metric->range(Period::MonthToDate);   // identical
$metric->range(Period::ThisQuarter);   // the full current quarter
$metric->range(Period::Custom, '2024-01-01 00:00:00', '2024-03-01 00:00:00');
$metric->range(Period::All);           // no date filtering (the default)

Every period

The default range is ALL — no date filtering — unless you change metrics.default_range. ranges() on any metric returns the same key → label map, and labels run through Laravel’s translator, so a range picker can be localised in your app’s translation files.

Weeks are ISO weeks — Monday to Sunday — whatever the app locale, the same weeks the WEEK trend buckets count. Quarter and year-to-date comparisons never overflow on month-end days: on 12-31, LAST_QUARTER is Q3, and on a leap day the previous YTD ends on 02-28.

Timezones

A metric has a reporting timezone — timezone() on the metric (or Dashboard::timezone()), else config('metrics.timezone'), else the app timezone. Ranges are resolved in it (TODAY is today there, and CUSTOM bounds are read as its wall clock), and trend buckets are labelled in it — handy for per-tenant reporting:

$metric->timezone('America/New_York')->range(Period::Today)->toArray();

Timestamps are taken to be stored in the app timezone (config('app.timezone')), which is how Eloquent writes them. Range bounds are converted to it before they reach the query, and a trend moves each row’s timestamp onto the reporting clock before bucketing it — daylight-saving changes of either zone included — so a row stored at 2026-09-14 23:30 UTC counts as 2026-09-15 in Europe/Bratislava:

config(['metrics.timezone' => 'Europe/Bratislava']);   // app timezone: UTC

Metrics::value()->count(User::query())->range('TODAY')->result()->value();
Metrics::trend()->count(User::query(), 'id')->hourly()->range('TODAY')->result()->trends();
// ['2026-09-15 00:00' => ..., '2026-09-15 01:00' => ..., ...] — local hours

A date column (no time of day) has no timezone to convert from; aggregate one with the reporting timezone left at the app timezone.

Enum toolkit

Period and Unit are string-backed enums built on enums-for-laravel, so they come with helpers for host selects and validation:

use RoundlyConsulting\Metrics\Enums\Period;
use RoundlyConsulting\Metrics\Enums\Unit;

Period::toOptions()->all();   // ['7' => '7 Days', ..., 'ALL' => 'All'] — value => label map
Period::options();            // Collection<EnumOption> of {value, label, name} DTOs for JS/Inertia
Period::validationRule();     // 'in:7,14,30,...,ALL'
Unit::toOptions()->all();     // ['MINUTE' => 'Minute', ..., 'YEAR' => 'Year']
Unit::validationRule();       // 'in:MINUTE,HOUR,DAY,WEEK,MONTH,YEAR'
Unit::labels();               // Collection<string> of readable labels

Validate a range coming from the request before applying it — an unknown value throws InvalidRangeException when the metric resolves:

use RoundlyConsulting\Metrics\Enums\Period;
use RoundlyConsulting\Metrics\Facades\Metrics;

$validated = $request->validate([
    'period' => ['required', Period::validationRule()],
]);

return Metrics::get('revenue')->range($validated['period']);