Cqrs Laravel Package

Product Decisions This Supports

• Command bus vs. native Laravel dispatch. When weighing whether to introduce an explicit command/handler layer over dispatch(new Job) and event(), this package is a concrete, thin option to prototype against. It provides commands, handlers, and a middleware pipeline without dragging in event sourcing.
• Modular monolith roadmap. Explicit Command → Handler pairs make bounded contexts legible in the codebase. This supports a decision to stay one deployable but enforce seams between domains — the cheap step before any service extraction.
• Build vs. buy for CQRS scaffolding. The build option is a few hundred lines of our own (handler resolution, middleware, container wiring). This package, Ecotone, or Laravel's native bus are the alternatives. Its real value here is as a reference implementation and a low-cost trial, not a platform commitment.
• Sync vs. async write paths. Because it sits on Symfony Messenger, the same command can run in-process or through a transport and worker. That informs whether we invest in queue infrastructure for write workloads.
• Auditability of intent. Commands are named after business intentions (ApproveRefund) rather than table rows. That supports future decisions on audit logging, replay, and compliance reporting.
• Feature-level use cases: multi-step write workflows with validation/authorization pipelines (middleware is the natural home), read-model projections for dashboards, and anywhere our Eloquent models have become god-objects mixing reads, writes, and side effects.

When to Consider This Package

Consider it when:

• The domain is already complex enough that write logic, validation, and side effects are tangled across controllers and models, and a command layer would clarify intent.
• The team is comfortable with Symfony Messenger concepts or already runs Symfony components alongside Laravel — the package is Messenger-native, not Laravel-native.
• You need CQRS only — separate write handlers from read queries — and not event sourcing. There is no event store, aggregate, or replay here.
• You want a small, MIT-licensed, swappable dependency rather than a framework. The handler/middleware surface is easy to wrap behind our own interface, so exit cost is low.
• You are running a time-boxed spike where the cost of evaluation is a day, not a quarter.

Look elsewhere when:

• Vendor risk is unacceptable. Zero stars, zero dependents, no visible community. Treat it as a single-maintainer, unproven dependency. Do not place it on a critical path without a fork-and-own plan.
• The Symfony 4.3+ constraint is unverified against our stack. 4.3 is long EOL; confirm real compatibility with current Symfony Messenger and our Laravel/PHP baseline before it appears in any design document.
• Laravel-native ergonomics matter more. Laravel's Bus, Events, and Queues already cover most of this, and self-handling commands via the container's bus dispatcher are idiomatic and need no third party. Ecotone or a hand-rolled bus may also fit better.
• You need event sourcing, sagas, or process managers. Scope mismatch.
• The team will not maintain the pattern. CQRS adds indirection; without discipline it becomes ceremony. If we cannot fund the refactor properly, skip it entirely.

How to Pitch It (Stakeholders)

To executives: This is a small, MIT-licensed library that adds a structured command layer to our PHP backend. It is not a platform bet — it is a pattern enabler. The business case is maintainability and delivery speed in the complex parts of the product: write logic becomes named, testable, and auditable ("ApproveRefund" instead of scattered controller code), which shortens onboarding and reduces regression risk on our highest-churn features. The cost is low and reversible, but the adoption signal is genuinely weak — no community, no dependents — so the recommendation is a two-week spike on one bounded context, behind our own interface, with a documented exit path. Approve the spike, not a standard.

To engineering: Treat it as a reference architecture and a thin command/handler dispatcher over Symfony Messenger. Concrete asks: (1) verify Messenger version compatibility with our PHP/Laravel baseline — the 4.3+ claim is dated; (2) wrap the dispatcher behind an internal CommandBus interface so we can swap to Laravel's bus or Ecotone without touching call sites; (3) define our middleware set up front — transaction, validation, logging, authorization — since that is where the value and the complexity both live; (4) agree explicitly that we are doing CQRS, not event sourcing: no event store, no replay. If the spike shows no measurable win over dispatch() plus Jobs, we keep the pattern and drop the package.