Filament Plugin Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require simplestats-io/filament-plugin
   

2. Add API token to .env:

   SIMPLESTATS_API_TOKEN=your_api_token_here
   

3. Register the plugin in your PanelProvider:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugin(SimplestatsPlugin::make());
   }
   

4. Access the dashboard at /admin/simplestats (or your Filament panel path + /simplestats).

First Use Case

• Quick analytics overview: Immediately see key metrics (visitors, revenue, registrations) without leaving Filament.
• Time-range filtering: Use the dropdown to compare today’s stats vs. last week or month.

Implementation Patterns

Core Workflows

1. Plugin Registration Customize navigation and appearance:

   SimplestatsPlugin::make()
       ->navigationGroup('Analytics')
       ->navigationLabel('Business Stats')
       ->navigationIcon('heroicon-o-chart-pie')
       ->cacheTtl(300); // 5-minute cache
   

2. Self-Hosted Integration Override API URL for private instances:

   SimplestatsPlugin::make()
       ->apiUrl('https://your-simplestats.com/api/v1');
   

3. Dynamic Widget Usage Reuse widgets in custom Filament pages:

   use SimpleStatsIo\FilamentPlugin\Widgets\StatsOverview;
   
   public function getWidgets(): array
   {
       return [
           StatsOverview::class,
           // Other widgets...
       ];
   }
   

Integration Tips

• Cache Optimization: Set cacheTtl to balance freshness vs. API calls (e.g., 60 for 1-minute updates).
• Environment Variables: Prefer .env for tokens/URLs to avoid hardcoding:

  SIMPLESTATS_API_URL=https://custom-api.example.com
  SIMPLESTATS_API_TOKEN=${SIMPLESTATS_TOKEN}
  

• Livewire Compatibility: Widgets auto-update with Filament’s Livewire hooks—no manual refresh needed.

Gotchas and Tips

Common Pitfalls

1. API Token Errors

   • Symptom: Blank dashboard or 401 Unauthorized.
   • Fix: Verify .env token and check SimpleStats.io for token validity.
   • Debug: Temporarily disable caching (cacheTtl=0) to rule out stale responses.

2. Navigation Missing

   • Cause: Plugin not registered in PanelProvider.
   • Fix: Ensure ->plugin(SimplestatsPlugin::make()) is called in panel() method.

3. Chart Data Stale

   • Workaround: Adjust cacheTtl or clear cache:

     php artisan cache:clear
     

Debugging Tips

• API Logs: Enable Laravel’s debug mode (APP_DEBUG=true) to inspect HTTP requests.
• Widget Isolation: Test individual widgets (e.g., StatsOverview) in isolation to identify misbehaving components.
• Drilldown Filter: Use the comparison feature (v1.2.0+) to debug time-range discrepancies:

  // Example: Compare "This Month" vs. "Last Month"
  SimplestatsPlugin::make()->enableComparison();
  

Extension Points

1. Custom Metrics Extend the plugin by adding new widgets. Example:

   // app/Filament/Widgets/CustomMetric.php
   use SimpleStatsIo\FilamentPlugin\Widgets\BaseWidget;
   
   class CustomMetric extends BaseWidget {
       protected static string $view = 'filament.simplestats.custom-metric';
       // ...
   }
   

2. Override Views Publish and modify views:

   php artisan vendor:publish --tag="simplestats-filament-views"
   

   Then edit resources/views/vendor/filament/simplestats/....

3. API Response Hooks Intercept responses via a service provider:

   public function boot()
   {
       SimpleStatsIo\FilamentPlugin\Services\ApiClient::macro('beforeRequest', function ($request) {
           // Modify request/response (e.g., add headers)
       });
   }
   

Configuration Quirks

• Zero Cache (cacheTtl=0): Disables caching entirely; useful for development but impacts performance.
• Navigation Sort: Lower numbers appear first (e.g., navigationSort(1) for top priority).
• Self-Hosted URLs: Must end with /api/v1 to match the plugin’s expectations.