Filament Jobs Monitor Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require croustibat/filament-jobs-monitor
   php artisan vendor:publish --tag="filament-jobs-monitor-migrations"
   php artisan migrate
   

   Verify your FilamentPHP version matches the package requirements (check README table).

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

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               \Croustibat\FilamentJobsMonitor\Plugin::make(),
           ]);
   }
   

3. First Use Case: Dispatch a job (e.g., php artisan queue:work) and navigate to the Jobs Monitor plugin in Filament. Observe real-time job statuses (queued, processing, failed).

Implementation Patterns

Core Workflows

1. Job Dispatching & Tracking:

   • Use standard Laravel job dispatching (dispatch(), dispatchNow()).
   • The plugin auto-captures jobs via Laravel’s Illuminate\Queue\Events\JobProcessed and JobFailed listeners (no manual instrumentation needed).

2. Queue Configuration:

   • Supports all drivers (database, redis, sync, etc.). No driver-specific setup required.
   • For custom queues, ensure the queue connection is configured in config/queue.php and the plugin’s migrations are up-to-date.

3. Filament Integration:

   • Resource vs. Plugin:
     • Use the plugin for lightweight monitoring (default).
     • Use the resource (if published) for advanced CRUD (e.g., retrying jobs). Enable via config:

       'resources' => ['enabled' => true],
       

4. Real-Time Updates:

   • Leverage Filament’s built-in polling or integrate with Laravel Echo/Pusher for live updates (extend via Croustibat\FilamentJobsMonitor\Contracts\JobMonitor).
   • Example: Add a job:updated event listener to refresh the UI dynamically.

5. Job Metadata:

   • Customize displayed data by extending the Job model or using the job:monitoring event:

     // app/Providers/EventServiceProvider.php
     public function boot()
     {
         event(new \Croustibat\FilamentJobsMonitor\Events\JobMonitoring(
             $job,
             $payload
         ));
     }
     

Advanced Patterns

1. Custom Job Columns: Override the table columns in a Filament service provider:

   public function register()
   {
       FilamentJobsMonitor::tableColumns(function (Table $table) {
           $table->columns([
               Tables\Columns\TextColumn::make('custom_field')
                   ->label('Custom Data'),
           ]);
       });
   }
   

2. Queue Worker Monitoring:

   • Track worker processes via the Processes tab (if enabled in config).
   • Add worker metadata by extending the Worker model or using the worker:monitoring event.

3. Bulk Actions:

   • Retry/Delete jobs in bulk via Filament’s built-in actions (resource mode only).
   • Example:

     FilamentJobsMonitor::tableActions([
         Tables\Actions\Action::make('retry')
             ->action(function (Job $job) { $job->release(); }),
     ]);
     

4. API Access:

   • Expose job data via Filament’s API for third-party tools:

     Route::get('/api/jobs', [FilamentJobsMonitor::class, 'getJobs']);
     

Gotchas and Tips

Pitfalls

1. Migration Conflicts:

   • If using custom queue tables, ensure the package’s migrations don’t conflict. Run:

     php artisan vendor:publish --tag="filament-jobs-monitor-migrations" --force
     

   • For shared queue tables, disable the package’s migrations in config/filament-jobs-monitor.php:

     'migrations' => ['run' => false],
     

2. Job Data Lag:

   • Jobs processed before the plugin is installed won’t appear. Use php artisan queue:flush to reprocess old jobs (if needed).

3. Performance:

   • Large queues may slow Filament. Optimize with:
     • Pagination: Adjust per_page in config.
     • Indexing: Add DB indexes to failed_jobs and jobs tables:

       ALTER TABLE jobs ADD INDEX (queue);
       ALTER TABLE failed_jobs ADD INDEX (queue);
       

4. Driver-Specific Quirks:

   • Redis: Ensure the Redis connection is properly configured in config/queue.php.
   • Database: For high-volume queues, increase failed_jobs table size or archive old jobs:

     // config/filament-jobs-monitor.php
     'failed_jobs_ttl' => 30, // Days to retain failed jobs
     

Debugging

1. Missing Jobs:

   • Verify the queue table is being written to (check jobs table).
   • Ensure the queue:failed table exists (for failed jobs).

2. Plugin Not Showing:

   • Check Filament’s plugin registration order. The plugin must be loaded after Filament’s core.
   • Clear Filament’s cache:

     php artisan filament:cache:clear
     

3. Event Listeners:

   • If jobs aren’t appearing, manually trigger the listeners:

     // app/Providers/EventServiceProvider.php
     protected $listen = [
         'Illuminate\Queue\Events\JobProcessed' => [
             \Croustibat\FilamentJobsMonitor\Listeners\LogJob::class,
         ],
         'Illuminate\Queue\Events\JobFailed' => [
             \Croustibat\FilamentJobsMonitor\Listeners\LogFailedJob::class,
         ],
     ];
     

Extension Points

1. Custom Job Models: Extend the Job model to add fields:

   class CustomJob extends \Croustibat\FilamentJobsMonitor\Models\Job
   {
       protected $casts = [
           'custom_data' => 'array',
       ];
   }
   

   Update the config to use your model:

   'model' => \App\Models\CustomJob::class,
   

2. Hooks:

   • Job Processing: Use job:processing event to log custom data.
   • UI Customization: Override Filament’s views in resources/views/vendor/filament-jobs-monitor/.

3. Testing:

   • Mock jobs in tests:

     $job = \Croustibat\FilamentJobsMonitor\Models\Job::factory()->create([
         'queue' => 'test',
         'payload' => ['command' => 'TestJob'],
     ]);
     

4. Localization:

   • Translate strings via Filament’s localization system:

     // lang/en/filament-jobs-monitor.php
     return [
         'job' => [
             'status' => [
                 'processing' => 'In Progress',
             ],
         ],
     ];