Jobs Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require moox/jobs
   php artisan mooxjobs:install
   

   • Publishes config, migrations, and registers Filament plugins.
   • For Moox app users: php artisan moox:install handles everything.

2. First Use Case:

   • Access the Jobs Dashboard via Filament (/admin/jobs).
   • View queued jobs, failed jobs, and batches in a unified UI.
   • Example: Monitor a SendEmailJob batch for a marketing campaign.

3. Key Files to Review:

   • config/mooxjobs.php: Adjust queue connection, batch settings, or failed job retention.
   • database/migrations/: Verify table structures for jobs, failed_jobs, and job_batches.

Implementation Patterns

Core Workflows

1. Job Monitoring:

   • Use the Jobs Table to filter by job class, queue, or batch.
   • Example: Track ProcessInvoiceJob failures with:

     // In a Filament policy or query scope
     public function scopeFailed($query) {
         return $query->where('job', 'App\Jobs\ProcessInvoiceJob');
     }
     

2. Batch Management:

   • Create batches programmatically:

     use Moox\Jobs\Facades\Jobs;
     
     $batch = Jobs::batch([
         new SendEmailJob($user),
         new LogActivityJob($user),
     ])->name('user-onboarding')->dispatch();
     

   • View batch progress in Filament’s Batches tab.

3. Failed Job Retries:

   • Retry failed jobs via the UI or programmatically:

     $failedJob = FailedJob::find($id);
     $failedJob->retry();
     

4. Integration with Filament:

   • Extend the dashboard with custom widgets:

     use Moox\Jobs\Filament\Widgets\JobsOverview;
     
     Filament::registerWidget(JobsOverview::class);
     

Advanced Patterns

• Custom Job Columns: Override default columns in a service provider:

  public function boot() {
      Filament::serving(function () {
          Filament::registerTableColumn(
              'custom_column',
              fn ($record) => $record->payload['custom_data']
          );
      });
  }
  

• Queue Listeners: Hook into job events (e.g., JobProcessed) for analytics:

  use Moox\Jobs\Events\JobProcessed;
  
  event(new JobProcessed($job));
  

• API Access: Expose job data via Filament’s API:

  Route::get('/api/jobs', function () {
      return Jobs::table()->get();
  });
  

Gotchas and Tips

Pitfalls

1. Redis Limitations:

   • Moox Jobs does not support Redis queues natively (unlike Horizon).
   • Workaround: Use the database driver or sync Redis jobs to the database via a listener.

2. Failed Job Retention:

   • Default retention is 14 days (configurable in mooxjobs.php).
   • Overlong retention may bloat your failed_jobs table.

3. Batch Naming Collisions:

   • Batches with identical names (e.g., user-onboarding) will overwrite each other.
   • Use UUIDs or timestamps for uniqueness:

     $batch->name('user-onboarding-' . now()->timestamp);
     

4. Payload Size:

   • Large job payloads (e.g., serialized models) may exceed database limits.
   • Tip: Store payloads in a separate table or use shouldQueue() with delay().

Debugging Tips

• Log Job Events: Enable logging in mooxjobs.php:

  'log_events' => true,
  

  Check storage/logs/laravel.log for job lifecycle events.

• Query Performance: Add indexes to failed_jobs for large queues:

  Schema::table('failed_jobs', function (Blueprint $table) {
      $table->index('job');
      $table->index('batch_id');
  });
  

• Filament Caching: Clear Filament’s cache after config changes:

  php artisan filament:cache-clear
  

Extension Points

1. Custom Job Actions: Add buttons to the job table via a Filament plugin:

   use Moox\Jobs\Filament\Resources\JobResource;
   
   JobResource::registerAction(
       Action::make('customAction')
           ->action(function (Job $job) { /* ... */ })
   );
   

2. Override Views: Publish and modify Filament views:

   php artisan vendor:publish --tag=mooxjobs-views
   

   Edit resources/views/vendor/moox/jobs/....

3. Queue Worker Integration: Sync external queues (e.g., SQS) to Moox Jobs via a custom worker:

   use Moox\Jobs\Facades\Jobs;
   
   $worker = new ExternalQueueWorker();
   $worker->process(function ($job) {
       Jobs::table()->create([...]);
   });