Job Manager Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require bnza/job-manager
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       Bnza\JobManagerBundle\JobManagerBundle::class => ['all' => true],
   ];
   

2. Basic Configuration Define job types in config/packages/bnza_job_manager.yaml:

   bnza_job_manager:
       jobs:
           my_job:
               class: App\Job\MyJob
               command: 'app:my-job'
               description: 'Processes user data'
   

3. First Job Class Create a job class (e.g., src/Job/MyJob.php):

   namespace App\Job;
   
   use Bnza\JobManagerBundle\Job\JobInterface;
   
   class MyJob implements JobInterface {
       public function execute() {
           // Job logic here
           return true;
       }
   }
   

4. Run via CLI

   php bin/console job:run my_job
   

First Use Case

• Queue a Job: Use the job:queue command to add a job to the queue.

  php bin/console job:queue my_job --data='{"user_id": 123}'
  

• View Queue: Check pending jobs with job:list.

Implementation Patterns

Workflows

1. Job Execution Flow

   • Queue: job:queue → Stores job in DB (via JobQueue entity).
   • Run: job:run → Fetches jobs from DB, executes them sequentially, and logs results.
   • Retry: Failed jobs can be retried via job:retry <job_id>.

2. Data Handling

   • Pass data via --data CLI argument (JSON-serialized).
   • Access data in job class via JobInterface::getData():

     $userId = $this->getData()['user_id'];
     

3. Logging

   • Logs are stored in the JobLog entity (auto-created on job completion/failure).
   • View logs via job:logs or query the job_log table.

Integration Tips

• Symfony Commands Extend Bnza\JobManagerBundle\Command\JobCommand for custom job-specific commands. Example:

  namespace App\Command;
  
  use Bnza\JobManagerBundle\Command\JobCommand;
  
  class CustomJobCommand extends JobCommand {
      protected function configure() {
          $this->setName('app:custom-job');
      }
  }
  

• Event Listeners Hook into job lifecycle events (e.g., JobEvents::JOB_STARTED):

  # config/services.yaml
  services:
      App\EventListener\JobListener:
          tags:
              - { name: kernel.event_listener, event: bnza.job_manager.job.started, method: onJobStarted }
  

• Database Schema The bundle auto-creates tables (job_queue, job_log). Customize via migrations or Doctrine extensions.

Gotchas and Tips

Pitfalls

1. Job Data Serialization

   • --data must be valid JSON. Non-serializable objects (e.g., closures) will fail.
   • Fix: Use json_encode() on arrays/objects before passing via CLI.

2. Command Naming Collisions

   • Ensure command in job_manager.yaml matches your Symfony command name.
   • Fix: Verify with php bin/console list after configuration.

3. Locking Issues

   • Jobs are locked during execution (via JobQueue::lock()). Long-running jobs may timeout.
   • Fix: Use job:run --timeout=3600 to adjust the lock duration (default: 300s).

4. Logging Overwrite

   • By default, logs append to the job_log table. Custom log handlers may overwrite data.
   • Fix: Extend JobLog entity or override the JobLogger service.

Debugging

• Check Queue Status

  php bin/console job:list --all
  

  • pending: Not yet run.
  • running: Locked by another process.
  • failed: Execution threw an exception.

• Inspect Job Data Dump job data in the job class:

  var_dump($this->getData());
  

• Enable Debug Mode Set BNZA_JOB_MANAGER_DEBUG=1 in .env to log additional details.

Extension Points

1. Custom Job Storage Override the job_queue table by extending the JobQueue entity or using a custom repository.

2. Parallel Execution The bundle runs jobs sequentially. For parallelism:

   • Use Symfony Messenger or Laravel Queues alongside.
   • Example: Dispatch jobs to a queue worker after job:queue.

3. GUI Integration

   • Expose job status via a custom controller:

     use Bnza\JobManagerBundle\Entity\JobQueue;
     
     public function showJobs() {
         return $this->render('jobs/index.html.twig', [
             'jobs' => $this->getDoctrine()->getRepository(JobQueue::class)->findAll(),
         ]);
     }
     

4. Scheduled Jobs Combine with Symfony’s CronBundle or Laravel’s task scheduling:

   # config/packages/cron.yaml
   cron:
       jobs:
           daily_job:
               command: 'job:run my_job'
               schedule: '0 0 * * *'