Enqueue Laravel Package

Getting Started

Minimal Steps

1. Installation:

   • Typically pulled in via transport packages (e.g., ecotone/amqp-transport, ecotone/redis-transport). For direct use (custom transports):

     composer require ecotone/enqueue
     

   • Requires php-enqueue/enqueue (≥2.0) and a supported broker extension (e.g., ext-amqp, ext-redis).

2. First Use Case:

   • Replace a Laravel queue job with an Ecotone command. Example:

     use Ecotone\Attribute\CommandHandler;
     use Ecotone\Command\CommandHandlerInterface;
     
     #[CommandHandler]
     class ProcessOrderCommandHandler implements CommandHandlerInterface
     {
         public function __invoke(ProcessOrderCommand $command): void
         {
             // Business logic (e.g., update inventory, send email)
         }
     }
     

   • Dispatch the command via Ecotone’s Bus (integrated with Laravel’s service container):

     use Ecotone\Bus\CommandBus;
     
     $bus = app(CommandBus::class);
     $bus->dispatch(new ProcessOrderCommand($orderId));
     

3. Configure a Transport:

   • Example for Redis:

     use Ecotone\Transport\Redis\RedisTransport;
     use Enqueue\Redis\RedisConnectionFactory;
     
     $connectionFactory = new RedisConnectionFactory('redis://localhost');
     $transport = new RedisTransport($connectionFactory);
     

   • Register the transport with Ecotone’s Bus in Laravel’s AppServiceProvider:

     public function register(): void
     {
         $this->app->bind(RedisTransport::class, fn() => new RedisTransport(
             new RedisConnectionFactory(config('queue.redis.connection'))
         ));
     }
     

4. Run Consumers:

   • Use Ecotone’s CLI tool (included with ecotone/ecotone) or integrate with Laravel’s task scheduler:

     ecotone:consume --transport=redis
     

   • For Laravel, create a console command to run consumers:

     use Symfony\Component\Console\Command\Command;
     use Symfony\Component\Console\Input\InputInterface;
     use Symfony\Component\Console\Output\OutputInterface;
     use Ecotone\Bus\QueryBus;
     
     class RunEcotoneConsumers extends Command
     {
         protected function execute(InputInterface $input, OutputInterface $output): int
         {
             $bus = app(QueryBus::class);
             $bus->consume(); // Starts consuming messages
             return 0;
         }
     }
     

5. Verify:

   • Check logs for consumed messages or use broker tools (e.g., redis-cli for Redis queues).

Where to Look First:

• Ecotone Quickstart Guide (Laravel-specific examples).
• Enqueue Documentation (broker-specific configs).
• tests/ in the ecotone-dev repo for integration patterns.

Implementation Patterns

Core Workflows

1. Command/Query Handling

• Pattern: Replace Laravel’s Job classes with Ecotone’s #[CommandHandler] or #[QueryHandler].

  #[CommandHandler]
  class SendWelcomeEmailCommandHandler
  {
      public function __invoke(SendWelcomeEmailCommand $command): void
      {
          Mail::to($command->email)->send(new WelcomeEmail($command->user));
      }
  }
  

• Integration:
  • Dispatch commands via Laravel’s service container:

    $bus = app(CommandBus::class);
    $bus->dispatch(new SendWelcomeEmailCommand($user->email));
    

  • Use Laravel’s events to trigger commands:

    use Illuminate\Support\Facades\Event;
    
    Event::listen(UserRegistered::class, function ($event) {
        $bus->dispatch(new SendWelcomeEmailCommand($event->user->email));
    });
    

2. Event-Driven Architecture

• Pattern: Use Ecotone’s #[EventHandler] for CQRS or event sourcing.

  #[EventHandler]
  class HandleOrderPlacedEvent
  {
      public function __invoke(OrderPlacedEvent $event): void
      {
          // Update inventory, send notifications, etc.
      }
  }
  

• Integration:
  • Publish events from Laravel’s Event system:

    Event::dispatch(new OrderPlacedEvent($orderId));
    

  • Or use Ecotone’s EventBus directly:

    $eventBus = app(EventBus::class);
    $eventBus->publish(new OrderPlacedEvent($orderId));
    

3. Sagas for Long-Running Workflows

• Pattern: Orchestrate multi-step processes (e.g., order fulfillment).

  use Ecotone\Saga\Saga;
  
  #[Saga]
  class OrderFulfillmentSaga
  {
      public function __invoke(OrderPlacedEvent $event): void
      {
          $this->bus->dispatch(new ReserveInventoryCommand($event->orderId));
          $this->bus->dispatch(new ShipOrderCommand($event->orderId));
      }
  }
  

• Integration:
  • Register sagas with Ecotone’s SagaBus:

    $sagaBus = app(SagaBus::class);
    $sagaBus->start(new OrderFulfillmentSaga(), $event);
    

4. Outbox for Reliable Publishing

• Pattern: Decouple event publishing from transaction commits.

  use Ecotone\Outbox\Outbox;
  
  class OrderService
  {
      public function placeOrder(OrderData $data)
      {
          DB::transaction(function () use ($data) {
              $order = Order::create($data);
              app(Outbox::class)->publish(new OrderPlacedEvent($order->id));
          });
      }
  }
  

• Integration:
  • Configure the outbox with a transport (e.g., Redis):

    $outbox = new Outbox(new RedisTransport($connectionFactory));
    $this->app->singleton(Outbox::class, fn() => $outbox);
    

5. Custom Transport Integration

• Pattern: Extend for unsupported brokers (e.g., Stomp).

  use Ecotone\Transport\Transport;
  use Enqueue\Client\Producer;
  use Enqueue\Client\Consumer;
  
  class StompTransport implements Transport
  {
      public function __construct(private Producer $producer, private Consumer $consumer) {}
  
      public function produce($message): void
      {
          $this->producer->send($message);
      }
  
      public function consume(callable $callback): void
      {
          $this->consumer->consume($callback);
      }
  }
  

• Integration:
  • Bind the transport to Ecotone’s Bus:

    $this->app->bind(StompTransport::class, fn() => new StompTransport(
        new Producer(new StompConnection('stomp://localhost')),
        new Consumer(new StompConnection('stomp://localhost'))
    ));
    

Laravel-Specific Tips

1. Service Provider Setup

• Register Ecotone’s Bus and transports in AppServiceProvider:

  use Ecotone\Bus\CommandBus;
  use Ecotone\Transport\Redis\RedisTransport;
  
  public function register(): void
  {
      $this->app->singleton(CommandBus::class, fn() => new CommandBus(
          new RedisTransport(new RedisConnectionFactory(config('queue.redis.connection')))
      ));
  }
  

2. Queue Worker Integration

• Create a Laravel command to run Ecotone consumers:

  use Illuminate\Console\Command;
  use Ecotone\Bus\QueryBus;
  
  class EcotoneWorker extends Command
  {
      protected $signature = 'ecotone:work';
      protected $description = 'Run Ecotone message consumers';
  
      public function handle(): void
      {
          $bus = app(QueryBus::class);
          $bus->consume();
      }
  }
  

• Schedule it in app/Console/Kernel.php:

  protected function schedule(Schedule $schedule): void
  {
      $schedule->command('ecotone:work')->everyMinute();
  }
  

3. Job Serialization

• Convert Laravel jobs to Ecotone messages:

  use Illuminate\Contracts\Queue\Job as LaravelJob;
  use Ecotone\Message\Message;
  
  class LaravelJobToMessageConverter
  {
      public function convert(LaravelJob $job): Message
      {
          return new Message(
              $job->payload(),
              $job->getJobId()
          );
      }
  }
  

4.