Filament Queueable Bulk Actions Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require bytexr/filament-queueable-bulk-actions
   

   Choose the correct version (^5.0, ^4.0, or ^3.0) based on your Filament version.

2. Publish Assets: Run migrations and publish config/views:

   php artisan vendor:publish --tag="queueable-bulk-actions-migrations"
   php artisan vendor:publish --tag="queueable-bulk-actions-config"
   php artisan vendor:publish --tag="queueable-bulk-actions-views"  # Optional
   php artisan migrate
   

3. Register Plugin: Add to app/Providers/Filament/PluginServiceProvider.php:

   public function register(): void
   {
       Filament::plugin(QueueableBulkActionsPlugin::make());
   }
   

First Use Case: Queueable Bulk Delete

1. Define a Queueable Action in your Filament resource:

   use Bytexr\FilamentQueueableBulkActions\Actions\QueueableAction;
   
   public static function getBulkActions(): array
   {
       return [
           QueueableAction::make('delete')
               ->action(function (Collection $records) {
                   foreach ($records as $record) {
                       $record->delete();
                   }
               })
               ->queueable()
               ->successNotificationTitle('Records deleted')
               ->successNotificationDescription('{count} records were deleted successfully.')
       ];
   }
   

2. Trigger the Action:

   • Select records in the Filament table.
   • Click the "Queue Delete" button (auto-generated by the package).
   • Monitor progress via the Queue Jobs widget (auto-included).

Implementation Patterns

Workflow: Bulk Data Processing

1. Define Queueable Actions: Use QueueableAction for any bulk operation (e.g., updates, exports, API calls):

   QueueableAction::make('export')
       ->action(function (Collection $records) {
           Export::queue(new RecordsExport($records));
       })
       ->queueable()
       ->queueableOptions(['chunks' => 50]) // Process in chunks
       ->successNotificationTitle('Export queued')
   

2. Real-Time Feedback: Leverage Livewire for progress updates:

   QueueableAction::make('update-status')
       ->action(function (Collection $records) {
           foreach ($records as $record) {
               UpdateStatusJob::dispatch($record);
           }
       })
       ->queueable()
       ->livewire() // Enables Livewire progress tracking
   

3. Custom Job Handling: Extend QueueableBulkAction for complex logic:

   class CustomQueueableAction extends QueueableAction
   {
       protected static string $view = 'filament-queueable-bulk-actions::actions.custom';
   
       public function mount(): void
       {
           $this->fillForm([
               'custom_option' => 'default_value',
           ]);
       }
   }
   

Integration Tips

• Queue Configuration: Configure config/queueable-bulk-actions.php to customize:

  • Default queue connection (default).
  • Job batch size (batch_size).
  • Notification channels (notifications).

• Queue Monitoring: Use the built-in Queue Jobs widget or integrate with Laravel Horizon:

  Filament::serving(function () {
      Filament::registerWidget(
          \Bytexr\FilamentQueueableBulkActions\Widgets\QueueJobsWidget::class
      );
  });
  

• Custom Views: Override default views by publishing and modifying:

  php artisan vendor:publish --tag="queueable-bulk-actions-views"
  

Gotchas and Tips

Pitfalls

1. Queue Connection Mismatch:

   • Ensure your queue worker (queue:work) is running on the same connection specified in config/queueable-bulk-actions.php.
   • Debug with:

     php artisan queue:failed-table
     php artisan queue:work --queue=your_queue_name
     

2. Livewire Conflicts:

   • If Livewire progress tracking fails, verify:
     • The action has ->livewire() called.
     • No JavaScript errors in browser console (check filament-queueable-bulk-actions.js).

3. Batch Size Limits:

   • Large batches may hit memory limits. Adjust queueableOptions(['chunks' => N]) or use database transactions:

     QueueableAction::make('process')
         ->action(function (Collection $records) {
             DB::transaction(function () use ($records) {
                 foreach ($records->chunk(100) as $chunk) {
                     ProcessJob::dispatch($chunk);
                 }
             });
         })
     

Debugging

• Log Queueable Actions: Enable debug mode in config:

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

  Check logs at storage/logs/laravel.log.

• Failed Jobs: Retry failed jobs manually:

  php artisan queue:retry all
  

Extension Points

1. Custom Job Classes: Extend QueueableBulkActionJob for reusable logic:

   class MyCustomJob extends QueueableBulkActionJob
   {
       public function handle()
       {
           // Custom logic here
           $this->updateProgress(50);
       }
   }
   

2. Notification Overrides: Override default notifications by binding events:

   event(new QueueableBulkActionCompleted($action, $records));
   

3. API Integration: Trigger queueable actions via API:

   Route::post('/bulk-queue', function (Request $request) {
       $action = app(YourResource::class)
           ->getBulkActions()['queueable-action-key'];
   
       return $action->queue($request->selected_records);
   });
   

Pro Tips

• Soft Deletes: Combine with SoftDeletes for safer bulk operations:

  QueueableAction::make('soft-delete')
      ->action(function (Collection $records) {
          foreach ($records as $record) {
              $record->delete(); // Uses softDelete if enabled
          }
      })
      ->queueable()
  

• Rate Limiting: Use Laravel’s throttle to prevent queue overload:

  QueueableAction::make('rate-limited')
      ->action(function (Collection $records) {
          foreach ($records as $record) {
              RateLimitedJob::dispatch($record)->throttle(10);
          }
      })