Cqrs Bundle Laravel Package

Product Decisions This Supports

• Build vs. buy for transactional messaging: this bundle is the "buy" option for the CQRS + transactional outbox layer — command/event buses, outbox persistence, relay, deduplication, OpenTelemetry/trace-context propagation, causation IDs. If your roadmap includes reliable event publishing without a full message-broker migration, this is the layer you'd otherwise spend a quarter building and a year hardening.
• Roadmap timing on framework upgrades: v0.5.1 is effectively an upgrade enabler — it is the prerequisite for adopting Symfony 8.2. Any roadmap item gated on the next Symfony LTS (8.2) inherits this dependency and its version constraint.
• Architecture decision: async bus or not: 0.5.1 makes transports.command_async / transports.event_async authoritative even when no async bus exists. That turns a previously implicit design choice (relay handles rows in-process vs. a dedicated worker consumes them) into an explicit, configurable one — a decision PMs and platform leads should settle deliberately, because it changes deployment topology and operational runbooks.
• Operational readiness / on-call scope: after upgrade, outbox-only applications must run messenger:consume <transport> for the configured transports, or point them at sync:// to preserve prior behaviour. That's a staffing and deployment-pipeline consequence, not just a code change.
• Observability investment: built-in OpenTelemetry and trace-context middleware means distributed tracing across command/event flows comes "free" rather than as a bespoke instrumentation project — relevant if observability is a roadmap theme.
• Use cases this unlocks: transactional consistency between DB writes and event publication (outbox), delayed/retried message handling (DelayStamp), deduplication for at-least-once delivery, and handler-less events as a first-class pattern.

When to Consider This Package

Consider it when:

• You are on Symfony (this is a Symfony bundle, not a Laravel package — Laravel teams should treat the concepts as a reference architecture, not a drop-in dependency; equivalent Laravel territory is largely covered by Laravel's queue/outbox patterns or packages like EventSauce/Ecotone).
• You need guaranteed at-least-once publication of domain events alongside DB transactions and want the outbox implemented for you rather than hand-rolled.
• You are standardising DDD/CQRS conventions (command bus, event bus, handlers, middleware) across multiple teams and want an opinionated, framework-native implementation.
• You need trace propagation and deduplication in a message-driven system and would otherwise build cross-cutting middleware in-house.
• You are planning a Symfony 8.2 upgrade and want the middleware/compiler-pass plumbing handled — but only on ≥0.5.1, and only with a review of UPGRADE.md.

Look elsewhere when:

• You are on Laravel and want a native fit — this bundle's value is in Symfony's Messenger/DI/compiler-pass machinery.
• You need vendor stability guarantees: the package is pre-1.0 (0.x), so minor versions may contain behaviour changes and patches may require operational changes (as 0.5.1 does). If you cannot absorb that cadence, a heavier but stable broker-based stack (e.g. a managed queue + an established outbox library) is safer.
• Your team lacks Symfony DI / compiler-pass depth: 0.5.1 changes pass priorities and will fail the build with a LogicException if Messenger's pass hasn't run. Custom passes touching bus middleware must sit below priority −25. This is expert-level territory.
• You have no async workers and no appetite to operate them: you'd be pinning transports to sync://, which partly negates the async value proposition.
• Your messaging needs are trivial (a few fire-and-forget jobs) — the outbox and relay are unnecessary complexity.

Release-specific adoption notes (v0.5.1): no breaking API or config changes, but it is a required upgrade before Symfony 8.2 — 0.5.0 is materially broken there (missing middleware, NoHandlerForMessageException on handler-less events, EnvelopeAware failures, container not compiling with outbox enabled, routing ignored). Treat the "no breaking changes" claim carefully: the outbox transport fix is a silent behaviour change for outbox-only apps, and rows written by 0.5.0 retain their empty transport and will keep being handled in the relay process. Pin ^0.5.1 explicitly; do not float on ^0.5.0.

How to Pitch It (Stakeholders)

For executives: We're evaluating a small open-source component that provides the messaging backbone for our PHP/Symfony services — it makes sure business events are reliably published when data changes, and gives us tracing and de-duplication without building it ourselves. The latest patch (0.5.1) is a compatibility release: it fixes a real breakage on the next Symfony version and closes a configuration gap for teams not running background message workers. There are no API changes, but the upgrade requires a short operational step (running message workers, or a config switch). Main risk is that the project is pre-1.0 and moves quickly; mitigation is version pinning and a documented upgrade runbook.

For engineering: Adopt only on ≥0.5.1, and upgrade in the same change window as Symfony 8.2 — 0.5.0 is broken on 8.2 in five distinct ways. Budget for two operational chores: (1) audit your own compiler passes; anything that must observe or mutate bus middleware lists needs priority below −25, since the bundle's passes now run at −24 and fail loudly with a LogicException if Messenger's MessengerPass hasn't executed; (2) if you use the outbox without an async bus, decide per transport between messenger:consume <transport> (rows now carry the configured transport) and sync:// (preserves the old in-relay behaviour). Expect pre-existing outbox rows from 0.5.0 to keep their empty transport and continue in the relay — plan a drain or accept the mixed behaviour. Upside: handler-less events, EnvelopeAware handlers, #[AsMessageHandler(transport: …)] routing and outbox compilation all work again on 8.2, and DoctrineBridge 8.2's transaction middleware is correctly skipped under the outbox regardless of service id. Net read: solid capability, thin operational margin — worth a time-boxed spike, not a blind production rollout.