Filament Statefusion Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require a909m/filament-statefusion
   

   Publish the config (if needed):

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

2. Register the Plugin Add to app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               \A909M\FilamentStateFusion\FilamentStateFusionPlugin::make(),
           ]);
   }
   

3. First Use Case: Display States in a Resource For a Post model with states (e.g., draft, published), annotate the resource:

   use A909M\FilamentStateFusion\Concerns\HasStates;
   
   class PostResource extends Resource
   {
       use HasStates;
   
       // ...
   }
   

   States will auto-render in the table, form, and detail views.

Implementation Patterns

Core Workflows

1. State-Aware Tables Filter records by state in the table view:

   public static function table(Table $table): Table
   {
       return $table
           ->columns([
               // ...
               StatesColumn::make('state'),
           ]);
   }
   

2. State Transitions in Forms Add a state transition button to forms:

   public static function form(Form $form): Form
   {
       return $form
           ->schema([
               // ...
               StatesWidget::make('state')
                   ->transitions([
                       'publish' => 'Publish',
                       'draft' => 'Save as Draft',
                   ]),
           ]);
   }
   

3. State-Based Permissions Restrict state transitions via Filament policies:

   public function canPublish(Post $record): bool
   {
       return $record->state->is('draft');
   }
   

4. Custom State Logic Extend state behavior in the model:

   class Post extends Model
   {
       use \Spatie\ModelStates\HasStates;
   
       protected $states = [
           'draft' => ['color' => 'gray-500'],
           'published' => ['color' => 'green-500'],
       ];
   
       public function publish(): void
       {
           $this->transitionTo('published');
           // Additional logic (e.g., notify subscribers)
       }
   }
   

5. Bulk State Actions Add bulk state transitions to table actions:

   public static function table(Table $table): Table
   {
       return $table
           ->actions([
               Tables\Actions\BulkAction::make('publish')
                   ->action(function (Collection $records) {
                       foreach ($records as $record) {
                           $record->transitionTo('published');
                       }
                   }),
           ]);
   }
   

Gotchas and Tips

Common Pitfalls

1. State Not Reflecting in UI

   • Ensure the model uses HasStates trait from Spatie, not a custom implementation.
   • Clear cache after adding new states:

     php artisan optimize:clear
     

2. Transition Buttons Missing

   • Verify the states array in the model includes the transition targets.
   • Check Filament permissions (e.g., canPublish policy).

3. Stale State Colors

   • Override colors in the model’s $states array or via the StatesWidget:

     StatesWidget::make('state')
         ->colors([
             'draft' => 'amber-500',
             'published' => 'emerald-500',
         ])
     

4. Performance with Large Datasets

   • Use eagerLoadStates() in the resource’s getTableRecords() to avoid N+1 queries:

     public static function getTableRecords(Table $table): Collection
     {
         return Post::query()
             ->withStates()
             ->get();
     }
     

Debugging Tips

• Log State Transitions Add a model observer to track transitions:

  class PostStateObserver
  {
      public function transitioned(Post $post, string $from, string $to)
      {
          \Log::info("State transition: {$from} -> {$to}", ['post_id' => $post->id]);
      }
  }
  

• Inspect Filament StateFusion Events Listen for state-related events in EventServiceProvider:

  protected $listen = [
      \A909M\FilamentStateFusion\Events\StateTransitioning::class => [
          function ($event) {
              \Log::debug('Transitioning state', $event->state);
          },
      ],
  ];
  

Extension Points

1. Custom State Widgets Create a custom widget for complex state logic:

   class CustomStatesWidget extends StatesWidget
   {
       protected function getTransitions(): array
       {
           return [
               'approve' => Translatable::make('Approve'),
               'reject' => Translatable::make('Reject'),
           ];
       }
   }
   

2. State-Based Table Filters Dynamically filter tables by state:

   public static function getTableFilters(Table $table): array
   {
       return [
           \A909M\FilamentStateFusion\Tables\Filters\StateFilter::make('state')
               ->states(['draft', 'published']),
       ];
   }
   

3. Integrate with Filament Actions Trigger state transitions from custom actions:

   Tables\Actions\Action::make('archive')
       ->action(function (Post $record) {
           $record->transitionTo('archived');
           $record->save();
       }),
   

4. Localization Translate state labels and transitions:

   StatesWidget::make('state')
       ->translatable()
       ->translations([
           'draft' => 'Rascunho',
           'published' => 'Publicado',
       ]),