Filament Simple Stats Laravel Package

Getting Started

Minimal Setup

1. Installation (Laravel 10/11/13 compatible):

   composer require spatie/filament-simple-stats
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="Spatie\FilamentSimpleStats\FilamentSimpleStatsServiceProvider"
   

2. First Use Case (Laravel 13+ compatible): Add a stat to a Filament dashboard resource or page:

   use Spatie\FilamentSimpleStats\Stat;
   
   public static function getStats(): array
   {
       return [
           Stat::make('Total Users', 'users_count')
               ->model(User::class),
           Stat::make('Active Users', 'active_users_count')
               ->query(fn () => User::where('last_active_at', '>', now()->subDays(7))->count()),
       ];
   }
   

3. Data Source: Define a getStats() or getWidgets() method in your dashboard/resource class. The package now supports inline laravel-trend (no separate package required for trends).

Implementation Patterns

Core Workflows

1. Basic Model Stats (Laravel 13+):

   Stat::make('Orders', 'orders_count')
       ->model(Order::class)
       ->description('Total orders in the system');
   

   • Automatically queries Order::count() and caches results (configurable).

2. Custom Queries (Laravel 13+):

   Stat::make('Revenue', 'revenue')
       ->query(fn () => Order::sum('amount'))
       ->description('Total revenue (USD)');
   

3. Trend Integration (now inline with laravel-trend):

   Stat::make('Monthly Users', 'monthly_users')
       ->model(User::class)
       ->trend() // No separate package needed
       ->description('New users per month');
   

   • Requires a created_at column (no additional setup for laravel-trend).

4. Dashboard Integration (Laravel 13+):

   public static function getWidgets(): array
   {
       return [
           StatWidget::make('Sales Overview', [
               Stat::make('Total Sales', 'sales_count')
                   ->model(Order::class),
               Stat::make('Avg. Sale', 'avg_sale')
                   ->query(fn () => Order::avg('amount')),
           ]),
       ];
   }
   

Advanced Patterns (Laravel 13+)

• Dynamic Descriptions:

  Stat::make('Users', 'users_count')
      ->description(fn () => "Total users: " . User::count());
  

• Custom Icons (Laravel 13+):

  Stat::make('Users', 'users_count')
      ->icon('heroicon-o-users');
  

• Grouping Stats:

  StatWidget::make('User Metrics', [
      Stat::make('Total Users', 'users_count'),
      Stat::make('Active Users', 'active_users_count'),
  ]);
  

Gotchas and Tips

Common Pitfalls

1. Missing getStats()/getWidgets() Method:

   • Ensure your dashboard/resource implements either getStats() or getWidgets().
   • Fix: Add the method and return an array of Stat instances.

2. Trend Data Requirements:

   • created_at column is required for trends (no additional package needed).
   • Fix: Ensure your model has a created_at timestamp.

3. Caching Issues:

   • Stats cache by default (1 hour). Clear cache if data doesn’t update:

     php artisan cache:clear
     

   • Tip: Disable caching for real-time stats:

     Stat::make('Live Users', 'live_users')->cache(false);
     

4. Laravel 13+ Compatibility:

   • If using Laravel 13, ensure your config/app.php includes:

     'providers' => [
         // ...
         Spatie\FilamentSimpleStats\FilamentSimpleStatsServiceProvider::class,
     ],
     

Debugging Tips

• Log Stat Queries: Enable debug mode in config/filament-simple-stats.php:

  'debug' => env('STATS_DEBUG', false),
  

  • Logs queries to storage/logs/filament-simple-stats.log.

• Check Config: Verify config/filament-simple-stats.php for customizations (e.g., cache duration, default icons).

Extension Points

1. Custom Stat Classes: Extend Spatie\FilamentSimpleStats\Stat for reusable logic:

   class RevenueStat extends Stat
   {
       public function __construct()
       {
           parent::__construct('Revenue', 'revenue');
           $this->query(fn () => Order::sum('amount'));
       }
   }
   

2. Override Defaults: Publish the config and modify:

   php artisan vendor:publish --tag="filament-simple-stats-config"
   

   • Adjust cache_duration, default_icon, or trend_options.

3. Localization: Translate stat labels/descriptions using Filament’s localization:

   Stat::make('Users', 'users_count')
       ->label(__('stats.users'))
       ->description(__('stats.total_users'));
   

Laravel 13-Specific Notes

• No laravel-trend Package Needed: Trends are now bundled inline—no additional composer require is required.
• Bootstrap Changes: If upgrading from Laravel 10/11, ensure your bootstrap/app.php includes:

  $app->register(\Spatie\FilamentSimpleStats\FilamentSimpleStatsServiceProvider::class);