Bus Laravel Package

Getting Started

Start by verifying illuminate/bus is included in your Laravel installation (it’s auto-registered via app.php or service provider discovery in Laravel 11+). No extra installation is needed—just begin dispatching commands. Your first real-world use case is replacing inline business logic (e.g., in a controller) with a dedicated command:

// Instead of:
$order->process();

// Use:
dispatch(new ProcessOrder($order));

Dispatch synchronously in tests or inline contexts via dispatchSync(), and asynchronously (via queues) via dispatch(). Check Bus::dispatched() assertions in feature tests to validate command intent.

Implementation Patterns

• Command-Handler Co-location: Prefer defining handle() directly inside your command class for simplicity (e.g., ProcessOrder::handle()), especially for small/medium domains.
• Middleware Pipeline: Apply cross-cutting concerns globally (e.g., Bus::pipeThrough([LogCommands::class])) or per-command via Bus::dispatchSync($command)->then(...) (advanced).
• Queue Integration: Make commands implement ShouldQueue to automatically dispatch to your queue connection—no extra config needed. Use onQueue(), onConnection(), and chain() for orchestration.
• Testing Strategy: In unit tests, mock the Bus facade to assert dispatched commands without side effects. In feature tests, use Bus::fake() to prevent real dispatching while verifying expectations.
• Domain Separation: Group commands in App/Commands and handlers (if separated) in App/Handlers/Commands, mirroring DDD principles to decouple business rules from HTTP layer concerns.

Gotchas and Tips

• Handler Resolution Fallback: Laravel auto-wires handlers only if they follow naming conventions (e.g., GenerateInvoiceHandler for GenerateInvoice). Rename mis-matched handlers to avoid silent failures.
• Type-Strict handle() Methods: Parameters must match exact types (e.g., Order|null $order won’t auto-resolve if null isn’t accepted); use strict type declarations and validation.
• No Direct Container Binding: Avoid resolving Bus from the container directly—prefer dependency injection in classes or use the Bus facade for clarity.
• Laravel Version Lock: This package requires illuminate/* ^13.0; mixing with older Laravel versions (e.g., 10.x) will cause dependency conflicts. Always align with your Laravel version.
• Debugging Delayed Dispatches: If queued commands stall, verify ShouldQueue is implemented, queue workers are running (php artisan queue:work), and exceptions are caught/logged in the job.
• Extensibility Tip: Extend Bus (e.g., CustomBus extends Bus) and bind it in AppServiceProvider to inject custom logic (e.g., correlation IDs, audit logging) without monkey-patching core behavior.