Filament Simple Stats Laravel Package

Technical Evaluation

Architecture Fit

• Pros:

  • Filament Integration: Seamlessly integrates with Filament’s widget ecosystem, leveraging its existing dashboard infrastructure (e.g., filament/widgets). Aligns with Filament’s modular design, allowing for easy extension or customization of stat widgets.
  • Trend Analytics: Built on flowframe/laravel-trend (now inlined), providing out-of-the-box period-over-period comparisons (e.g., daily/weekly/monthly trends). Reduces reliance on third-party analytics tools for basic metrics.
  • Eloquent-First: Supports Eloquent models and raw query builders, making it versatile for most Laravel applications using ORM or custom queries.
  • Opinionated Simplicity: Abstracts complexity (e.g., trend calculations, UI rendering) behind a clean API, accelerating development for non-data-science teams.

• Cons:

  • Tight Coupling to Filament: Limited utility outside Filament dashboards. If the application uses alternative admin panels (e.g., Nova, Backpack), this package offers no direct value.
  • Trend Logic: Trends are hardcoded to compare against the previous period (e.g., yesterday vs. today). Custom trend logic (e.g., YoY, custom date ranges) requires extending the package.
  • No Real-Time Data: Relies on database queries; not suitable for real-time dashboards (e.g., WebSocket-driven updates).

Integration Feasibility

• Dependencies:
  • Core: Laravel 10–13, Filament v5.2+, PHP 8.1+. Minimal additional dependencies (only flowframe/laravel-trend is inlined).
  • Database: Requires Eloquent models or query builders. No support for non-SQL data sources (e.g., GraphQL, external APIs).
• Compatibility:
  • Filament Version: Must align with Filament’s widget API (v5.2+). Downgrading Filament may break functionality.
  • Query Complexity: Works best with simple aggregations (e.g., count, sum). Complex joins or subqueries may require custom query building.
• Customization:
  • Styling: Uses Filament’s default styling. Overriding CSS/JS requires extending the widget class.
  • Data Sources: Limited to Eloquent models. For non-model data (e.g., cache, external APIs), users must implement a custom SimpleStat adapter.

Technical Risk

• Low:
  • Maturity: Actively maintained (releases every 1–2 months), with clear documentation and tests. MIT license reduces legal risk.
  • Adoption: 26 GitHub stars and Filament’s popularity suggest stable demand.
• Medium:
  • Performance: Heavy queries (e.g., last30Days()->dailySum()) could impact dashboard load times if not optimized (e.g., caching, database indexing).
  • Trend Logic: Assumes linear period-over-period comparisons. Edge cases (e.g., holidays, irregular intervals) may require customization.
• High:
  • Filament Lock-in: Migrating away from Filament would require rewriting widgets.
  • Query Injection: Dynamic where clauses could expose SQL injection risks if not sanitized (though Eloquent mitigates this).

Key Questions

1. Use Case Alignment:
   • Are we using Filament for dashboards? If not, is this package worth the Filament dependency?
   • Do we need real-time updates, or are periodic refreshes sufficient?
2. Data Complexity:
   • Are our metrics simple aggregations (e.g., counts, sums), or do we need custom trend logic?
   • Will we need to extend the package for non-Eloquent data sources?
3. Performance:
   • How will these queries scale with large datasets? Are we prepared to add caching (e.g., Redis) or database optimizations?
4. Customization Needs:
   • Do we need to override default styling or add custom widgets beyond the provided templates?
5. Maintenance:
   • Who will own updates if Filament or Laravel versions change? Is the team comfortable with dependency updates?

Integration Approach

Stack Fit

• Primary Fit:
  • Laravel + Filament: Ideal for applications already using Filament for admin panels. Leverages Filament’s widget system to embed stats without reinventing UI components.
  • Eloquent-Based Apps: Perfect for apps using Eloquent models for core data (e.g., SaaS platforms, CMS, e-commerce).
• Secondary Fit:
  • Analytics-Heavy Apps: Useful for teams needing lightweight trend analysis without building custom charts (e.g., marketing dashboards, internal tools).
• Non-Fit:
  • Non-Filament Admin Panels: Nova, Backpack, or custom admin panels would require significant refactoring to use this package.
  • Real-Time Systems: Not suitable for WebSocket-driven or event-based dashboards.

Migration Path

1. Assessment Phase:
   • Audit existing dashboards to identify metrics that could be replaced by SimpleStat.
   • Verify Filament version compatibility (target v5.2+).
2. Pilot Implementation:
   • Start with a single dashboard widget (e.g., user signups) to test performance and customization.
   • Example:

     use Spatie\FilamentSimpleStats\SimpleStat;
     
     class UserStatsWidget extends Widget {
         protected function getStats(): array {
             return [
                 SimpleStat::make(User::class)
                     ->last7Days()
                     ->dailyCount()
                     ->invertTrendColors(), // If fewer users is "better"
             ];
         }
     }
     

3. Incremental Rollout:
   • Replace custom stat widgets with SimpleStat one by one.
   • Gradually migrate complex queries to use the package’s API (e.g., replace raw SQL with Eloquent).
4. Optimization:
   • Add caching (e.g., Cache::remember) for frequently accessed stats.
   • Optimize database queries (e.g., add indexes for created_at fields).

Compatibility

• Filament Widgets:
  • Extends filament/widgets, so it works with Filament’s widget groups, layouts, and permissions.
  • Supports all Filament widget features (e.g., canAccess, header, columns).
• Query Builders:
  • Works with Eloquent models and raw query builders (since v1.2.1). Example for raw queries:

    SimpleStat::make(fn () => DB::table('orders')->selectRaw('sum(amount) as total'))
        ->last30Days()
        ->dailySum('total');
    

• Trend Dependencies:
  • Inlined flowframe/laravel-trend, so no additional setup is needed beyond the package installation.

Sequencing

1. Prerequisites:
   • Ensure Laravel and Filament are up-to-date (v10+ and v5.2+, respectively).
   • Install the package:

     composer require spatie/filament-simple-stats
     

   • Publish Filament resources if customizing views:

     php artisan vendor:publish --tag=filament-widgets
     

2. Core Integration:
   • Create a new widget class extending Widget and implement getStats().
   • Example structure:

     app/Filament/Widgets/UserStatsWidget.php
     

3. Testing:
   • Test widgets in a staging environment with realistic data volumes.
   • Verify trend calculations for edge cases (e.g., no data, negative values).
4. Deployment:
   • Deploy to production and monitor performance (e.g., query execution time, cache hit rate).
5. Post-Launch:
   • Set up monitoring for widget load times and database query performance.
   • Plan for future Filament/Laravel updates (check changelogs for breaking changes).

Operational Impact

Maintenance

• Pros:
  • Low Effort: Minimal maintenance required for basic usage. Updates are handled via Composer.
  • Community Support: Spatie’s packages have strong community backing (e.g., GitHub discussions, issue resolution).
  • Documentation: Clear README and changelog reduce onboarding time.
• Cons:
  • Dependency Updates: Must stay aligned with Filament and Laravel versions. Example: Updating Filament from v5.2 to v6 may require package updates.
  • Custom Extensions: Any customizations (e.g., new stat types) must be maintained in-house.

Support

• Internal:
  • Onboarding: Developers familiar with Filament and Eloquent will adopt this quickly. Non-technical stakeholders may need training on interpreting trends.
  • Troubleshooting: Common issues (e.g., query errors, styling conflicts) can be resolved by reviewing Filament’s widget documentation.
• External:
  • Vendor Support: Spatie offers paid support for commercial projects. Open-source issues are handled via GitHub.
  • Community: Active GitHub discussions and Stack Overflow tags (e.g., filament, laravel-trend) provide peer support.

Scaling

• Performance:
  • Database Load: Each stat widget triggers a query. For dashboards with 1