Cqrs Laravel Package

Technical Evaluation

Architecture fit

• The package is deliberately thin: it provides two buses (command and query), handler resolution through Laravel's service container, and a small set of contracts and traits. It does not ship event sourcing, read-model projections, aggregate persistence, sagas, or a transport layer. That makes it a pattern enabler, not an architecture in a box.
• Fit is strongest where the team has already decided on CQRS/light command-bus discipline and wants Laravel-native glue rather than a heavier framework (Symfony Messenger, Ecotone, Prooph). It slots into an existing Laravel app without imposing a directory layout or persistence model.
• Fit is weak if stakeholders expect the package to deliver eventual consistency, projections, or event replay. Those remain our responsibility to design and operate.
• Because the surface area is small, it is also easy to wrap behind an internal interface and replace later. That materially lowers the strategic cost of adopting it.

Integration feasibility

• Integration is a composer require plus package auto-discovery; the spike cost is measured in hours, not weeks. A single vertical slice (one command, one handler, one query) is enough to validate the developer experience end to end.
• The real integration work is organizational, not technical: defining handler conventions, naming, payload objects (DTOs vs. arrays), validation placement, transaction boundaries, and where authorization lives. The package is unopinionated here, so we must supply the opinion or teams will diverge.
• Query-side integration is the lowest-risk entry point: read-only, no state mutation, easy to A/B against existing code paths.

Technical risk

• Sustainability / bus factor. 84 stars and a single-maintainer profile is the dominant risk. This is a thin, well-understood wrapper, so the mitigation is straightforward — we can fork or vendor it and maintain it ourselves for a few engineer-days per year. That should be an explicit, pre-agreed fallback, not an emergency.
• Framework compatibility drift. The primary ongoing breakage vector is Laravel major-version upgrades (container resolution, service provider registration, facade behavior). Treat "package supports the Laravel version we are upgrading to" as a gate in our upgrade checklist.
• Abstraction leakage. Without firm conventions, the command bus becomes a second, parallel way to call services, and the codebase ends up with two idioms. This is the most likely failure in practice and is entirely within our control.
• Scope misperception. Teams may assume CQRS implies events, async, or separate read stores. It does not here. Mis-set expectations cause rework.
• Low intrinsic blast radius. No database migrations, no queues required, no external services. Worst case at runtime is a handler-resolution exception, which is contained.

Key questions

1. Which Laravel and PHP versions are supported by the current release, and what is the maintainer's stated policy for supporting new Laravel majors?
2. Does the bus support a middleware/pipeline for cross-cutting concerns (transactions, logging, authorization, idempotency), and is that documented or do we build it?
3. Is async dispatch supported — i.e., can a command be dispatched onto a queue with a serializable handler — or must we layer that on ourselves?
4. What is the intended testing story (fakes, assertions, bus swapping) and does it survive our existing test suite conventions?
5. Who is the named internal owner, and what is our fork/vendor contingency budget?
6. Are there production references beyond the star count, and does the maintainer respond to issues within a reasonable window?

Integration Approach

Stack fit

• Native Laravel: service provider, facades, container-based handler resolution, config publishing. No new runtime, no new infrastructure, no new deployment artifact. It composes with what we already operate (queue workers, Octane, Horizon) rather than replacing it.
• It is a code-organization dependency, not a platform dependency. That keeps it out of the critical path for infra, security review, and disaster recovery planning.

Migration path

• Strangler, not rewrite. Introduce the bus alongside existing controllers and service classes. Controllers become thin: validate, map to a command/query object, dispatch, map the result to a response. No existing endpoint needs to change to adopt the package.
• Read side first. Route new or low-traffic query endpoints through the query bus to build familiarity with near-zero risk.
• Wrap, don't reimplement. Existing service classes become handler bodies in the first pass. Do not refactor domain logic during adoption — that conflates two changes and inflates review load.
• Explicit anti-goal: do not introduce event sourcing, separate read databases, or async command handling in the first phase. Those are follow-on decisions with real operational cost.

Compatibility

• Verify the supported Laravel/PHP matrix against our current and next-planned versions before committing; pin the package version in composer.json and let our dependency automation surface upgrades for review rather than auto-merging.
• Confirm behavior under Laravel Octane (handler state, static caching) if we run it — this is the most common surprise for bus packages in long-lived workers.

Sequencing

1. Week 1 — Spike. One engineer, one bounded context, one command and one query end to end, including tests. Output: a short ADR with the conventions we will enforce.
2. Week 2 — Conventions. Publish internal standards: naming, payload objects, validation placement, transaction boundary, error-to-HTTP mapping, authorization hook.
3. Weeks 3–6 — First vertical slice in production. A single feature area, behind normal release process. Measure review time and onboarding friction, not just correctness.
4. Post-slice — Decide. Expand, hold, or wrap-and-replace. Document the fork contingency before expanding to a second team.

Operational Impact

Maintenance

• Ongoing cost is genuinely low: no schema, no infrastructure, no configuration drift. The recurring tasks are version-pin bumps at Laravel upgrade time and periodic review of the upstream repository's activity.
• The unopinionated design shifts maintenance burden from "upgrading the package" to "maintaining our internal conventions." That is a real cost, just a more controllable one, and it belongs to the architecture group rather than to platform ops.
• Budget a small standing allocation (order of a few engineer-days per year) for the fork contingency. If the package goes quiet, we vendor it and continue.

Support

• Support model is community-only: no vendor, no SLA, no paid tier. Internal support must come from a named owning team with the authority to make convention decisions.
• Escalation path for defects is: patch locally → vendor the fork → replace with an internal bus. All three are cheap because the abstraction is thin; that is the package's main operational virtue.

Scaling

• Throughput scales with the PHP application and the queue workers we already run. The bus adds a container resolution per dispatch — negligible against typical request cost, but worth a quick benchmark in the spike if we expect high fan-out in a single request.
• Synchronous command handling means command duration is request duration. Any command that grows slow must move to the queue, which is our design work, not the package's feature.
• Horizontal scaling is unaffected; there is no shared state, no locks, no coordination introduced by the library.

Failure modes

• Handler not resolvable — container binding or namespace mismatch; fails fast and loudly. Mitigate with a convention test that asserts every command has a handler.
• Unhandled exception mid-command — partial writes if the transaction boundary is not explicitly owned. Mandate a single transaction boundary convention and enforce it in code review.
• Duplicated idioms — the bus coexists with direct service calls indefinitely and the codebase fragments. Mitigate with an explicit adoption boundary per module and a lint/review checklist.
• Silent divergence on payload shape — arrays vs. typed objects. Pick one in the ADR and enforce it.
• Laravel upgrade breakage — surfaces at upgrade time, not at runtime. Covered by the dependency-review gate.

Ramp-up

• The package API is small enough to learn in an afternoon; the real ramp-up is CQRS literacy — when a command is warranted versus a plain service call, and why queries should not mutate. Plan for a short internal walkthrough plus the reference slice as the canonical example.
• Expect roughly one sprint before a mid-level engineer is productive without review, and two before they can set conventions for others. Senior engineers familiar with command-bus patterns will be productive in days.
• The reference implementation and the ADR are the two highest-leverage onboarding artifacts; without them, each team will invent a slightly different CQRS and the package's flexibility becomes a liability.