Časové obdobia

Každú metriku vyfiltrujete cez range(). Prijíma prípad enumu Period alebo jeho reťazcovú hodnotu — sú zameniteľné — a pre vlastné okno aj explicitný začiatok a koniec:

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)

Všetky obdobia

Predvolené obdobie je ALL, teda bez filtrovania dátumu, pokiaľ nezmeníte metrics.default_range. ranges() na ktorejkoľvek metrike vráti tú istú mapu kľúč → popis. Popisy prechádzajú prekladačom Laravelu, takže výber obdobia lokalizujete v prekladových súboroch aplikácie.

Týždne sú ISO týždne — od pondelka po nedeľu — bez ohľadu na locale aplikácie, teda tie isté týždne, aké počítajú intervaly trendu WEEK. Porovnania štvrťroka a roka k dnešku nikdy nepretečú na konci mesiaca: 31. 12. je LAST_QUARTER tretí štvrťrok a v priestupný deň sa predchádzajúce YTD končí 28. 2.

Časové pásma

Metrika má časové pásmo reportingu — timezone() na metrike (alebo Dashboard::timezone()), inak config('metrics.timezone'), inak pásmo aplikácie. Vyhodnocujú sa v ňom obdobia (TODAY je dnešok v tomto pásme a hranice CUSTOM sa čítajú ako jeho miestny čas) a označujú sa v ňom intervaly trendov — praktické pri reportingu pre jednotlivých klientov (tenantov):

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

Časové pečiatky sa považujú za uložené v pásme aplikácie (config('app.timezone')), tak ich zapisuje Eloquent. Hranice obdobia sa pred dotazom prevedú do neho a trend pred zaradením do intervalu presunie časovú pečiatku každého riadka na čas reportingu — vrátane prechodov na letný a zimný čas v oboch pásmach — takže riadok uložený 2026-09-14 23:30 UTC sa v Europe/Bratislava ráta do 2026-09-15:

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

Stĺpec typu date (bez času) nemá z čoho prepočítať pásmo; agregujte ho s pásmom reportingu ponechaným na pásme aplikácie.

Nástroje enumov

Period a Unit sú enumy s reťazcovými hodnotami postavené na enums-for-laravel, takže ponúkajú pomocníkov pre výbery v aplikácii aj validáciu:

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

Obdobie z requestu pred použitím zvalidujte — neznáma hodnota vyhodí InvalidRangeException pri vyhodnotení metriky:

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

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

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