Asynchronous Bundle Laravel Package

Getting Started

Minimal Steps for Laravel Integration

1. Install the Bundle:

   composer require simple-bus/asynchronous-bundle
   

   Note: Since this is a Symfony bundle, Laravel integration requires a custom service provider or Symfony bridge (e.g., symfony/flex).

2. Create a Laravel Service Provider: Register the bundle in config/app.php:

   'providers' => [
       // ...
       SimpleBusLaravelServiceProvider::class,
   ],
   

   Define the provider (app/Providers/SimpleBusLaravelServiceProvider.php):

   use SimpleBus\AsynchronousBundle\SimpleBusAsynchronousBundle;
   use Symfony\Component\HttpKernel\Kernel;
   
   class SimpleBusLaravelServiceProvider extends ServiceProvider
   {
       public function register()
       {
           $this->app->register(new SimpleBusAsynchronousBundle(), [
               'kernel' => $this->app->make(Kernel::class),
           ]);
       }
   }
   

3. Configure the Message Store: Edit config/packages/simple_bus_asynchronous.yaml (create if missing):

   simple_bus_asynchronous:
       message_store: 'doctrine://default' # or 'symfony://cache.app'
   

   Laravel Note: Use doctrine if using Eloquent, or symfony://cache.app for file-based storage.

4. Define Your First Message: Create a message class (e.g., app/Messages/ProcessOrder.php):

   namespace App\Messages;
   
   class ProcessOrder
   {
       public function __construct(public string $orderId) {}
   }
   

5. Create a Handler: Implement a handler (e.g., app/Handlers/ProcessOrderHandler.php):

   namespace App\Handlers;
   
   use App\Messages\ProcessOrder;
   use SimpleBus\Message\Handler\MessageHandlerInterface;
   
   class ProcessOrderHandler implements MessageHandlerInterface
   {
       public function handle(ProcessOrder $message)
       {
           // Business logic (e.g., dispatch a Laravel job)
           ProcessOrderJob::dispatch($message->orderId);
       }
   }
   

6. Register the Handler: In SimpleBusLaravelServiceProvider.php:

   public function boot()
   {
       $this->app->bind(\SimpleBus\Message\Handler\MessageHandlerInterface::class, function ($app) {
           return new \App\Handlers\ProcessOrderHandler();
       });
   }
   

7. Dispatch a Message:

   use App\Messages\ProcessOrder;
   use SimpleBus\Message\Bus\MessageBusInterface;
   
   class OrderController extends Controller
   {
       public function __construct(private MessageBusInterface $bus) {}
   
       public function store()
       {
           $this->bus->dispatch(new ProcessOrder('order-123'));
           return response()->json(['status' => 'processing']);
       }
   }
   

8. Run the Queue Worker:

   php artisan queue:work
   

   Note: SimpleBus messages are not natively processed by Laravel’s queue system. You’ll need a custom queue listener (see Implementation Patterns).

First Use Case: Async Email Notifications

1. Create a message:

   namespace App\Messages;
   class SendEmailNotification { public function __construct(public string $userId, public string $template) {} }
   

2. Create a handler:

   namespace App\Handlers;
   use App\Messages\SendEmailNotification;
   use Illuminate\Support\Facades\Mail;
   
   class SendEmailNotificationHandler implements MessageHandlerInterface
   {
       public function handle(SendEmailNotification $message)
       {
           Mail::to($message->userId)->send(new EmailTemplate($message->template));
       }
   }
   

3. Dispatch in a controller:

   $this->bus->dispatch(new SendEmailNotification($user->id, 'welcome'));
   

Implementation Patterns

Core Workflows

1. Message-Driven Workflows

• Pattern: Use messages to decouple components (e.g., controllers, services).
• Example:

  // Controller dispatches a message; handler processes it asynchronously.
  $this->bus->dispatch(new UpdateUserProfile($userId, $data));
  

• Laravel Integration: Handlers can dispatch Laravel jobs for further async processing:

  public function handle(UpdateUserProfile $message)
  {
      UpdateProfileJob::dispatch($message->userId, $message->data);
  }
  

2. Event Sourcing with SimpleBus

• Pattern: Publish domain events as messages.
• Example:

  namespace App\Messages;
  class UserRegistered { public function __construct(public string $userId) {} }
  

• Handler:

  public function handle(UserRegistered $event)
  {
      event(new UserRegisteredEvent($event->userId));
      // Or: Log to a read model via Laravel's event system.
  }
  

3. Hybrid Async/Sync Processing

• Pattern: Use SimpleBus for cross-service communication and Laravel queues for internal jobs.
• Example:

  // SimpleBus message triggers a Laravel job.
  public function handle(OrderCreated $message)
  {
      SendOrderConfirmationJob::dispatch($message->orderId);
  }
  

Integration Tips

Bridging SimpleBus to Laravel Queues

Since SimpleBus doesn’t natively integrate with Laravel’s queue system, create a queue listener to consume SimpleBus messages:

1. Create a Queue Listener:

   namespace App\Listeners;
   use App\Messages\ProcessOrder;
   use Illuminate\Contracts\Queue\ShouldQueue;
   use Illuminate\Queue\InteractsWithQueue;
   
   class SimpleBusQueueListener implements ShouldQueue
   {
       use InteractsWithQueue;
   
       public function handle(ProcessOrder $message)
       {
           // Process the message (e.g., call a handler).
       }
   }
   

2. Dispatch Messages to Laravel’s Queue: Modify your SimpleBus handler to push messages to Laravel’s queue:

   public function handle(ProcessOrder $message)
   {
       SimpleBusQueueListener::dispatch($message);
   }
   

Message Serialization

SimpleBus uses PHP serialization by default. For Laravel compatibility, use JSON:

# config/packages/simple_bus_asynchronous.yaml
simple_bus_asynchronous:
    message_store: 'doctrine://default'
    serializer: 'json' # Override default

Retry Logic

SimpleBus lacks built-in retries. Implement a handler wrapper:

namespace App\Handlers;
use SimpleBus\Message\Handler\MessageHandlerInterface;
use Illuminate\Support\Facades\Log;

class RetryableHandler implements MessageHandlerInterface
{
    public function handle($message)
    {
        try {
            $this->realHandler->handle($message);
        } catch (\Exception $e) {
            Log::error("Message failed: {$e->getMessage()}");
            throw $e; // Laravel's queue will retry.
        }
    }
}

Testing Patterns

Unit Testing Handlers

use App\Handlers\ProcessOrderHandler;
use App\Messages\ProcessOrder;
use PHPUnit\Framework\TestCase;

class ProcessOrderHandlerTest extends TestCase
{
    public function testHandlesMessage()
    {
        $handler = new ProcessOrderHandler();
        $message = new ProcessOrder('order-123');

        $this->assertNull($handler->handle($message));
    }
}

Integration Testing with Laravel Queues

use App\Messages\ProcessOrder;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;

class SimpleBusIntegrationTest extends TestCase
{
    use RefreshDatabase;

    public function testMessageProcessedAsynchronously()
    {
        $this->bus->dispatch(new ProcessOrder('order-123'));

        $this->assertDatabaseHas('jobs', ['payload' => json_encode(['orderId' => 'order-123'])));
    }
}

Gotchas and Tips

Pitfalls

1. No Native Laravel Queue Support:

   • SimpleBus messages won’t appear in Laravel’s failed_jobs table. Use a custom listener to log failures:

     public function handle($message)
     {
         try {
             // ...
         } catch (\Exception $e) {
             \App\Models\FailedJob::create([
                 'message' => serialize($message),
                 'error' => $e->getMessage(),
             ]);
         }
     }
     

2. Serialization Mismatches:

   • SimpleBus’s default serializer may not work with Laravel’s queue payloads. Always use JSON:

     simple_bus_asynchronous:
         serializer: 'json'
     

3. Handler Registration Issues:

   • If handlers aren’t invoked, ensure they’re properly bound in the service container:

     $this->app->bind(\SimpleBus\Message\Handler\MessageHandlerInterface::class, function ($app) {
         return new \App\Handlers\ProcessOrderHandler