Async Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require aligent/async-bundle
   

   Ensure it’s enabled in config/bundles.php:

   Aligent\AsyncBundle\AligentAsyncBundle::class => ['all' => true],
   

2. First Use Case: Dispatching an Async Job Extend Oro’s async processing for custom logic (e.g., webhooks, delayed tasks):

   use Aligent\AsyncBundle\Job\AsyncJob;
   use Oro\AsyncBundle\Entity\Job;
   
   // Dispatch a job via Oro's async system
   $job = new AsyncJob('my_custom_job', ['param' => 'value']);
   $job->setEntityClass(Job::class);
   $job->setEntityData(['status' => 'pending']);
   $this->get('oro_async.job_executor')->execute($job);
   

3. Key Classes to Explore

   • AsyncJob: Base class for custom async jobs.
   • JobExecutor: Service for executing jobs.
   • WebhookEvent: For custom Oro webhook events (v5.0+).
   • ChannelManager: For managing async channels (e.g., queues).

Implementation Patterns

1. Custom Async Jobs

Extend AsyncJob to create reusable async tasks:

namespace App\Async;

use Aligent\AsyncBundle\Job\AsyncJob;

class ProcessOrderJob extends AsyncJob
{
    protected $orderId;

    public function __construct($orderId)
    {
        $this->orderId = $orderId;
        parent::__construct('app.process_order', ['order_id' => $orderId]);
    }

    public function run()
    {
        // Custom logic here
        $order = $this->entityManager->find(Order::class, $this->orderId);
        // ...
    }
}

Dispatch via:

$job = new ProcessOrderJob(123);
$this->get('oro_async.job_executor')->execute($job);

2. Webhook Integration (Oro 5.0+)

Create custom webhook events:

use Aligent\AsyncBundle\Event\WebhookEvent;

class CustomWebhookEvent extends WebhookEvent
{
    protected $eventName = 'custom.webhook';

    public function __construct($payload)
    {
        parent::__construct($payload, 'custom_webhook_channel');
    }
}

Trigger via:

$event = new CustomWebhookEvent(['data' => 'payload']);
$this->get('oro_async.webhook.dispatcher')->dispatch($event);

3. Channel Management

Dynamically manage async channels (queues):

// Create a channel
$channel = $this->get('oro_async.channel_manager')->createChannel('custom_channel');

// Delete a channel (fixes cache issue from v5.0.3)
$this->get('oro_async.channel_manager')->deleteChannel('custom_channel');

4. Job Monitoring

Query failed jobs (note: uses TEXT field for exceptions since v4.1.1):

$failedJobs = $this->get('oro_async.job_repository')->findBy(['status' => 'failed']);
foreach ($failedJobs as $job) {
    $exception = $job->getException(); // TEXT field, may need JSON decode
}

5. Event Listeners

Hook into Oro’s async lifecycle:

// config/services.yaml
services:
    App\Async\Listener\JobListener:
        tags:
            - { name: kernel.event_listener, event: oro_async.job.execute, method: onJobExecute }

class JobListener
{
    public function onJobExecute(JobExecuteEvent $event)
    {
        $job = $event->getJob();
        // Pre/post-processing logic
    }
}

Gotchas and Tips

1. Cache Pitfalls (v5.0.3 Fix)

• Issue: Deleted channels weren’t removed from cache until updated.
• Workaround: Explicitly call deleteChannel() after removal:

  $this->get('oro_async.channel_manager')->deleteChannel('old_channel');
  

• Debug: Check oro_async_channel table for orphaned entries.

2. Exception Handling (v4.1.1 Change)

• Change: Failed job exceptions now use a TEXT field (not LONGTEXT).
• Tip: Decode JSON manually if storing complex exceptions:

  $exceptionData = json_decode($job->getException(), true);
  

3. Oro 5.0 Compatibility

• Breaking Changes: Ensure your code uses Oro 5.0’s async API (e.g., oro_async.webhook.dispatcher).
• Migration: Update Job entity references to match Oro 5.0’s schema.

4. Custom Webhook Events (v5.0.2)

• Tip: Extend WebhookEvent for reusable payloads:

  class OrderWebhookEvent extends WebhookEvent
  {
      public function getOrderId(): int
      {
          return $this->getPayload()['order_id'];
      }
  }
  

• Debug: Verify channel routing in config/packages/oro_async.yaml.

5. Performance Tips

• Batch Jobs: Use Oro’s JobExecutor with bulk flags:

  $this->get('oro_async.job_executor')->execute($job, ['batch_size' => 50]);
  

• Avoid Blocking: Offload heavy tasks to async jobs to prevent timeouts.

6. Debugging

• Logs: Enable Oro’s async logs in config/packages/monolog.yaml:

  handlers:
      async:
          type: stream
          path: "%kernel.logs_dir%/async.log"
          level: debug
  

• Job Status: Query oro_async_job table directly for stuck jobs:

  SELECT * FROM oro_async_job WHERE status = 'pending' AND created_at < NOW() - INTERVAL '1 hour';
  

7. Extension Points

• Custom Job Handlers: Implement JobHandlerInterface for unique logic:

  class CustomHandler implements JobHandlerInterface
  {
      public function handle(Job $job)
      {
          // Custom processing
      }
  }
  

• Register Handler:

  # config/services.yaml
  services:
      App\Async\Handler\CustomHandler:
          tags:
              - { name: oro_async.job_handler, jobName: 'custom_job' }