Laravel Easy Metrics Laravel Package

Getting Started

Install via Composer:

composer require sakanjo/laravel-easy-metrics

Start by building a simple metric in a Filament widget or Laravel command. For a live demo, create a UsersCountWidget extending Filament\Widgets\ChartWidget and populate getData() with:

[$labels, $data] = Trend::make(User::class)
    ->range(30)
    ->countByMonths();

This instantly renders a line chart of user signups over 30 days. Use Value::make()->count() for single KPIs like “Total Users” and wire it to a ValueMetric or custom view.

Implementation Patterns

• Metric Type Selection:
  • Value: Single aggregated KPI (e.g., ->sum('revenue'), ->count()).
  • Doughnut/Pie: Categorical breakdowns (e.g., ->count('status') for active/inactive users).
  • Trend/Line/Bar: Time-series (e.g., ->averageByWeeks('order_value'), ->countByDays()).
• Flexible Grouping: Pass a second column to count(), sum(), etc., for automatic grouping (e.g., Doughnut::make()->count('tier', 'region')).
• Time Range Configuration: Chain range(30), range(Range::MTD), and ranges([15, 30, 365]) to expose interactive toggles in UI—critical for dashboards.
• Growth Reporting: Add ->withGrowthRate()->growthRateType(GrowthRateType::Percentage) to get growth %/value alongside metrics. Works for all metric types and integrates cleanly into component render logic.
• Enum Labels: Combine with SaKanjo\EasyEnum to auto-transform database values (e.g., 0, 1) to readable labels (Active, Disabled) via getLabel() in doughnut/pie legends.
• Date Column Customization: Override default created_at with ->dateColumn('last_activity_at') for metrics on non-timestamp columns.

Gotchas and Tips

• DB Engine Differences: minBy*(), maxBy*(), etc., rely on database-specific time-truncation functions. Test on production DB (e.g., MySQL’s DATE_FORMAT vs PostgreSQL’s date_trunc).
• Null Handling: Aggregates ignore NULL values by default, but count('column') does not include nulls unless you chain ->whereNotNull('column').
• Growth Rate Calculation: Growth compares the last time interval to the immediately preceding one—e.g., for countByMonths(), it’s month n vs month n-1, not vs全年 average. Verify against business logic expectations.
• ** Filament Integration Pitfall**: If using dynamic filters, ensure rangesFromOptions() receives an array keyed by range values (e.g., [30 => '30 Days']), and confirm widget $this->filter matches expected range input.
• Extensibility: All metrics are fully extendable—subclass Value, Trend, etc., to add custom aggregations, label formatters, or DB expressions via constructor override.