Weave Code
Laravel Stats Laravel Package
spatie/laravel-stats
Lightweight Laravel package that summarizes database changes over time. Define a stats class, call increase() or decrease() as events happen, then query totals grouped by day, week, or month, returning increments, decrements, and net differences for each period.
spatie/laravel-stats is a lightweight package for tracking changes in your database over time. Define a stats class extending BaseStats, then call increase() or decrease() whenever a relevant event occurs—such as a subscription or cancellation. Query the accumulated data with a fluent API and group results by week, month, or day.
- Simple tracking via
increase()anddecrease()calls - Flexible queries with
start(),end(), and grouping methods - Rich output including value, increments, decrements, and difference
- Date-range filtering for precise historical reports
- Framework-native integration with Laravel's Eloquent and collections
Frequently asked questions about Laravel Stats
- How do I install spatie/laravel-stats in a Laravel app?
- Install it with Composer using composer require spatie/laravel-stats. Publish and run the package migration so the stats table exists, then create a stats class that extends Spatie\Stats\BaseStats. You can call increase() or decrease() from your domain events or model observers once the migration is in place.
- What is the difference between increase(), decrease(), and set() in spatie/laravel-stats?
- increase() records a positive delta and decrease() records a negative delta against a stat key. set() is useful when the source of truth lives outside your application, such as a scheduled reconciliation job that writes an absolute value. The query layer then calculates totals, increments, decrements, and net difference from the recorded changes.
- How do I group stats by day, week, month, or year?
- Use the fluent StatsQuery builder from your stats class, for example SubscriptionStats::query()->start(...)->end(...)->groupByWeek()->get(). The package supports grouping by day, week, month, and year, and also provides finer buckets such as minute and hour. Each result includes a start date, end date, value, increments, decrements, and difference for that period.
- Can I track stats for a specific model or tenant?
- Yes. The StatsWriter and StatsQuery for() API added in version 2.0 lets you anchor stats to an Eloquent model, a class, or a HasMany relationship, with optional attribute filters. This makes per-tenant counters practical in multi-tenant SaaS applications because stats can be keyed by relationship instead of a single global namespace. You can then query only the stats associated with that model or tenant.
- Does spatie/laravel-stats support Laravel 10, 11, 12, and 13?
- The package has an active changelog and reached version 2.4.0 with Laravel 13 support. For exact version constraints, check the composer.json on Packagist and the repository changelog before upgrading a production application. Spatie packages generally track current Laravel releases, but you should still verify the constraint for your specific Laravel version.
- How do I backdate a stat change or backfill historical data?
- The increase() method accepts a backdating parameter, so you can pass a timestamp such as $subscription->created_at as the second argument. This is useful for historical backfills and for correcting domain events that fire out of order or are replayed from a queue. You can also use set() from a scheduled job to reconcile a counter from an external system.
- How do I test stats in my Laravel application?
- Use Laravel's normal testing tools, such as RefreshDatabase, and call your stats class methods inside the test. Then query the stats with StatsQuery or assert the expected rows in the stats table. The package does not replace your application test suite, so focus assertions on the increments, decrements, and grouped totals your business logic should produce.
- What database drivers does spatie/laravel-stats support?
- MySQL is the most commonly used and best-tested database for this package. PostgreSQL support was added in version 2.0.3, SQLite support was completed in version 2.2.0, and table-prefix handling was fixed in version 2.0.2. Because the SQL generation layer has been hardened incrementally, test your specific driver and query groupings before relying on it in production.
- Does spatie/laravel-stats handle retention or pruning of old stat records?
- No. The package stores stat changes as an event log and does not ship retention policies, pruning commands, or archival features. At high write volumes the stats table can grow without bound, so you should plan your own retention or archival strategy. This is an application-level concern rather than something the package manages for you.
- What are alternatives to spatie/laravel-stats for tracking metrics?
- spatie/laravel-stats is best treated as auditable business counters with time-bucketed rollups, not as a full metrics platform. If you need dashboards, alerting, cardinality management, or long-term time-series storage, consider a dedicated metrics or APM system alongside it. Alternatives include building custom aggregate tables, using a time-series database, or adopting a broader analytics or monitoring service.
Weaver
How can I help you explore Laravel packages today?