Bus Laravel Package

Product Decisions This Supports

Feature architecture: build vs. buy for command orchestration. The command bus is a solved problem inside Laravel, so the build-vs-buy decision collapses to "do we adopt the framework's native bus or hand-roll a service layer?" Choosing illuminate/bus avoids maintaining bespoke orchestration code while giving you middleware, queue dispatch, and handler resolution for free — the package is MIT-licensed and shipped with the framework, so it carries no procurement, licensing, or vendor-contract overhead.

Roadmap: staging complexity against delivery speed. The bus pattern pays off when workflows grow (multi-step checkout, onboarding, provisioning, billing retries). It lets the team defer building an internal workflow engine by using queued commands plus chaining (chain(), onQueue()) as the orchestration primitive. Conversely, if the roadmap is mostly CRUD and read-heavy screens, adopting the bus is premature structure that will slow delivery.

Cross-cutting requirements get a single enforcement point. Validation, authorization, audit logging, and correlation IDs become bus middleware applied uniformly rather than re-implemented per controller. This is the strongest product argument: it turns compliance and observability asks from "sprinkle it everywhere" into "one pipeline, one review."

Scalability decisions without re-architecture. Making a command implement ShouldQueue moves work off the request cycle with no product-facing redesign. That gives you a lever for p95 latency and throughput that is a one-line change, not a roadmap item — useful when traffic forecasts shift mid-quarter.

Domain boundaries and team scaling. Commands map cleanly onto business capabilities (ProcessOrder, GenerateInvoice), giving product and engineering a shared vocabulary for features. That alignment pays off when multiple squads touch one codebase or when you need to isolate, audit, or later extract a domain.

Testability as a planning input. Bus::fake() lets integration tests assert intent ("this command was dispatched") separate from side effects. For a PM this means faster, less brittle regression suites — directly affecting release cadence and the cost of each sprint's QA.

What it explicitly does not decide: it does not buy you a message broker, a Saga/workflow engine, or cross-service eventing. If the roadmap includes multi-service orchestration or non-PHP consumers, treat this as an in-process tool and budget a separate decision (e.g., Symfony Messenger, a queue-backed event bus, or a dedicated workflow service).

When to Consider This Package

Adopt when:

• The product is a monolithic Laravel application already on the matching framework major version (this split requires illuminate/* ^13.0). Anything older means an upgrade project precedes adoption.
• Business logic has outgrown controllers and models — order fulfillment, subscriptions, provisioning, imports, approval chains — where a "do the thing" operation has preconditions, side effects, and retries.
• Requirements include one or more of: async/deferred processing, retry semantics, per-operation auditing, or uniform validation and authorization across operations.
• The team is already fluent in Laravel conventions (auto-wired handlers, ShouldQueue, queue workers, Bus::fake()). Skill fit is the single largest determinant of whether this accelerates or confuses.
• You need a consistent, reviewable pattern across squads more than you need bespoke flexibility.

Look elsewhere when:

• The project is not Laravel, or is a microservice stack with mixed runtimes. The package has hard dependencies on Laravel contracts, collections, and support; extracting it standalone invites dependency conflicts. Use Symfony Messenger or a broker-native SDK instead.
• The scope is genuinely simple CRUD. The bus adds indirection, an extra class per operation, and a handler-resolution convention to learn — over-engineering that shows up as slower onboarding and harder debugging.
• You need durable, cross-service, or long-running orchestration with compensation logic. A command bus is not a workflow engine; forcing Sagas through it produces fragile code.
• You cannot operate queue workers. Async commands require running and monitoring workers; if infra ownership is absent, the async benefits are theoretical and failures become silent.

Decision questions to put in the PRD: Which two or three workflows justify the pattern? Does the team already run queue workers in production with alerting? Is the framework version current? Are there non-PHP or non-Laravel consumers on the horizon?

How to Pitch It (Stakeholders)

One-line summary: We get a production-grade, zero-cost command orchestration layer that is already part of our framework — no license, no vendor, no new infrastructure — and it lets us ship complex workflows faster without building a custom orchestration layer.

For executives: This is not a new dependency; it is an existing component of Laravel we are choosing to use deliberately rather than ignore. Cost is engineering time only. The business return is threefold: faster delivery of multi-step features, a single auditable place to enforce validation, permissions, and logging, and the ability to absorb traffic spikes by moving work to background queues without re-architecting. The primary risk is misapplication — using it for trivial features — which we mitigate with a short adoption guideline rather than a broad mandate.

For engineering: It is the framework-native implementation of the command bus, tightly integrated with the service container, queue system, and event dispatcher. We adopt it incrementally: start with synchronous dispatch for one real workflow, add middleware for logging/validation once the pattern is proven, then flip specific commands to ShouldQueue for async. Key cautions we will document: handler naming conventions must match or handlers silently fail to resolve; handle() parameters need strict types; Bus should come via injection or the facade, not container resolution; version alignment with the framework is mandatory; and queued commands need monitored workers. Testing is a strength — Bus::fake() gives us intent-level assertions and faster suites.

Ask: Approve a scoped pilot on one or two workflows this cycle, plus a lightweight one-page internal guideline (when to use a command, naming, middleware, queue operations). We will review delivery velocity and incident profile after the pilot before broadening adoption across squads.