PHPackages                             omaressaouaf/laravel-statistician - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Admin Panels](/categories/admin)
4. /
5. omaressaouaf/laravel-statistician

ActiveLibrary[Admin Panels](/categories/admin)

omaressaouaf/laravel-statistician
=================================

A Laravel package for generating clean application statistics from Eloquent models, query builders, or plain tables

1.0.0(1mo ago)985MITPHPPHP ^8.2|^8.3|^8.4|^8.5CI passing

Since Jun 12Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/omaressaouaf/laravel-statistician)[ Packagist](https://packagist.org/packages/omaressaouaf/laravel-statistician)[ Docs](https://github.com/omaressaouaf/laravel-statistician)[ RSS](/packages/omaressaouaf-laravel-statistician/feed)WikiDiscussions master Synced 1w ago

READMEChangelog (1)Dependencies (4)Versions (2)Used By (0)

Laravel Statistician
====================

[](#laravel-statistician)

[![Latest Stable Version](https://camo.githubusercontent.com/becbc5fa2bf2e849dd0723c4b38bba1bc744717d471cb7f5cd77c49588f9c90a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6f6d6172657373616f7561662f6c61726176656c2d73746174697374696369616e2e737667)](https://packagist.org/packages/omaressaouaf/laravel-statistician)[![License](https://camo.githubusercontent.com/f42857e8cc00beabca55b1a2c2a8ae2a4c1d2786223c9c0b4bde3dc40cb4ffe4/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f6f6d6172657373616f7561662f6c61726176656c2d73746174697374696369616e)](LICENSE)[![Tests](https://github.com/omaressaouaf/laravel-statistician/actions/workflows/tests.yml/badge.svg)](https://github.com/omaressaouaf/laravelstatistician/actions/workflows/tests.yml)

A Laravel package for generating **clean application statistics** from Eloquent models, query builders, or plain tables.

Features
--------

[](#features)

- Aggregate stats: **count**, **sum**, **avg**, **min**, **max**
- Date-range filtering with `start()` and `end()`
- Date-grouped statistics for charts
- Percentage change between two periods, Trend statistics
- Supports Eloquent builders, query builders, model classes, and table names
- Multiple statistics in one call
- Cache support

---

Installation
------------

[](#installation)

Install via Composer:

```
composer require omaressaouaf/laravel-statistician
```

---

Usage
-----

[](#usage)

### Basic Aggregate Statistic

[](#basic-aggregate-statistic)

```
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'];
```

### Custom Key

[](#custom-key)

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

echo $stats['total_users'];
```

### Date Range

[](#date-range)

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

### Sum / Avg / Min / Max

[](#sum--avg--min--max)

```
use App\Models\Order;
use Omaressaouaf\LaravelStatistician\Enums\Aggregate;

$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();
```

### Date Grouped Statistics

[](#date-grouped-statistics)

Useful for charts and dashboards.

```
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',
    ],
]
```

### Percentage Change

[](#percentage-change)

```
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'];
```

### Using Query Builders

[](#using-query-builders)

```
use Illuminate\Support\Facades\DB;

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

### Multiple Sources

[](#multiple-sources)

```
$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();
```

---

Caching
-------

[](#caching)

Cache statistics for a specific number of seconds:

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

Cache until a specific date:

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

Clear cache conditionally:

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

---

### Custom Statisticians

[](#custom-statisticians)

The package is fully extensible. You can create your own statisticians by implementing one of the provided contracts:

- `OneQueryStatistician` – for statistics that can be computed with a single query for all provided sources (e.g: `AggregateStatistician`).
- `MultiQueryStatistician` – for statistics that require multiple queries or more advanced calculations per each source (e.g: `DateGroupedAggregateStatistician`).

A custom statistician works with its own source object, allowing you to encapsulate configuration and keep your API consistent with the built-in statisticians.

#### Example

[](#example)

```
namespace App\Statistics\Sources;

use Omaressaouaf\LaravelStatistician\Contracts\Source;

class ActiveUsersSource extends Source
{
    public function __construct(
        public Aggregate $aggregate = Aggregate::COUNT
    ) {}
}
```

```
namespace App\Statistics;

use Illuminate\Database\Eloquent\Builder;
use Omaressaouaf\LaravelStatistician\Contracts\OneQueryStatistician;
use App\Models\User;
use App\Statistics\Sources\ActiveUsersSource;

class ActiveUsersStatistician implements MultiQueryStatistician
{
    protected function sourceClass(): string
    {
        return ActiveUsersSource::class;
    }

    protected function handle(Source $source): mixed
    {
        return User::query()
            ->where('is_active', true)
            ->whereDate($source->dateColumn, '>=', $this->startDate->toDateString())
            ->whereDate($source->dateColumn, '