Cqrs Bundle Laravel Package

Technical Evaluation

Baseline: no prior assessment exists; this establishes v0.5.1 as the reference version.

Architecture fit. somework/cqrs is a Symfony bundle that layers CQRS conventions, an outbox, and middleware (causation id, OpenTelemetry, trace-context capture, deduplication lock release) onto Symfony Messenger. It fits Symfony applications that already run Messenger with Doctrine DBAL and need transactional outbox semantics. It is not a Laravel-native package: the bundle integrates through Symfony's container compiler passes and Messenger bundles, so a Laravel codebase would only be a fit if it already runs Symfony Messenger/Doctrine components. This should be confirmed before treating it as an option in the current stack.

Integration feasibility. High for the narrow target stack. v0.5.1 is a drop-in composer require somework/cqrs-bundle:^0.5.1 with no configuration or API changes from 0.5.0. Two caveats: (1) 0.5.0 is effectively unusable on Symfony 8.2 — 0.5.1 must land first; (2) despite "no breaking changes," two runtime behaviors change (compiler-pass ordering expectations, outbox transport routing), so the upgrade is not purely cosmetic.

Technical risk. The patch itself is low risk and fixes genuine correctness defects (missing middleware, non-compiling container with outbox, ignored handler routes, dropped DelayStamp). The strategic risk sits in the package, not the patch: it is pre-1.0, and it depends on framework internals that are not stable contracts — Symfony 8.2 moved MessengerPass from priority 0 to −16 inside a new MessengerBundle, which silently broke 0.5.0. Testing against 8.2.x-dev signals that upstream churn will keep producing bundle patches. The v0.5.0 outbox rows retain an empty transport, so upgraded applications run with mixed routing until those rows drain.

Key questions.

• Are we on Symfony 8.2, or planning to be within the support window? (If yes, 0.5.1 is a hard prerequisite.)
• Do we own any compiler passes that inspect or mutate CQRS bus middleware? They must run below priority −25.
• Is the outbox enabled without an async bus, and are transports.command_async / transports.event_async set? This determines whether work silently moves from the relay to per-transport workers.
• Do we want handler execution in the transport worker (messenger:consume <transport>) or kept in the relay (sync://)? This is a deliberate operational choice, not a default.
• Who owns this dependency if upstream maintenance slows? The container wiring makes forking non-trivial.
• What is the PHP version floor implied by Symfony 8.2 in our environments?

Integration Approach

Stack fit. Appropriate for Symfony 6.4/7.x/8.2 services using Messenger + Doctrine DBAL. Out of scope for Laravel queue/Horizon-based services unless they already embed Symfony Messenger. Do not adopt it as a general-purpose Laravel CQRS library.

Migration path. 0.5.0 → 0.5.1 is direct, with no code changes required for the default case. For applications still on Symfony ≤8.1, 0.5.1 is safe: the passes now run at −24, which is after MessengerPass on every supported version. For Symfony 8.2 adoption, sequence 0.5.1 first, then the framework upgrade — never the reverse.

Compatibility. Verify Composer constraints resolve together (symfony/messenger, doctrine/dbal, doctrine-bundle, DoctrineBridge). Note that 8.2.x-dev test coverage is evidence of intent, not a stable-version guarantee; pin to released Symfony versions in production. Check that no application compiler pass assumes middleware list ordering that the new −24 priority changes.

Sequencing.

1. Inventory custom compiler passes and their priorities; move anything that must see the bundle middleware below −25.
2. Inventory outbox usage per service: async bus present or not, and whether transports.<type>_async is configured.
3. Decide routing per service: real transport with a running worker, or sync:// to preserve relay-process handling.
4. Deploy 0.5.1 and start messenger:consume <transport> workers before the first outbox writes under the new routing.
5. Only then upgrade Symfony to 8.2.
6. Drain/observe 0.5.0-era rows with empty transport until they are gone; confirm the mixed-routing window is closed.
7. Roll out to a non-production environment first and assert middleware presence on each CQRS bus.

Operational Impact

Maintenance. Low per-release effort, but recurring: each Symfony minor (particularly around Messenger bundle restructuring) has shown it can break the bundle's compiler passes. Budget a recurring "verify after Symfony upgrade" task rather than assuming patch-level stability. Upgrade documentation and changelog discipline are good, which reduces triage cost.

Support. Dependency is young (0.x) and concentrated; it is deeply wired into container compilation, so replacing or patching it in-house is expensive. Treat upstream activity as a tracked risk with a named owner.

Scaling. Behavior changes matter here. Messages that previously executed inline in the relay now run in per-transport workers, shifting load from relay processes to consumer fleets. DelayStamp is now honored for outbox rows without an async bus — previously ignored — so delayed work will actually be delayed, changing throughput and latency profiles. Size worker concurrency for the newly routed traffic; relay capacity may drop.

Failure modes.

• Build-time LogicException if MessengerPass has not run — fail-fast and preferable to silent middleware loss, but it is a deploy-blocking failure mode on unusual kernel/container configurations.
• Loss of causation-id, tracing, trace-context, and dedup lock-release middleware (the 0.5.0-on-8.2 state) — implies duplicate processing and broken distributed traces, i.e., data-integrity risk, not just observability noise.
• NoHandlerForMessageException on events without handlers and EnvelopeAware "envelope has not been set" errors — runtime failures on otherwise valid event flows.
• Outbox rows with empty transport being handled synchronously in the relay; after upgrade, mixed old/new rows route differently, which complicates incident diagnosis.
• Outbox messages bypassing DoctrineBridge 8.2 transaction middleware when stored through a bus (by design; they run in the relay) — transaction boundaries must be understood by on-call.

Ramp-up. Moderate. Engineers need working knowledge of Messenger compiler-pass ordering, the outbox relay, and consumer worker operations. It is not a "composer require and forget" dependency; on-call runbooks should cover outbox transport routing, worker health, and the relay-vs-worker execution split.

Recommendation. Adopt v0.5.1; explicitly prohibit 0.5.0 in any environment reaching Symfony 8.2. Gate the Symfony 8.2 upgrade on 0.5.1 plus completed steps 1–4 above, and require an explicit per-service decision on transport routing before deployment.