Domain Events Laravel Package

Technical Evaluation

Architecture fit. complex-heart/domain-events targets the domain layer: it gives you primitives for recording events inside aggregates and a bus abstraction for publishing them, rather than a full event-sourcing framework. That is the right shape for a hexagonal or DDD-style Laravel codebase where the domain must stay free of framework imports (no Illuminate\* in entities). It complements, rather than replaces, Laravel's native event dispatcher: the domain records, an adapter publishes. If our architecture is "Laravel-first, models are the domain," the package adds a layer we will not use and the fit is poor.

Integration feasibility. MIT-licensed, Composer-installable, small public surface. The realistic effort is not in installing it but in writing the glue: a Laravel service provider binding, a bridge from the package's bus to EventDispatcher, transaction-aware dispatch (after-commit), and a listener registration convention. Budget 3–5 engineer-days for a spike plus adapter, not the "composer require" hour the README implies.

Technical risk. High, and concentrated in maturity rather than design. Signals: 0 stars, 0 dependents, a single maintainer, a release date of 2026-03-15 (i.e., effectively brand new), and an opportunity score of 34.35 — the problem space is already served by spatie/laravel-event-sourcing, EventSauce, Symfony Messenger, and Laravel's own events. Zero dependents means zero production battle-testing; we would be among the first to find the edge cases. Specific risks: pre-1.0 API churn, undocumented serialization contract, unclear PSR-14 compliance, no stated PHP/Laravel version matrix, no security policy.

Key questions for the maintainer (or our own spike).

1. Is the event bus PSR-14 compatible, or a bespoke interface requiring an adapter?
2. How are events serialized, and is the format stable/versioned for outbox persistence or queue transport?
3. Is dispatch immediate or deferred; is there an after-commit hook, and is it transaction-aware?
4. Does it ship a Laravel service provider, or is that explicitly out of scope?
5. What is the versioning/support policy, and who is the backup maintainer?
6. What happens on listener exceptions — collect, rethrow, or swallow?

Integration Approach

Stack fit. Assumes PHP 8.1+ and a PSR-4 autoloaded codebase; framework-agnostic by design, so it slots into Laravel 10/11/12 only through an adapter we own. It is a fit for a modular monolith with explicit bounded contexts; a poor fit for a legacy CRUD app where "domain events" would be a rename of model observers.

Migration path. Do not retrofit. Pick one bounded context (billing, orders, onboarding) and introduce the package there, leaving existing Laravel events untouched. Where that context currently fires event(new OrderPlaced(...)) from a controller or observer, move the raise into the aggregate, keep the existing Laravel event as the outward-facing contract, and have the adapter translate. This gives a reversible seam: deleting the package's usage restores the status quo.

Compatibility. Verify before committing: PHP constraint vs. our runtime, whether the bus interface is PSR-14 (Psr\EventDispatcher\EventDispatcherInterface) or custom, and whether serialization uses __serialize, reflection, or manual toArray. If events must cross a queue or an outbox table, custom serialization is the single largest hidden cost — treat an unstable format as a blocker for async use.

Sequencing.

1. Week 1 — spike (1 dev): install in a branch, model three real events from the pilot context, write the Laravel bridge, prove dispatch-after-commit and listener failure behaviour.
2. Week 2 — decision: ADR comparing it against writing ~150 lines of in-house RecordsEvents trait + DomainEventBus. At this maturity level, in-house is a legitimate winner; the package must beat it on more than novelty.
3. Weeks 3–4 — pilot: one bounded context, event catalog documented, no async transport yet.
4. Later: outbox/relay only if the persistence contract proves stable; expand context by context.

Operational Impact

Maintenance. We should assume we own the code. Plan for a vendored fork or a pinned version with a documented patch queue; add it to the dependency review list with a named owner. A solo-maintainer package with no dependents is a bus-factor-1 dependency in our supply chain, and an abandoned release two years from now is the base case, not the tail risk.

Support. No community, no Stack Overflow corpus, no issue history to mine — every question is answered by reading source. Budget for internal documentation of the bus contract, event naming convention, and serialization format; that documentation is the actual deliverable, not the dependency.

Scaling. In-process, synchronous dispatch scales fine and is where this package is safest. Anything crossing a process boundary — queues, outbox, event store, projections — pushes work back onto us: delivery guarantees, idempotency keys, replay, schema evolution. Do not read "domain events" as "event-driven architecture"; the package supplies the vocabulary, not the reliability.

Failure modes to design against. Events dispatched before commit and then lost on rollback; duplicate delivery with no idempotency; deserialization breaking when a class is renamed or a property is removed; listener exceptions silently swallowed so a downstream projection drifts; event ordering assumptions violated once async is introduced.

Ramp-up. The API surface is small, so a mid-level engineer is productive in 1–2 days; the real cost is conceptual — aggregates, invariants, and why events are raised rather than fired from controllers. Expect one sprint of pairing for the pilot team plus a short internal brown-bag. Keep the blast radius at one bounded context until the adapter and the event catalog have survived a full release cycle.