Metric

MetricModule builds dashboard widgets from server-side PHP configuration. It is additive and does not change CounterModule, ChartLineModule, or ChartBarModule.

Use AlexKudrya\Adminix\Modules\Metric\Metric builders:

use AlexKudrya\Adminix\Modules\Metric\Metric;
use AlexKudrya\Adminix\Modules\Metric\MetricDateBucketEnum;
use AlexKudrya\Adminix\Modules\Metric\MetricRangePresetEnum;

Metric::value('users_total')
    ->title('Users')
    ->dataSource(User::class)
    ->aggregate('count');

Metric::trend('orders_by_day')
    ->title('Orders by day')
    ->dataSource(Order::class)
    ->dateField('created_at')
    ->range(MetricRangePresetEnum::LAST_7_DAYS)
    ->bucket(MetricDateBucketEnum::DAY)
    ->aggregate('count')
    ->comparePreviousPeriod();

Metric::partition('orders_by_status')
    ->title('Orders by status')
    ->dataSource(Order::class)
    ->groupBy('status')
    ->aggregate('count')
    ->limit(6);

Metric::progress('monthly_revenue')
    ->title('Monthly revenue')
    ->dataSource(Order::class)
    ->criteria(['status' => 'paid'])
    ->aggregate('sum', 'amount')
    ->target(50000);

Result:

value metrics render a counter-styled number card;
trend metrics render a line chart and can add a dashed previous-period series;
partition metrics render a grouped bar chart;
progress metrics render a counter-styled value card with a progress bar.

When a value/progress metric has previous-period comparison data, Adminix renders the smaller delta text inline beside the main value so the card keeps the same vertical rhythm as CounterModule.

Configuration

Common methods:

name() is required and unique on the page.
title() is the visible widget title.
dataSource() accepts an Eloquent model class or table name.
criteria() applies server-side query scope before aggregation.
aggregate() accepts count, sum, avg, min, or max.
aggregate('sum', 'amount') sets both aggregate and aggregate field. Non-count aggregates require aggregateField().
format() controls displayed card values. Supported values are default number formatting, percent, and decimal:n.

Trend methods:

dateField() selects the date/datetime column, defaulting to created_at.
bucket() accepts MetricDateBucketEnum::DAY, WEEK, or MONTH.
range() accepts only MetricRangePresetEnum values: LAST_7_DAYS, LAST_30_DAYS, LAST_90_DAYS, or LAST_12_MONTHS.
comparePreviousPeriod() adds a previous-period comparison for value and trend metrics.

Partition methods:

groupBy() is required and defines the grouping field.
limit() caps the number of grouped bars.

Progress methods:

target() is required and must be greater than zero.

Safety

Metric ranges are server-side presets, not browser-provided raw dates. Do not use metrics as an authorization boundary; keep tenant/user scope in criteria(). Invalid aggregate names, range presets, missing aggregate fields, missing trend date fields, and invalid progress targets fail with controlled package errors.

Aggregations are covered by SQLite-compatible Testbench tests.

Last modified: 22 June 2026