Job Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require abc/job
   

   Ensure php-enqueue (dependency) is also installed and configured for your transport (e.g., Redis, RabbitMQ).

2. Basic Job Definition Create a job class implementing JobInterface:

   use Abc\Job\JobInterface;
   
   class SendEmailJob implements JobInterface
   {
       public function run(): void
       {
           // Your logic here
       }
   }
   

3. Dispatching a Job Use the JobDispatcher to enqueue a job:

   $dispatcher = new JobDispatcher();
   $job = new SendEmailJob();
   $dispatcher->dispatch($job);
   

4. First Use Case Trigger a job asynchronously in a Laravel controller:

   use Abc\Job\JobDispatcher;
   
   public function sendWelcomeEmail()
   {
       $dispatcher = app(JobDispatcher::class);
       $dispatcher->dispatch(new SendEmailJob());
       return response()->json(['status' => 'Job dispatched']);
   }
   

Implementation Patterns

Core Workflows

1. Job Dispatching

   • Use JobDispatcher for one-off jobs.
   • For batches/sequences, wrap jobs in BatchJob or SequenceJob:

     $batch = new BatchJob([new Job1(), new Job2()]);
     $dispatcher->dispatch($batch);
     

2. Laravel Integration

   • Bind the dispatcher in AppServiceProvider:

     $this->app->singleton(JobDispatcher::class, function ($app) {
         return new JobDispatcher(new EnqueueConnection());
     });
     

   • Use dependency injection in controllers/services.

3. Status Tracking

   • Retrieve job status via JobRepository:

     $repository = new JobRepository();
     $status = $repository->getStatus($jobId);
     

4. Cancellation/Restart

   • Cancel a job:

     $repository->cancel($jobId);
     

   • Restart a failed job:

     $repository->restart($jobId);
     

Advanced Patterns

1. Scheduled Jobs Requires AbcSchedulerBundle (2.x). Configure in config/packages/abc_scheduler.yaml:

   abc_scheduler:
       jobs:
           send_weekly_report: '@App\Jobs\ReportJob'
           schedule: '0 0 * * 1' # Every Monday at midnight
   

2. Custom Transports Configure php-enqueue in .env (e.g., Redis):

   ENQUEUE_DSN=redis://localhost
   

3. Job Composition Combine jobs dynamically:

   $sequence = new SequenceJob([
       new Job1(),
       new BatchJob([new Job2(), new Job3()]),
       new Job4()
   ]);
   

4. REST API Expose job status via API (uses built-in JSON REST layer):

   Route::get('/jobs/{id}', [JobController::class, 'getStatus']);
   

Gotchas and Tips

Pitfalls

1. Transport Configuration

   • Ensure php-enqueue is properly set up (e.g., Redis/RabbitMQ server running).
   • Debug connection issues with:

     php artisan enqueue:listeners
     

2. Job Serialization

   • Jobs must be serializable. Avoid closures or non-serializable dependencies.
   • Use __serialize()/__unserialize() if needed:

     public function __serialize(): array
     {
         return ['data' => $this->data];
     }
     

3. Experimental Status

   • API may change. Test thoroughly in staging.
   • Check GitHub issues for known bugs.

4. Laravel Queue Conflicts

   • Avoid mixing abc/job with Laravel’s native queues unless using php-enqueue as the transport.

Debugging Tips

1. Job Logs Enable debug mode in config/enqueue.php:

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

2. Monitoring Use php-enqueue tools to inspect queues:

   php artisan enqueue:consume --queue=default --limit=10
   

3. Status Polling Jobs may take time to appear in the repository. Add retries:

   while (!$repository->getStatus($jobId)->isComplete()) {
       sleep(1);
   }
   

Extension Points

1. Custom Job Handlers Extend JobHandler to add pre/post-processing:

   class CustomJobHandler extends JobHandler
   {
       protected function beforeRun(JobInterface $job): void
       {
           // Logic before job runs
       }
   }
   

2. Transport-Specific Logic Override EnqueueConnection for custom transports:

   class CustomConnection extends EnqueueConnection
   {
       protected function createContext(): Context
       {
           return new CustomContext();
       }
   }
   

3. API Extensions Extend the REST layer by overriding JobController or adding routes.

4. Event Listeners Listen for job events (e.g., JobStarted, JobFailed) via EventDispatcher:

   $dispatcher->addListener(JobStarted::class, function ($event) {
       Log::info('Job started', ['id' => $event->getJob()->getId()]);
   });