Backgroundbundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require masando/edemy-backgroundbundle
   

   Ensure eDemyFramework is installed and properly configured in your project.

2. Bundle Registration Add to config/bundles.php:

   Masando\eDemyBackgroundBundle\eDemyBackgroundBundle::class => ['all' => true],
   

3. First Use Case: Enqueue a Background Job

   use Masando\eDemyBackgroundBundle\Background\BackgroundJob;
   
   // In a controller or service
   $job = new BackgroundJob('App\Jobs\ProcessUserData', ['userId' => 123]);
   $this->get('edemy_background.job_dispatcher')->dispatch($job);
   

4. Check Configuration Verify config/edemy_background.php exists (auto-generated) and adjust queue settings (e.g., default_queue, connection).

Implementation Patterns

Core Workflows

1. Job Dispatching

   • Synchronous Proxy: Dispatch jobs from controllers/services without blocking the request.

     $dispatcher = $this->get('edemy_background.job_dispatcher');
     $dispatcher->dispatch(new BackgroundJob('App\Jobs\SendEmail', ['email' => 'user@example.com']));
     

   • Bulk Dispatching:

     $dispatcher->dispatchMultiple([
         new BackgroundJob('App\Jobs\GenerateReport', ['id' => 1]),
         new BackgroundJob('App\Jobs\CleanupCache'),
     ]);
     

2. Job Definition Extend Masando\eDemyBackgroundBundle\Background\AbstractJob for custom jobs:

   namespace App\Jobs;
   
   use Masando\eDemyBackgroundBundle\Background\AbstractJob;
   
   class ProcessUserData extends AbstractJob {
       public function handle() {
           // Business logic here
       }
   }
   

3. Queue Integration

   • Supports Symfony Messenger + Doctrine Messenger or native Laravel queues.
   • Configure edemy_background.php:

     'connection' => 'doctrine', // or 'messenger', 'sync'
     'queue_name' => 'edemy_background',
     

4. Job Monitoring

   • Use the BackgroundJobRepository to track jobs:

     $jobs = $this->get('edemy_background.job_repository')->findBy(['status' => 'pending']);
     

Integration Tips

• Event-Driven Workflows: Trigger background jobs from Symfony events (e.g., kernel.request).

  $eventDispatcher->addListener('kernel.request', function () use ($dispatcher) {
      $dispatcher->dispatch(new BackgroundJob('App\Jobs\LogRequest'));
  });
  

• Dependency Injection: Inject JobDispatcherInterface into services for reusable job handling.
• Testing: Mock the dispatcher in PHPUnit:

  $this->mock('edemy_background.job_dispatcher')->shouldReceive('dispatch')->once();
  

Gotchas and Tips

Pitfalls

1. Queue Connection Mismatch

   • If jobs don’t appear in the queue, verify edemy_background.php matches your actual queue setup (e.g., Doctrine Messenger requires MESSENGER_TRANSPORT_DSN in .env).
   • Fix: Check php bin/console messenger:consume logs for connection errors.

2. Job Serialization Issues

   • Complex objects (e.g., Eloquent models) must implement Serializable or use __serialize()/__unserialize().
   • Tip: Use DTOs or arrays for job payloads to avoid serialization headaches.

3. Missing Job Classes

   • If the job class isn’t found, ensure:
     • The namespace is correct in BackgroundJob.
     • The class is autoloaded (composer dump-autoload).

4. Race Conditions

   • Jobs may overlap if not idempotent. Use unique job IDs or database locks:

     $job = new BackgroundJob('App\Jobs\ProcessOrder', ['orderId' => 123], 'unique_job_123');
     

Debugging

• Enable Logging Add to config/edemy_background.php:

  'debug' => true,
  

  Logs appear in var/log/dev.log.

• Job Retries Configure retry logic in AbstractJob:

  protected $maxRetries = 3;
  protected $delay = 60; // seconds
  

• Queue Stuck? Clear pending jobs via:

  php bin/console edemy_background:clear-queue
  

Extension Points

1. Custom Job Statuses Extend the status field in the background_job table or override the JobRepository:

   namespace App\Repository;
   use Masando\eDemyBackgroundBundle\Repository\BackgroundJobRepository;
   
   class CustomJobRepository extends BackgroundJobRepository {
       // Add custom queries (e.g., 'failed_after_retries')
   }
   

2. Middleware for Jobs Add middleware to config/edemy_background.php:

   'middleware' => [
       App\Middleware\LogJobExecution::class,
   ],
   

3. Alternative Queue Drivers Override the QueueFactory service to support custom drivers (e.g., Redis):

   # config/services.yaml
   Masando\eDemyBackgroundBundle\Queue\QueueFactory: ~
   

4. Webhooks for Job Events Listen for job lifecycle events (e.g., job.started, job.failed) via Symfony’s event system:

   $eventDispatcher->addListener(
       'edemy_background.job.started',
       [YourListener::class, 'onJobStarted']
   );