Filament Statefusion Laravel Package

Technical Evaluation

Architecture Fit

• State Management Alignment: The package leverages Spatie Laravel Model States, a battle-tested solution for stateful models, and integrates it with FilamentPHP, a modern Laravel admin panel. This is a strong architectural fit for applications requiring workflow-driven state transitions (e.g., order processing, content moderation, approval pipelines).
• Filament Ecosystem Synergy: Since Filament is built on Laravel Livewire, this package natively extends Filament’s UI capabilities without requiring custom frontend logic, reducing complexity.
• Domain-Driven Design (DDD) Support: Ideal for bounded contexts where state transitions are critical (e.g., e-commerce, SaaS platforms, CMS workflows).

Integration Feasibility

• Low-Coupling Design: The package does not modify core Filament or Spatie logic, making it easy to adopt incrementally.
• Filament Plugin System: Since it’s a Filament plugin, integration follows Filament’s standard plugin registration (config/filament.php), minimizing boilerplate.
• Spatie Compatibility: Requires Laravel Model States (v3.x+), which is widely adopted. If the app already uses Spatie’s package, integration is near-zero effort.

Technical Risk

Key Questions

1. Does the application already use Spatie Laravel Model States?
   • If no, assess the effort to migrate existing state logic to Spatie’s format.
2. What Filament version is in use?
   • Ensure compatibility with the package’s minimum Filament requirement (v3.x).
3. Are there custom state transition rules beyond Spatie’s defaults?
   • If yes, evaluate whether Filament’s UI can accommodate them without heavy customization.
4. How critical are real-time state updates?
   • If high, test Livewire reactivity under load with complex state graphs.
5. Does the team have experience with Filament plugins?
   • If no, allocate time for plugin development best practices (e.g., service providers, publishable config).

Integration Approach

Stack Fit

• Primary Stack: Laravel (v10.x+) + FilamentPHP (v3.x) + Spatie Laravel Model States (v3.x+).
• Secondary Stack:
  • Works with: Any Filament resource/page using Eloquent models.
  • Conflicts with: Custom Filament UI components that override state-related logic (e.g., manual form submissions).
• Non-Fit Scenarios:
  • Non-Filament Laravel apps: Requires a separate UI layer (e.g., Livewire standalone).
  • Non-Spatie state management: Would need a wrapper layer to adapt existing state logic.

Migration Path

1. Prerequisite Check:
   • Verify spatie/laravel-model-states is installed (composer require spatie/laravel-model-states).
   • Ensure Filament is v3.x (composer require filament/filament:"^3.0").
2. Installation:

   composer require a909m/filament-statefusion
   

3. Configuration:
   • Publish the package config (if needed):

     php artisan vendor:publish --provider="A909M\FilamentStateFusion\FilamentStateFusionServiceProvider"
     

   • Register the plugin in config/filament.php:

     'plugins' => [
         \A909M\FilamentStateFusion\Plugin::make(),
     ],
     

4. Model Integration:
   • Use Spatie’s state traits on Eloquent models:

     use Spatie\ModelStates\HasStates;
     
     class Order extends Model
     {
         use HasStates;
     }
     

   • Define states in a migration:

     Schema::create('order_states', function (Blueprint $table) {
         $table->id();
         $table->string('name')->unique();
         $table->json('data')->nullable();
         $table->timestamps();
     });
     

5. Filament Resource Enhancement:
   • Extend a Filament resource to include state management:

     use A909M\FilamentStateFusion\Concerns\HasStateFusion;
     
     class OrderResource extends Resource
     {
         use HasStateFusion;
     }
     

6. Testing:
   • Test state transitions via Filament’s UI and API.
   • Validate authorization policies (if using Filament’s gates).

Compatibility

Sequencing

1. Phase 1: Core Integration (1–2 days)
   • Install package, configure Filament plugin, and integrate a single model (e.g., Order).
2. Phase 2: UI/UX Validation (1 day)
   • Test state transitions, filtering, and workflows in Filament.
   • Adjust state labels, colors, and transition buttons via config.
3. Phase 3: Rollout (Ongoing)
   • Gradually apply to other stateful models (e.g., Post, Subscription).
   • Monitor performance impact on complex workflows.

Operational Impact

Maintenance

• Proactive Maintenance:
  • Dependency Updates: Monitor a909m/filament-statefusion, spatie/laravel-model-states, and Filament for breaking changes.
  • Plugin Configuration: Centralize state-related settings in config/filament-statefusion.php for easy updates.
• Reactive Maintenance:
  • State Transition Bugs: Isolate issues by testing with minimal state configurations.
  • Filament Updates: Test plugin compatibility after major Filament releases.

Support

• Troubleshooting:
  • Common Issues:
    • State transitions not appearing in Filament → Check HasStateFusion trait usage.
    • Permission errors → Verify Filament’s gates/policies for state actions.
  • Debugging Tools:
    • Use php artisan state:list (Spatie) to inspect model states.
    • Enable Filament’s debug mode (config/filament.php) for UI issues.
• Documentation Gaps:
  • The package lacks advanced customization docs (e.g., overriding transition logic).
  • Workaround: Study Spatie’s Model States docs and Filament’s plugin system.

Scaling

• Performance Considerations:
  • N+1 Queries: State transitions may trigger additional queries. Mitigate with:
    • Eager loading states in Filament resources:

      public static function getRelations(): array
      {
          return [
              'states',
          ];
      }
      

    • Caching frequently accessed state data (e.g., state:cache Spatie command).
  • Complex Workflows: For highly interconnected states, consider:
    • Lazy-loading state transition options.
    • Background jobs for non-critical transitions (e.g., state:transition via queue).
• Horizontal Scaling:
  • Stateless by design; no distributed lock requirements for basic usage.
  • Edge Case: Concurrent state changes may require optimistic locking ($model->fresh()).

Failure Modes