DEV Community: Omar Essaouaf

Building Cleaner Laravel Dashboard Statistics with Laravel Statistician

Omar Essaouaf — Sun, 21 Jun 2026 19:07:39 +0000

Laravel package for generating clean and reusable dashboard

Most dashboards start innocently: a card for total users, another one for total orders, then revenue, average order value, chart data, percentage change, and eventually caching because the dashboard is now doing too much work on every request.

At first, this feels fine because each statistic is “just a query”. But as the application grows, the same logic starts appearing in controllers, services, widgets, reports, and API endpoints.

That is the kind of small but annoying problem I wanted to solve with Laravel Statistician.

Laravel Statistician is a Laravel package for generating clean application statistics from Eloquent models, query builders, model classes, or plain table names.

The goal is simple: keep dashboard and reporting logic reusable instead of duplicating query logic everywhere.

Repository:

https://github.com/omaressaouaf/laravel-statistician

The Problem

In many Laravel applications, dashboard statistics begin like this:

$totalUsers = User::count();
$totalOrders = Order::count();
$totalRevenue = Order::sum('total');
$averageOrderValue = Order::avg('total');

This is perfectly fine in the beginning. The problem appears later, when the dashboard needs date filters, chart data, percentage changes, cached numbers, and similar metrics reused in different places.

At that point, the issue is no longer that the queries are difficult. The issue is that they are easy enough to duplicate.

A controller has one version of the logic. An admin widget has another. A report export has another. An API endpoint has another.

Over time, these small duplicated queries create inconsistency across the codebase.

What Laravel Statistician Does

Laravel Statistician provides a cleaner way to define and generate application statistics.

It supports common dashboard needs such as aggregate statistics, date-range filtering, date-grouped statistics for charts, percentage changes between periods, trend statistics, multiple statistics in one call, caching, and custom keys.

It is not trying to be a full analytics platform or a BI tool. It is a small package for the kind of statistics most Laravel applications need in dashboards, admin panels, reports, and internal tools.

Installation

You can install it with Composer:

composer require omaressaouaf/laravel-statistician

Basic Aggregate Statistic

Here is a simple example that counts users:

use App\Models\User;
use Omaressaouaf\LaravelStatistician\Enums\Aggregate;
use Omaressaouaf\LaravelStatistician\Sources\AggregateSource;
use Omaressaouaf\LaravelStatistician\Statisticians\AggregateStatistician;

$stats = AggregateStatistician::fromSources(
    new AggregateSource(User::class, Aggregate::COUNT)
)->get();

echo $stats['users_count'];

Instead of writing the query directly inside a controller or dashboard widget, the statistic becomes a structured source. That makes it easier to reuse, extend, and compose with other statistics.

Custom Keys

By default, the package generates a key based on the source and aggregate. You can also define your own key:

$stats = AggregateStatistician::fromSources(
    (new AggregateSource(User::class, Aggregate::COUNT))->keyBy('total_users')
)->get();

echo $stats['total_users'];

This is useful when you want your dashboard response to have clean and predictable names.

Date Range Filtering

Most dashboard statistics are not global. You usually want numbers for today, this week, this month, this year, or a custom date range.

Laravel Statistician allows you to apply a start and end date:

$stats = AggregateStatistician::fromSources(
    new AggregateSource(User::class, Aggregate::COUNT)
)
    ->start('2025-01-01')
    ->end('2025-12-31')
    ->get();

This keeps date filtering consistent across different statistics.

Multiple Statistics in One Call

A common dashboard pattern is returning several numbers together, such as users, orders, and revenue.

use App\Models\User;
use App\Models\Order;
use Omaressaouaf\LaravelStatistician\Enums\Aggregate;
use Omaressaouaf\LaravelStatistician\Sources\AggregateSource;
use Omaressaouaf\LaravelStatistician\Statisticians\AggregateStatistician;

$stats = AggregateStatistician::fromSources(
    (new AggregateSource(User::class, Aggregate::COUNT))->keyBy('users'),
    (new AggregateSource(Order::class, Aggregate::COUNT))->keyBy('orders'),
    (new AggregateSource(Order::class, Aggregate::SUM, 'total'))->keyBy('revenue'),
)->get();

return $stats;

This keeps related dashboard metrics grouped together instead of scattering them across multiple methods or services.

Sum, Average, Min, and Max

You are not limited to counts. For example, you can calculate order statistics like this:

use App\Models\Order;
use Omaressaouaf\LaravelStatistician\Enums\Aggregate;
use Omaressaouaf\LaravelStatistician\Sources\AggregateSource;
use Omaressaouaf\LaravelStatistician\Statisticians\AggregateStatistician;

$stats = AggregateStatistician::fromSources(
    new AggregateSource(Order::class, Aggregate::SUM, 'total'),
    new AggregateSource(Order::class, Aggregate::AVG, 'total'),
    new AggregateSource(Order::class, Aggregate::MAX, 'total'),
)->get();

This can be useful for ecommerce dashboards, SaaS admin panels, financial reports, and internal business tools.

Date-Grouped Statistics for Charts

Dashboard charts usually need data grouped by date: users registered per day, orders per day, revenue per month, tickets created per week, and so on.

Laravel Statistician includes date-grouped statistics:

use App\Models\User;
use Omaressaouaf\LaravelStatistician\Enums\Aggregate;
use Omaressaouaf\LaravelStatistician\Sources\DateGroupedAggregateSource;
use Omaressaouaf\LaravelStatistician\Statisticians\DateGroupedAggregateStatistician;

$stats = DateGroupedAggregateStatistician::fromSources(
    new DateGroupedAggregateSource(User::class, Aggregate::COUNT)
)
    ->start('2025-01-01')
    ->end('2025-01-31')
    ->get();

Example result:

[
    'users_count_by_date' => [
        'data' => [
            ['date_label' => '2025-01-01', 'aggregate' => 10],
            ['date_label' => '2025-01-02', 'aggregate' => 15],
        ],
        'date_format' => 'Y-m-d',
    ],
]

This is useful when building chart components because the data can be generated in a consistent format instead of being prepared manually every time.

Percentage Change

Dashboards are usually more useful when they show context. “1,200 users” is useful, but “1,200 users, up 18% compared to the previous period” is much better.

Laravel Statistician supports percentage change between periods:

use App\Models\User;
use Omaressaouaf\LaravelStatistician\Sources\PercentageChangeSource;
use Omaressaouaf\LaravelStatistician\Statisticians\PercentageChangeStatistician;

$stats = PercentageChangeStatistician::fromSources(
    new PercentageChangeSource(User::class)
)
    ->start('2025-02-01')
    ->end('2025-02-28')
    ->get();

echo $stats['users_percentage_change'];

This helps when building dashboard cards that compare current performance with a previous period.

Using Query Builders

Sometimes a statistic is not based on an entire model. You may want to count only active users, completed orders, paid invoices, or filtered records.

The package also works with query builders:

use Illuminate\Support\Facades\DB;
use Omaressaouaf\LaravelStatistician\Enums\Aggregate;
use Omaressaouaf\LaravelStatistician\Sources\AggregateSource;
use Omaressaouaf\LaravelStatistician\Statisticians\AggregateStatistician;

$stats = AggregateStatistician::fromSources(
    new AggregateSource(DB::table('users')->where('is_active', true), Aggregate::COUNT)
)->get();

This makes it flexible enough for real-world use cases where statistics often depend on business rules.

Caching Statistics

Some dashboard statistics do not need to be recalculated on every request. Laravel Statistician supports caching:

$stats = AggregateStatistician::fromSources(
    new AggregateSource(User::class)
)
    ->cacheFor(3600)
    ->get();

You can also cache until a specific date:

$stats = AggregateStatistician::fromSources(
    new AggregateSource(User::class)
)
    ->cacheUntil(now()->addDay())
    ->get();

And clear the cache conditionally:

$stats = AggregateStatistician::fromSources(
    new AggregateSource(User::class)
)
    ->clearCacheWhen(request()->boolean('refresh'))
    ->cacheFor(3600)
    ->get();

This is useful for dashboards where users expect fast responses, but the data does not need to be refreshed every second.

Why I Built It

I like small packages that solve boring problems cleanly.

Dashboard statistics are not usually the hardest part of a Laravel application, but they can easily make the codebase messy. The pattern often looks like this:

// Controller
$totalUsers = User::whereBetween('created_at', [$start, $end])->count();

// Somewhere else
$users = User::whereDate('created_at', '>=', $start)
    ->whereDate('created_at', '<=', $end)
    ->count();

// Another dashboard widget
$userCount = User::query()
    ->whereBetween('created_at', [$from, $to])
    ->count();

None of this is terrible alone. But over time, it creates inconsistency.

Laravel Statistician is a small abstraction around this pattern. Not a heavy analytics system. Not a complex reporting engine. Just a cleaner way to define, reuse, cache, and return statistics.

Design Philosophy

The package follows a few simple principles.

First, the API should stay easy to read. A developer should be able to understand what is being calculated without jumping through multiple files.

Second, it should support common dashboard needs first: aggregates, date ranges, chart data, comparison stats, and caching.

Third, it should work with existing Laravel patterns. The package supports Eloquent models, query builders, model classes, and table names instead of forcing a new data layer.

Finally, it should stay extensible. Every application eventually has custom business metrics, so the package allows custom statisticians while preserving the same general developer experience.

When This Package Is Useful

Laravel Statistician can be useful for admin dashboards, SaaS dashboards, ecommerce reports, internal tools, CRM statistics, financial summaries, user activity reports, chart APIs, and KPI widgets.

It is especially useful when multiple parts of the application need similar statistics.

When You May Not Need It

You probably do not need this package if your dashboard has only one or two simple numbers, your statistics are extremely custom, you already use a dedicated analytics system, or your data is processed in a separate warehouse or BI tool.

This package is meant for application-level statistics inside Laravel apps. It is not meant to replace full analytics infrastructure.

Final Thoughts

Statistics logic is one of those things that feels too small to abstract at first. But once the dashboard grows, the duplication becomes obvious.

Laravel Statistician is my attempt to make this part of Laravel applications cleaner: define statistics once, reuse them, group them, cache them, and return them in a predictable format.

The package is open source, and I would love feedback from Laravel developers.

Repository:

https://github.com/omaressaouaf/laravel-statistician

If you build dashboards in Laravel, I hope this package saves you from writing the same statistics queries again and again.

What Phone Sanitization Revealed About Our Data

Omar Essaouaf — Sat, 13 Jun 2026 20:23:00 +0000

I Thought This Would Take a Day

The task: normalize phone numbers across a sharded production system. Multiple country databases, years of inconsistent formats from different integrations, the usual archaeology. I figured I'd write a script Monday, handle edge cases Tuesday, open a PR Wednesday.

It took the whole week. Not because phone normalization is hard, but because the problem kept exposing things I hadn't thought about.

The framework I didn't need

When I read the schema I saw patterns everywhere. Phone columns scattered across dozens of tables with different names, different formats, different roles in the data model. My brain immediately went to: this should be generic.

Within a few hours I had a design for dynamic schema discovery, automatic phone column detection, a table classification layer, configurable skip policies, dynamic country resolution per shard. The kind of system that could handle any similar migration in any future codebase.

I started building it. The abstractions felt justified. Then I asked myself: why does this actually need to be general?

It didn't. This was a maintenance command that would run once, maybe twice, against one specific system I understood. The reusability I was designing for was completely hypothetical. YAGNI applies to migrations too, maybe more so, because the cost of wrong abstractions in a migration isn't just complexity, it's also the surface area for subtle bugs in code that touches production data.

I deleted most of it.

The final command was explicit about everything: scan the accounts table in each country shard, normalize the phone fields used for identity, detect duplicates using a temporary SQL table, store the conflicting account IDs, normalize phone columns in downstream tables, skip rows belonging to duplicate accounts since those need human review, produce a structured JSON report. Every table name in the config. Every column name spelled out. No dynamic resolution, no introspection.

It felt almost embarrassingly simple. Then it started feeling right.

There's a principle I keep running into that I'd call the maintenance command corollary: tools that run infrequently and touch sensitive data should optimize for auditability over extensibility. The engineer running this six months from now, under pressure, needs to be able to read it and trust it quickly. They don't need it to be clever.

Normalization changes identity

This was the part I hadn't fully thought through, and it reframed the entire project.

Two phone numbers that look different can represent the same subscriber. +1 (800) 555-0123 and 18005550123 are the same number once you apply E.164 normalization. When you collapse those representations across millions of account records, accounts that have been treated as distinct for years suddenly resolve to the same person.

We had duplicates nobody knew about. They had existed quietly in the system across multiple shards because no one had ever compared canonical forms at scale. The normalization didn't create the duplicates, it just made them visible for the first time.

This is the thing about data migrations that makes them genuinely different from feature work. A feature has an off switch. A migration that has run against production data usually doesn't. If you normalize a phone number and discard the original, you've made a permanent decision. If your normalization logic has a bug, you may not be able to reconstruct what the original value was. The blast radius of a wrong decision is bounded in different ways than application bugs.

This is also why duplicate detection ended up being the majority of the actual work. The normalization logic was straightforward. The harder problem was: once we find accounts that now share a canonical phone number, what do we do? Automatically merge? Pick one? The answer was neither: surface them in the report and skip any downstream normalization that touches those accounts until a human reviews them. Automation should stop at the boundary of decisions it doesn't have enough context to make.

Pushing aggregation into the database

My first instinct for duplicate detection was in-process: stream records, build a map of canonical phone to account IDs, flag any key with more than one entry. Reasonable approach, and for small datasets it would have been fine.

The problem was scale combined with the shard architecture. Some country databases have tens of millions of accounts. Holding all canonical phone values in memory simultaneously, across a migration that needed to be resumable, was going to be awkward and wasteful.

What I did instead: buffer inserts of (canonical_phone, account_id) tuples into a temporary table, flush in batches, then run a single GROUP BY canonical_phone HAVING COUNT(*) > 1 at the end. The database does the aggregation, uses its own indexes, and produces exactly the set I need. Total memory footprint on the application side stays flat regardless of table size.

It's not a novel pattern. But I notice engineers, myself included, sometimes reach for in-process solutions out of habit even when the data is already in a database that is extremely good at this specific class of problem. The embarrassing version of this mistake is reimplementing GROUP BY in a hash map.

Same column type, different semantics

I went in assuming I could treat phone numbers uniformly. They're all phone numbers. Normalize them all the same way. That assumption broke down quickly.

Some phone fields are identity fields. They are how the system finds and matches accounts. Normalizing them is what drives the deduplication logic. Others are contact preferences or communication records that happen to store a phone number but play no role in identity resolution. Others live in event logs that represent historical facts and probably shouldn't be rewritten at all.

The data type is the same. The semantics are completely different, and the right migration behavior depends on the semantics, not the type.

This also came up in a subtler way when I was writing the config schema. I had a field called owner_uid_column because I was thinking about the mechanism: this table has a foreign key to the account UID. But what I actually meant was "the column that tells me which account owns this row." I renamed it to owner_column. Small change, but the original name encoded an assumption about key type that wasn't relevant to what the config was trying to express. Config that describes intent ages better than config that describes implementation.

The broader principle here is that column relationships don't imply identical business rules. Two tables can both have a foreign key to the same parent entity and still require completely different handling in a migration. The relationship tells you where data comes from, not what it means.

Behavioral equivalence as a refactoring strategy

I refactored this several times over the week, removing abstractions in each pass. The thing that made that safe was a specific validation approach: I compared structured outputs between versions rather than reviewing code.

After each refactor, I ran both versions against the same dataset and diffed the results: duplicate groups found, account IDs flagged, changed rows, unchanged rows, skipped rows, invalid rows, the final report structure. They had to be byte-for-byte identical. Not functionally similar, identical.

This is a stronger guarantee than code review. Code review catches things that look wrong. Output comparison catches things that are wrong. The implementation can change arbitrarily as long as the observable behavior doesn't change. That's the actual definition of a correct refactor, and having a machine verify it rather than a human read it is more reliable.

It also changes the psychology of simplification. Deleting an abstraction feels risky when you're relying on your own judgment that the replacement is equivalent. It feels much less risky when you have a diff that shows zero behavioral difference. I deleted a few hundred lines this way that I wouldn't have been confident deleting based on reading alone.

Where this landed

The version I shipped was smaller and more boring than what I had on Tuesday. Every table explicit. Every column explicit. Config that reads like a description of the business problem rather than a description of the implementation. A report that tells you exactly what happened, row by row, so the person running it next time can audit the results without reading the code.

I've been writing software long enough to know that "boring" and "correct" are not in tension. For a migration tool that runs occasionally and touches data you can't easily recover, boring is exactly what you want.