Laravel Eventstore Laravel Package

Technical Evaluation

Architecture fit. gosuperscript/laravel-eventstore is an event-sourcing persistence layer for Laravel — it stores domain events (and typically snapshots) in the application database and exposes them through Laravel's service container, config, and migration conventions. It fits if we need an audit trail, event replay, or event-sourced aggregates and are already committed to Laravel + a relational store. It is a poor fit if we only need append-only logging (a table and a job would do) or if we plan to scale event volume beyond what a single relational store can absorb without snapshotting and archival.

Integration feasibility. Standard Composer install with package auto-discovery, config/migration publishing, and aggregate-root base classes or traits. The realistic effort is not installation but domain modeling: aggregates, event versioning, projectors/read models, and replay tooling. Budget for that, not for the composer require.

Technical risk. v8.4.1 is a single-line behavioral change: connection-loss conditions now throw ConnectionLostException instead of a plain Exception (#33). This is non-breaking under semver for anyone catching \Exception, but it is a silent behavior change for two groups:

1. Code with a bare catch (\Exception $e) around store writes will continue to work but will keep treating a recoverable connection loss as a generic failure — retries, backoff, and 503 mapping will not engage.
2. Code that inspects exception class names, messages, or log-scrubbing rules keyed to the generic type will need updating; alerting on "generic exception from event store" will go quiet at exactly the moment it matters.
3. Catch-block ordering matters: any catch (\Exception) placed before a catch (ConnectionLostException) makes the new type unreachable.

The change is a net improvement — it makes transient infrastructure failure distinguishable from domain/validation failure — but it only pays off if we actually consume the new type.

Key questions.

• What is ConnectionLostException's parent class and namespace, and does it implement a marker interface we can catch broadly? Is the FQCN stable across 8.x?
• Does the package provide any retry/backoff semantics, or is this purely a signaling change we must handle ourselves?
• What are the supported PHP/Laravel version constraints in composer.json for 8.4.x, and what is the project's BC policy given it has already shipped eight majors?
• Is the underlying connection loss detectable in advance (pool exhaustion, failover) or only observable at write time?
• How are partial writes handled when the connection drops mid-append — is there any transactional guarantee documented?

Integration Approach

Stack fit. Assumes Laravel with a relational database (MySQL/Postgres) and standard queue workers. The connection-loss exception is most relevant in queue-driven projectors and long-running consumers, where a dropped connection is expected transient noise rather than a request-scoped failure. Web-request paths need a distinct mapping (retryable 503) instead of a 500.

Migration path. Pin ^8.4.1. The concrete work item is exception handling, not the version bump:

1. Grep for catch (\Exception and catch (\Throwable in and around event-store call sites.
2. Insert a specific catch (ConnectionLostException $e) before the generic handler, with bounded retry and backoff.
3. Update the global exception handler / error-reporting config so the new type is classified as infrastructure, not application, failure.

Compatibility. Patch-level release; no schema migration, no public API signature change, no deprecations announced. Risk is concentrated in exception-handling code and in anything that pattern-matches on exception class strings. Confirm no other internal package pins laravel-eventstore to an exact 8.4.0.

Sequencing.

1. Bump in a non-production environment; run existing event-store tests.
2. Add explicit handling for ConnectionLostException and a test that simulates a dropped connection (kill the DB connection mid-append or use a fault-injecting connection wrapper) to prove retry engages.
3. Update logging/alerting rules and dashboards to key on the new type.
4. Soak in staging under queue load, then promote. Low urgency — this is not a security or data-corruption fix — but it should not sit indefinitely, since the value of the change is entirely realized in our handling code.

Operational Impact

Maintenance. Low ongoing cost; upstream is actively cutting patch releases, which is a positive signal but also means routine version hygiene. Track the changelog for the next major (v9), where breaking changes to exception hierarchy or Laravel support windows are likely.

Support. The exception class is now part of the public contract we depend on. Support runbooks and on-call alerts should distinguish "event store connection lost" (retry, check DB pool/failover) from "event store rejected write" (investigate aggregate/concurrency). Without that split, both look identical in logs and mean very different things to whoever is paged.

Scaling. The dominant scaling concern is event-table growth, not this release: row count, index bloat, snapshot cadence, and read-model rebuild time all degrade before connection handling does. The connection-loss change becomes material precisely as we scale — higher write concurrency, connection-pool contention, and replica failovers all increase the frequency of transient drops, and the new type is what lets us absorb them instead of surfacing them.

Failure modes.

• Silent behavior regression: generic catch (\Exception) swallows the new type; retries never fire; transient blips become user-visible errors. Highest-likelihood risk of this release.
• Catch ordering: specific handler placed after generic handler, unreachable.
• Alerting gap: monitoring keyed to generic exception class stops matching; failures go unreported.
• Unhandled type: if the class is not loadable (autoload/version skew), the throw itself fails and masks the original connection error.
• Partial append: connection loss mid-write may leave ambiguity about whether the event persisted — verify the package's transactional guarantees before enabling blind retries, or we risk duplicate events.

Ramp-up. Small for the version bump; meaningful for the underlying discipline. Engineers need working knowledge of event sourcing (aggregates, projections, replay, idempotency) and of the new exception contract. Estimate a short pairing session plus a written handling pattern in the team's Laravel conventions doc, rather than formal training.