Tasks Bundle Laravel Package

Getting Started

Minimal Steps

1. Install Dependencies Ensure RabbitMQ is running with the rabbitmq_delayed_message_exchange plugin enabled.

   sudo rabbitmq-plugins enable rabbitmq_delayed_message_exchange
   

2. Composer Installation

   composer require docplanner/tasks-bundle
   

3. Register Bundles Add to app/AppKernel.php:

   new OldSound\RabbitMqBundle\OldSoundRabbitMqBundle(),
   new DocPlanner\TasksBundle\DocPlannerTasksBundle(),
   

4. Configure RabbitMQ Connection Update config.yml with RabbitMQ credentials (see RabbitMqBundle docs).

5. Define Task Configuration Add docplanner_tasks config in config.yml:

   docplanner_tasks:
       connection_name: default
       names_prefix: app_
   

6. First Use Case: Send a Task Create a payload and task class, then dispatch:

   $payload = new MyTaskPayload();
   $this->get('docplanner_tasks.dispatcher')->dispatch(new MyTask(), $payload);
   

Implementation Patterns

Workflows

1. Task Creation

   • Extend BaseTaskPayload for payloads (serialized via serialize()).
   • Extend BaseTask for jobs, implementing:
     • supports($payload): Validate payload compatibility.
     • execute(): Task logic (return true on success, false on failure).

2. Dispatching Tasks Use the dispatcher service to enqueue tasks:

   $dispatcher = $this->get('docplanner_tasks.dispatcher');
   $dispatcher->dispatch(new MyTask(), $payload);
   

3. Consuming Tasks

   • Tasks are auto-consumed by the bundle via RabbitMQ listeners.
   • For custom consumers, tag your service with docplanner_tasks.task:

     services:
         my_custom_task:
             class: AppBundle\Task\MyCustomTask
             tags:
                 - { name: docplanner_tasks.task }
     

4. Delayed Tasks Leverage RabbitMQ’s delayed exchange (if plugin is enabled) to schedule tasks:

   $dispatcher->dispatchDelayed(new MyTask(), $payload, 3600); // Delay in seconds
   

Integration Tips

• Payload Serialization: Ensure payloads are serializable (avoid closures, resources, or non-serializable objects).
• Error Handling: Wrap execute() in try-catch to handle failures gracefully.
• Logging: Log task execution for debugging:

  $this->logger->info('Task executed', ['task' => get_class($this), 'payload' => $payload]);
  

• Testing: Mock the dispatcher service in unit tests to avoid RabbitMQ dependencies.

Gotchas and Tips

Pitfalls

1. Serialization Issues

   • Problem: Payloads with non-serializable properties (e.g., closures, database connections) will fail silently or throw errors.
   • Fix: Use serialize()/unserialize()-compatible data (e.g., arrays, simple objects, or JSON-encoded strings).

2. Delayed Message Plugin

   • Problem: Without rabbitmq_delayed_message_exchange, delayed tasks won’t work.
   • Fix: Enable the plugin and restart RabbitMQ:

     sudo rabbitmq-plugins enable rabbitmq_delayed_message_exchange
     sudo systemctl restart rabbitmq-server
     

3. Connection Failures

   • Problem: RabbitMQ downtime or misconfigurations (e.g., wrong credentials) cause tasks to silently fail.
   • Fix: Add retry logic or use OldSoundRabbitMqBundle's connection recovery features.

4. Task Tagging

   • Problem: Forgetting to tag a task service (docplanner_tasks.task) means it won’t be consumed.
   • Fix: Always tag task services in services.yml or as an annotation.

5. Return Value Misinterpretation

   • Problem: execute() returning false may not trigger retries or dead-letter queues by default.
   • Fix: Implement custom error handling or use RabbitMQ’s dead-letter exchanges.

Debugging

• Check RabbitMQ Queues: Use rabbitmqctl list_queues or the RabbitMQ Management UI to verify tasks are enqueued.
• Logs: Enable debug mode in OldSoundRabbitMqBundle:

  old_sound_rabbit_mq:
      connections:
          default:
              logger: true
  

• Payload Inspection: Log serialized payloads to ensure data integrity:

  $this->logger->debug('Serialized payload', ['data' => serialize($payload)]);
  

Extension Points

1. Custom Dispatcher Override the default dispatcher to add middleware or logging:

   $dispatcher = $this->get('docplanner_tasks.dispatcher');
   $dispatcher->addMiddleware(function ($task, $payload) {
       // Pre-dispatch logic
   });
   

2. Task Priorities Use RabbitMQ’s priority queues (if supported) by extending the bundle’s configuration:

   docplanner_tasks:
       priority_queues: true
   

3. Dead-Letter Queues Configure RabbitMQ to route failed tasks to a dead-letter queue:

   old_sound_rabbit_mq:
       consumers:
           my_consumer:
               queue_name: my_queue
               exchange_options:
                   dead_letter_exchange: dlx