README

This package is a lightweight solution to summarize changes in your database over time. Here's a quick example where we are going to track the number of subscriptions and cancellations over time.

First, you should create a stats class.

use Spatie\Stats\BaseStats;

class SubscriptionStats extends BaseStats {}

Next, you can call increase on it when somebody subscribes, and decrease when somebody cancels their plan.

SubscriptionStats::increase(); // execute whenever somebody subscribes
SubscriptionStats::decrease() // execute whenever somebody cancels the subscription;

With this in place, you can query the stats. Here's how you can get the subscription stats for the past two months, grouped by week.

use Spatie\Stats\StatsQuery;

$stats = SubscriptionStats::query()
    ->start(now()->subMonths(2))
    ->end(now()->subSecond())
    ->groupByWeek()
    ->get();

This will return an array like this one:

[
    [
        'start' => '2020-01-01',
        'end' => '2020-01-08',
        'value' => 102,
        'increments' => 32,
        'decrements' => 20,
        'difference' => 12,
    ],
    [
        'start' => '2020-01-08',
        'end' => '2020-01-15',
        'value' => 114,
        'increments' => 63,
        'decrements' => 30,
        'difference' => 33,
    ],
]

Support us

We invest a lot of resources into creating best in class open source packages. You can support us by buying one of our paid products.

We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on our contact page. We publish all received postcards on our virtual postcard wall.

Installation

You can install the package via composer:

composer require spatie/laravel-stats

You must publish and run the migrations with:

php artisan vendor:publish --provider="Spatie\Stats\StatsServiceProvider" --tag="stats-migrations"
php artisan migrate

Usage

Step 1: create a stats class

First, you should create a stats class. This class is responsible for configuration how a particular statistic is stored. By default, it needs no configuration at all.

use Spatie\Stats\BaseStats;

class SubscriptionStats extends BaseStats {}

By default, the name of the class will be used to store the statistics in the database. To customize the used key, use getName

use Spatie\Stats\BaseStats;

class SubscriptionStats extends BaseStats
{
    public function getName() : string{
        return 'my-custom-name'; // stats will be stored with using name `my-custom-name`
    }
}

Step 2: call increase and decrease or set a fixed value

Next, you can call increase, decrease when the stat should change. In this particular case, you should call increase on it when somebody subscribes, and decrease when somebody cancels their plan.

SubscriptionStats::increase(); // execute whenever somebody subscribes
SubscriptionStats::decrease(); // execute whenever somebody cancels the subscription;

Instead of manually increasing and decreasing the stat, you can directly set it. This is useful when your particular stat does not get calculated by your own app, but lives elsewhere. Using the subscription example, let's image that subscriptions live elsewhere, and that there's an API call to get the count.

$count = AnAPi::getSubscriptionCount(); 

SubscriptionStats::set($count);

By default, that increase, decrease and set methods assume that the event that caused your stats to change, happened right now. Optionally, you can pass a date time as a second parameter to these methods. Your stat change will be recorded as if it happened on that moment.

SubscriptionStats::increase(1, $subscription->created_at);

Step 3: query the stats

With this in place, you can query the stats. You can fetch stats for a certain period and group them by minute, hour, day, week, month, or year.

Here's how you can get the subscription stats for the past two months, grouped by week.

$stats = SubscriptionStats::query()
    ->start(now()->subMonths(2))
    ->end(now()->subSecond())
    ->groupByWeek()
    ->get();

This will return an array containing arrayable Spatie\Stats\DataPoint objects. These objects can be cast to arrays like this:

// output of $stats->toArray():
[
    [
        'start' => '2020-01-01',
        'end' => '2020-01-08',
        'value' => 102,
        'increments' => 32,
        'decrements' => 20,
        'difference' => 12,
    ],
    [
        'start' => '2020-01-08',
        'end' => '2020-01-15',
        'value' => 114,
        'increments' => 63,
        'decrements' => 30,
        'difference' => 33,
    ],
]

Extended Use-Cases

Read and Write from a custom Model

Create a new table with type (string), value (bigInt), created_at, updated_at fields
Create a model and add HasStats-trait

StatsWriter::for(MyCustomModel::class)->set(123)
StatsWriter::for(MyCustomModel::class, ['custom_column' => '123'])->increase(1)
StatsWriter::for(MyCustomModel::class, ['another_column' => '234'])->decrease(1, now()->subDay())

$stats = StatsQuery::for(MyCustomModel::class)
    ->start(now()->subMonths(2))
    ->end(now()->subSecond())
    ->groupByWeek()
    ->get();
    
// OR

$stats = StatsQuery::for(MyCustomModel::class, ['additional_column' => '123'])
    ->start(now()->subMonths(2))
    ->end(now()->subSecond())
    ->groupByWeek()
    ->get();

Read and Write from a HasMany-Relationship

$tenant = Tenant::find(1) 

StatsWriter::for($tenant->orderStats(), ['payment_type_column' => 'recurring'])->increment(1)

$stats = StatsQuery::for($tenant->orderStats(), , ['payment_type_column' => 'recurring'])
    ->start(now()->subMonths(2))
    ->end(now()->subSecond())
    ->groupByWeek()
    ->get();

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

spatie / laravel-stats

Maintainers

Details