Job Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require aboutcoders/job-bundle
   

   Add to AppKernel.php (Symfony 2.x) or config/bundles.php (Symfony 3/4):

   new Aboutcoders\JobBundle\AbcJobBundle(),
   

2. Configure Queue Driver Edit app/config/config.yml (or config/packages/aboutcoders_job.yaml in Symfony 4+):

   aboutcoders_job:
       queue_driver: doctrine_dbal  # or rabbitmq, redis, etc.
   

3. Annotate a Job Method

   use Aboutcoders\JobBundle\Annotation\Job;
   
   class MyJobService
   {
       /**
        * @Job()
        */
       public function processData($data)
       {
           // Your async logic here
       }
   }
   

4. Register the Service Tag the service in services.yml:

   services:
       my_job_service:
           class: AppBundle\Service\MyJobService
           tags:
               - { name: aboutcoders_job.job }
   

5. Trigger a Job

   $this->get('aboutcoders_job.job_dispatcher')->dispatch(
       'my_job_service',
       'processData',
       ['data' => 'example']
   );
   

First Use Case: Background Processing

Replace a slow API endpoint with an async job:

/**
 * @Job()
 */
public function generateReport($userId)
{
    $report = $this->reportService->generate($userId);
    $this->emailService->send($report);
}

Call from controller:

$dispatcher = $this->get('aboutcoders_job.job_dispatcher');
$dispatcher->dispatch('report_service', 'generateReport', ['userId' => 123]);

Implementation Patterns

Core Workflows

1. Job Dispatching

• Basic Dispatch:

  $dispatcher->dispatch('service_name', 'method_name', $params);
  

• With Priority:

  $dispatcher->dispatch('service_name', 'method_name', $params, 10); // Higher = sooner
  

• Delayed Execution:

  $dispatcher->dispatch('service_name', 'method_name', $params, null, 3600); // Delay in seconds
  

2. Job Management

• Check Status:

  $status = $this->get('aboutcoders_job.job_manager')->getJobStatus($jobId);
  

• Cancel Job:

  $this->get('aboutcoders_job.job_manager')->cancelJob($jobId);
  

• Retry Failed Job:

  $this->get('aboutcoders_job.job_manager')->retryJob($jobId);
  

3. Scheduled Jobs

Configure in config.yml:

aboutcoders_job:
    scheduled_jobs:
        'report_service.generateMonthlyReport':
            cron: '0 0 1 * *'  # Run at 00:00 on the 1st day of every month
            parameters: ['all']

4. REST API Integration

Expose job endpoints in routing.yml:

aboutcoders_job_rest:
    resource: "@AbcJobBundle/Resources/config/routing.yml"
    prefix: /api/jobs

Access endpoints like:

• GET /api/jobs/{id} → Job status
• POST /api/jobs/{id}/cancel → Cancel job

Integration Tips

With Doctrine Entities

Annotate entity methods:

use Aboutcoders\JobBundle\Annotation\Job;

class UserService
{
    /**
     * @Job()
     */
    public function notifyUser(User $user, $message)
    {
        $user->addNotification($message);
        $this->entityManager->flush();
    }
}

With Symfony Forms

Trigger jobs after form submission:

public function submitAction(Request $request)
{
    $form = $this->createForm(UserType::class);
    $form->handleRequest($request);

    if ($form->isSubmitted() && $form->isValid()) {
        $user = $form->getData();
        $this->get('aboutcoders_job.job_dispatcher')->dispatch(
            'user_service',
            'notifyUser',
            [$user, 'Your data was saved!']
        );
        $this->addFlash('success', 'Processing in background!');
    }
}

With Symfony Events

Listen for job lifecycle events:

services:
    app.job_listener:
        class: AppBundle\EventListener\JobListener
        tags:
            - { name: kernel.event_listener, event: aboutcoders.job.created, method: onJobCreated }

Custom Queue Drivers

Extend Aboutcoders\JobBundle\Queue\QueueInterface for new drivers:

class CustomQueueDriver implements QueueInterface
{
    public function push($jobId, $data, $priority = null, $delay = null)
    {
        // Custom logic (e.g., HTTP API call)
    }

    public function pop()
    {
        // Custom logic
    }
}

Register in config:

aboutcoders_job:
    queue_driver: custom
    queue_driver_options:
        class: AppBundle\Queue\CustomQueueDriver

Gotchas and Tips

Pitfalls

1. Serialization Issues

   • Problem: Complex objects (e.g., Doctrine entities, closures) may not serialize.
   • Fix: Use @Job(serializer="json") or implement JsonSerializable:

     /**
      * @Job(serializer="json")
      */
     public function processEntity(Entity $entity)
     {
         // ...
     }
     

2. Queue Driver Mismatches

   • Problem: Using doctrine_dbal without DBAL installed or misconfigured.
   • Fix: Ensure dependencies are installed and queue_driver_options are correct:

     aboutcoders_job:
         queue_driver: doctrine_dbal
         queue_driver_options:
             db_driver: pdo_mysql
             db_host: localhost
             db_name: your_db
     

3. Circular Dependencies

   • Problem: Jobs that dispatch other jobs may cause deadlocks.
   • Fix: Use @Job(allow_recursion=true) or refactor to avoid circular calls.

4. Stale Job Status

   • Problem: Job status not updating due to worker crashes.
   • Fix: Implement a heartbeat system or use aboutcoders_job.job_manager->updateJobStatus().

5. Memory Leaks

   • Problem: Long-running jobs consuming excessive memory.
   • Fix: Use @Job(timeout=30) to set max execution time (in seconds).

Debugging Tips

1. Enable Logging Configure in config.yml:

   aboutcoders_job:
       logging:
           enabled: true
           level: debug
           handlers:
               - { type: stream, path: "%kernel.logs_dir%/jobs.log" }
   

2. Check Queue Backlog For doctrine_dbal:

   SELECT * FROM aboutcoders_job_queue;
   

   For RabbitMQ:

   rabbitmqctl list_queues name messages
   

3. Worker Debugging Run worker with verbose output:

   php app/console aboutcoders:job:consume --verbose
   

4. Job Retry Logic Configure retry policy in config.yml:

   aboutcoders_job:
       retry_policy:
           max_attempts: 3
           delay: 1000  # ms between retries
   

Extension Points

1. Custom Job Statuses Extend Aboutcoders\JobBundle\Model\JobStatus:

   class CustomJobStatus extends JobStatus
   {
       const STATUS_PROCESSING = 'processing_custom';
   }
   

   Update JobManager to handle new statuses.

2. Pre/Post Job Hooks Implement Aboutcoders\JobBundle\Event\JobEventSubscriber:

   class MyJobSubscriber implements JobEventSubscriber
   {
       public function onJobCreated(JobEvent $event)
       {
           // Pre-job logic
       }
   
       public function onJobFinished(JobEvent $event)
       {
           // Post-job logic
       }
   }
   

   Register in services.yml:

   services:
       app.job_subscriber:
           class: AppBundle\EventListener\MyJobSubscriber
           tags:
               - { name: aboutcoders_job.event_subscriber }
   

3. Dynamic Job Parameters Use runtime parameters with @Job:

   /**
    * @Job(runtime_parameters={"userId": "@user_id"})
    */
   public function sendWelcomeEmail($userId)
   {
       // ...
   }
   

   Dispatch with:

   $dispatch