Jobboy Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require dansan/jobboy
   

   Add the service provider to config/app.php:

   'providers' => [
       // ...
       Dansan\Jobboy\JobboyServiceProvider::class,
   ],
   

2. Publish Config:

   php artisan vendor:publish --provider="Dansan\Jobboy\JobboyServiceProvider" --tag="jobboy-config"
   

   This generates a config/jobboy.php file with default settings.

3. First Use Case: Define a job class (e.g., app/Jobs/ProcessUser.php):

   namespace App\Jobs;
   
   use Dansan\Jobboy\Job;
   
   class ProcessUser extends Job
   {
       public $userId;
   
       public function __construct($userId)
       {
           $this->userId = $userId;
       }
   
       public function handle()
       {
           // Your job logic here
           \Log::info("Processing user ID: {$this->userId}");
       }
   }
   

   Dispatch the job:

   use App\Jobs\ProcessUser;
   
   ProcessUser::dispatch(123);
   

4. Queue Configuration: Ensure your .env has a queue connection (e.g., QUEUE_CONNECTION=database or QUEUE_CONNECTION=redis).

Implementation Patterns

Core Workflows

1. Job Dispatching:

   • Use Job::dispatch() for one-off jobs.
   • Chain jobs with then() for sequential execution:

     ProcessUser::dispatch(123)
         ->then(new SendWelcomeEmail($userId));
     

   • Use batch() for parallel execution:

     JobBoy::batch([
         new ProcessUser(1),
         new ProcessUser(2),
     ])->dispatch();
     

2. Job Chaining with Dependencies:

   ProcessUser::dispatch(123)
       ->then(new NotifyAdmin($userId))
       ->after(function ($job) {
           // Post-processing logic
       });
   

3. Delayed Jobs:

   ProcessUser::dispatch(123)->delay(now()->addMinutes(10));
   

4. Job Retries: Configure retries in config/jobboy.php:

   'retries' => 3,
   'backoff' => 60, // seconds
   

Integration Tips

• Laravel Events: Trigger jobs from event listeners:

  public function handle(UserRegistered $event)
  {
      ProcessUser::dispatch($event->user->id);
  }
  

• Artisan Commands: Dispatch jobs from commands:

  public function handle()
  {
      JobBoy::batch([new ProcessUser(1), new ProcessUser(2)])->dispatch();
  }
  

• Middleware: Apply middleware to jobs (if supported by the underlying queue driver):

  ProcessUser::dispatch(123)->middleware(ThrottleJobs::class);
  

• Job Metadata: Attach metadata for tracking:

  ProcessUser::dispatch(123)->metadata(['priority' => 'high']);
  

Gotchas and Tips

Pitfalls

1. Queue Driver Compatibility:

   • JobBoy relies on Laravel's queue system. Ensure your queue driver (e.g., database, redis, beanstalkd) is properly configured.
   • Debug Tip: If jobs aren’t processing, check QUEUE_CONNECTION in .env and run php artisan queue:work.

2. Job Serialization:

   • Complex objects (e.g., Eloquent models) may not serialize correctly. Use __serialize() and __unserialize() in your job class:

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

3. Missing Config:

   • Forgetting to publish the config (php artisan vendor:publish) will use default settings, which may not align with your needs (e.g., retry logic).

4. Job Class Naming:

   • Job classes must extend Dansan\Jobboy\Job (not Laravel’s Illuminate\Bus\Queueable).

5. Batch Job Failures:

   • If a batch job fails, the entire batch stops by default. Use failJobs() to configure behavior:

     JobBoy::batch([...])->failJobs(function ($job) {
         \Log::error("Job failed: " . get_class($job));
     })->dispatch();
     

Debugging Tips

1. Log Job Execution: Add logging in handle() to trace job flow:

   public function handle()
   {
       \Log::debug("Job started for user ID: {$this->userId}");
       // ...
       \Log::debug("Job completed for user ID: {$this->userId}");
   }
   

2. Check Queue Tables: For database queue driver, inspect jobs table:

   php artisan tinker
   >>> \DB::table('jobs')->where('payload', 'like', '%"userId":123%')->get();
   

3. Test Locally: Use QUEUE_CONNECTION=sync for immediate execution during development (not for production).

Extension Points

1. Custom Job Events: Extend JobBoy’s event system by listening to job.processing, job.processed, or job.failed:

   event(new JobProcessing($job));
   

2. Job Filters: Filter jobs before dispatching (e.g., skip if user is inactive):

   if ($user->isActive()) {
       ProcessUser::dispatch($user->id);
   }
   

3. Dynamic Job Classes: Instantiate jobs dynamically (useful for plugins):

   $jobClass = \App\Jobs\ProcessUser::class;
   $job = new $jobClass(123);
   dispatch($job);
   

4. Job Priority: Implement priority queues by extending the queue driver or using metadata:

   ProcessUser::dispatch(123)->metadata(['priority' => 'high']);
   

Config Quirks

• Retry Logic: The backoff setting in config/jobboy.php uses seconds, not minutes. Adjust accordingly:

  'retries' => 3,
  'backoff' => 60, // 1 minute delay between retries
  

• Timeouts: Job timeouts are controlled by the queue driver (e.g., QUEUE_TIMEOUT in .env). JobBoy does not override this.

• Unique Jobs: To prevent duplicate jobs, use Laravel’s unique() method (if supported by your queue driver):

  ProcessUser::dispatch(123)->unique('user-id-123');