Triedy metrík

Pre metriky, ktoré používate na viacerých miestach dashboardu, rozšírte základný typ a implementujte calculate(), ktorá vráti zodpovedajúci objekt výsledku:

Typ	Rozšírte	calculate() vracia	Vhodné pre
Value	`RoundlyConsulting\Metrics\Types\Value\Value`	`ValueResult`	Jedno číslo, voliteľne oproti predchádzajúcemu obdobiu
Trend	`RoundlyConsulting\Metrics\Types\Trend\Trend`	`TrendResult`	Časový rad (čiarový či plošný graf)
Progress	`RoundlyConsulting\Metrics\Types\Progress\Progress`	`ProgressResult`	Aktuálna hodnota oproti cieľu (progress bar)
Partition	`RoundlyConsulting\Metrics\Types\Partition\Partition`	`PartitionResult`	Rozpad podľa skupín (koláčový či stĺpcový graf)

Value

use App\Models\User;
use RoundlyConsulting\Metrics\Types\Result;
use RoundlyConsulting\Metrics\Types\Value\Value;

final class RegisteredUsers extends Value
{
    protected function calculate(): Result
    {
        return $this->count(User::query());
    }
}

RegisteredUsers::make()->range('TODAY')->toArray();

Trend

use App\Models\User;
use RoundlyConsulting\Metrics\Types\Result;
use RoundlyConsulting\Metrics\Types\Trend\Trend;

final class RegisteredUsersTrend extends Trend
{
    protected function calculate(): Result
    {
        return $this->count(User::query(), 'created_at');
    }
}

RegisteredUsersTrend::make()->hourly()->range('TODAY')->toArray();

Progress

Metrika Progress porovnáva aktuálnu hodnotu s cieľom target (predvolene 100). Jej predvolené nastavenia definujte raz v setup():

use App\Models\Subscription;
use RoundlyConsulting\Metrics\Types\Progress\Progress;
use RoundlyConsulting\Metrics\Types\Result;

final class MonthlyRevenueGoal extends Progress
{
    protected function setup(): void
    {
        $this->target(10000)->range('MTD');
    }

    protected function calculate(): Result
    {
        return $this->sum(Subscription::query(), 'amount');
    }
}

shouldBeAvoided() použite, keď je cieľ stropom, pod ktorým chcete zostať — napríklad chybový rozpočet alebo limit výdavkov —, a nie métou, ktorú chcete dosiahnuť. Vo výsledku sa prejaví ako avoid, aby ho UI mohlo vhodne zafarbiť:

use App\Models\Incident;
use RoundlyConsulting\Metrics\Types\Progress\Progress;
use RoundlyConsulting\Metrics\Types\Result;

final class ErrorBudget extends Progress
{
    protected function setup(): void
    {
        $this->target(50)->shouldBeAvoided()->range('MTD');   // stay under 50 this month
    }

    protected function calculate(): Result
    {
        return $this->count(Incident::query());
    }
}

// result => [..., 'target' => 50.0, 'avoid' => true, ...]

Partition

use App\Models\User;
use RoundlyConsulting\Metrics\Types\Partition\Partition;
use RoundlyConsulting\Metrics\Types\Result;

final class UsersByPlan extends Partition
{
    protected function calculate(): Result
    {
        // count of users grouped by the `plan` column
        return $this->count(User::query(), 'plan');
    }
}

Predvolené nastavenia v setup()

setup() sa spúšťa v konštruktore, po predvolených hodnotách z konfigurácie. Prezentáciu a správanie nastavte tam raz namiesto opakovania pri každom volaní — fluent volania na inštancii majú stále prednosť:

use App\Models\Order;
use RoundlyConsulting\Metrics\Enums\Period;
use RoundlyConsulting\Metrics\Types\Result;
use RoundlyConsulting\Metrics\Types\Value\Value;

final class Revenue extends Value
{
    protected function setup(): void
    {
        $this->withChangeAgainstPreviousPeriod();

        $this->name('Revenue')
            ->description('Paid orders in the selected period')
            ->prefix('$')
            ->precision(2)
            ->range(Period::MonthToDate);
    }

    protected function calculate(): Result
    {
        return $this->sum(Order::query()->where('status', 'paid'), 'total');
    }
}

// setup() runs in the constructor, so call-site fluent calls still win:
Revenue::make()->range(Period::LastMonth)->toArray();

Spoločné fluent API

Každá metrika — triedna aj inline — dedí od abstraktnej triedy RoundlyConsulting\Metrics\Metric a ponúka:

Metóda	Účinok
`name(string $name)`	Zobrazovaný názov; predvolene poľudštený názov triedy.
`description(string $description)`	Voľný popis v obálke.
`prefix(string $prefix) / suffix(string $suffix)`	Zobrazovaný prefix a sufix, napr. symbol meny alebo jednotka.
`precision(int $precision = 0, RoundingMode $mode = RoundingMode::HalfAwayFromZero)`	Presnosť a spôsob zaokrúhľovania všetkých hodnôt.
`range(Period\|string $range, ?string $customRangeStart = null, ?string $customRangeEnd = null)`	Časové obdobie — pozri Časové obdobia.
`timezone(?string $timezone)`	Vyhodnotí obdobia tejto metriky a označí jej intervaly trendu v explicitnom časovom pásme — pozri Časové obdobia.
`ranges(): array`	Dostupné kľúče a popisy období.
`formatUsing(Closure $formatter)`	Pridá do výsledku naformátovanú hodnotu — pozri Formátovanie čísel.
`cache(), cacheFor(), cacheKey(), dontCache()`	Cachovanie jednej metriky — pozri Cachovanie.
`key(): ?string`	Kľúč z registra, pod ktorým bola metrika načítaná, alebo null pri ad-hoc metrikách.
`make(mixed ...$arguments): static`	Statický konštruktor.
`result(): Result`	Typovaný objekt výsledku — vypočítaný alebo obnovený z cache výsledkov.
`toArray(): array`	Vyhodnotí metriku a vráti obálku.
`toResponse($request): JsonResponse`	Obálka ako JSON odpoveď (Responsable).

precision() prijíma natívny PHP enum RoundingMode, napr. ->precision(2, RoundingMode::HalfEven). Predvolený názov metriky je poľudštený názov triedy (RegisteredUsers → „Registered Users“).

Prejavte lásku k open source

Tento balík je zadarmo pod licenciou MIT. Ak vám šetrí čas, jednorazový príspevok alebo členstvo na Patreone nám pomôže ho ďalej udržiavať, testovať a dokumentovať.

Ďalšie spôsoby podpory vrátane kryptomien

Odoslaním daru súhlasíte s našimi podmienkami prijímania darov.

Podporte našu open-source prácu Pridajte sa k nám na Patreone

Chcete to zabudovať do svojho produktu?

Naše balíky integrujeme do zákazkových Laravel a AI riešení. Napíšte nám, na čom pracujete, a ozveme sa do 48 hodín.

Ponuka do 48 hodín Prezrieť všetky balíky