Eventsauce Snapshotting Laravel Package

Technical Evaluation

Architecture Fit

• Event Sourcing + Snapshotting Alignment: The package extends EventSauce (a PHP event-sourcing library) with snapshot capabilities, making it a strong fit for systems requiring performance optimizations (e.g., reducing event replay overhead) while maintaining event-sourcing consistency.
• Versioned Snapshots: Supports schema evolution via versioned snapshots (VersionedSnapshotState), enabling backward/forward compatibility—a critical feature for long-lived aggregates.
• Conditional Snapshotting: Allows strategic snapshot storage (e.g., every N events), reducing storage costs while preserving replayability.
• Doctrine DBAL Integration: Leverages Doctrine DBAL for persistence, aligning with Laravel’s database-agnostic approach (though Laravel’s Eloquent is not directly supported).

Integration Feasibility

• Laravel Compatibility:
  • Pros: Works with PHP 8.2+ and Doctrine DBAL, which Laravel supports via doctrine/dbal package.
  • Cons: No native Laravel-specific integrations (e.g., Eloquent, Queues, or Laravel’s event system). Requires manual wiring.
• EventSauce Ecosystem: Assumes EventSauce is already in use. If not, adopting this package necessitates full EventSauce integration (e.g., message repositories, event buses).
• Snapshot Storage: Requires a dedicated table for snapshots, adding a new database dependency.

Technical Risk

• Tight Coupling to EventSauce: Migration from other event-sourcing libraries (e.g., Laravel’s built-in event system) introduces rewrite risk.
• Versioning Complexity: Incorrect SnapshotVersionInflector or SnapshotVersionComparator implementations could break aggregate reconstitution.
• Conditional Logic Pitfalls: Misconfigured ConditionalSnapshotStrategy (e.g., EveryNEventConditionalSnapshotStrategy) may lead to inconsistent snapshots or performance degradation.
• Doctrine DBAL Overhead: Laravel’s Eloquent ORM is not supported; raw DBAL queries may conflict with Laravel’s query builder or migrations.

Key Questions

1. Is EventSauce already in use?
   • If not, assess the cost of migration (e.g., event storage, event bus, aggregate roots).
2. How will snapshots interact with Laravel’s caching/queues?
   • Snapshots are not cached by default; manual integration with Laravel’s cache or queue systems may be needed.
3. What’s the snapshot storage strategy?
   • Will snapshots be versioned, and how will schema changes be managed?
4. Performance vs. Storage Trade-offs
   • How will EveryNEventConditionalSnapshotStrategy impact replay speed vs. storage size?
5. Monitoring & Observability
   • How will snapshot creation/loading failures be logged/alerted (e.g., via Laravel’s logging or monitoring tools)?

Integration Approach

Stack Fit

• Core Stack: PHP 8.2+, Laravel (with Doctrine DBAL), EventSauce.
• Database: Supports any DBAL-compatible database (MySQL, PostgreSQL, SQLite), but Laravel’s migrations must be adapted for snapshot tables.
• Event Bus: Requires EventSauce’s event bus (not Laravel’s native event system).
• Testing: Snapshots introduce new failure modes (e.g., version mismatches); unit/integration tests must cover snapshot reconstitution.

Migration Path

1. Adopt EventSauce (if not already using it):
   • Replace Laravel’s event system with EventSauce’s message repository and event bus.
   • Migrate existing aggregates to implement AggregateRootWithSnapshotting.
2. Integrate Snapshotting:
   • Configure DoctrineSnapshotRepository with a dedicated snapshot table.
   • Implement VersionedSnapshotState for aggregates needing schema evolution.
3. Conditional Snapshotting (Optional):
   • Wrap AggregateRootRepositoryWithSnapshotting in AggregateRootRepositoryWithConditionalSnapshot for strategic snapshot storage.
4. Laravel-Specific Adaptations:
   • Use Doctrine DBAL for snapshot queries (avoid Eloquent).
   • Extend Laravel’s service container to bind EventSauce components.
   • Add custom commands for snapshot management (e.g., php artisan snapshot:prune).

Compatibility

• Laravel Services:
  • Not compatible with Eloquent models or Laravel’s event system.
  • Works with Laravel’s database connections (via DBAL) and service container.
• EventSauce Components:
  • Requires EventSauce 3.x (check for breaking changes).
  • UUID encoding must align with EventSauce’s UuidEncoder.
• PHP Extensions:
  • No additional extensions required beyond PHP 8.2+ and Doctrine DBAL.

Sequencing

1. Phase 1: EventSauce Integration
   • Set up EventSauce’s message repository and event bus.
   • Migrate critical aggregates to use AggregateRootBehaviour.
2. Phase 2: Snapshot Infrastructure
   • Create snapshot table via DBAL migrations (not Eloquent).
   • Implement DoctrineSnapshotRepository and SnapshotStateSerializer.
3. Phase 3: Versioned Snapshots
   • Introduce VersionedSnapshotState for aggregates with evolving schemas.
   • Update SnapshotVersionInflector and SnapshotVersionComparator.
4. Phase 4: Conditional Snapshotting (Optional)
   • Add EveryNEventConditionalSnapshotStrategy or custom logic.
5. Phase 5: Laravel Integration
   • Bind EventSauce components to Laravel’s service container.
   • Add Artisan commands for snapshot management.

Operational Impact

Maintenance

• Snapshot Schema Management:
  • New aggregate versions require new SnapshotState classes and migration of snapshot tables.
  • Risk of breaking changes if versioning logic is incorrect.
• Doctrine DBAL Maintenance:
  • Snapshot queries bypass Eloquent, requiring manual DBAL query handling.
  • Laravel’s migration system must be extended to manage snapshot tables.
• Dependency Updates:
  • Tied to EventSauce and Doctrine DBAL versions; updates may require snapshot logic reviews.

Support

• Debugging Snapshots:
  • Reconstitution failures (e.g., version mismatches) are harder to debug than event-only aggregates.
  • No built-in Laravel logging; custom logging must be added for snapshot operations.
• Performance Tuning:
  • Snapshot size and frequency must be monitored to avoid bloat or slow replays.
  • Conditional strategies (e.g., EveryNEvent) require tuning based on aggregate behavior.
• Rollback Strategy:
  • Snapshots complicate aggregate rollbacks; ensure event replay works after snapshot changes.

Scaling

• Database Load:
  • Snapshots reduce event replay time but add write overhead (storing snapshots).
  • Conditional snapshotting can mitigate this, but requires benchmarking.
• Horizontal Scaling:
  • Snapshots are read-heavy; ensure database read replicas are configured if needed.
  • EventSauce’s message repository must also scale (e.g., partitioned storage).
• Storage Growth:
  • Snapshots persist aggregate state; monitor table size to avoid storage costs.

Failure Modes

Ramp-Up

• Learning Curve:
  • EventSauce + Snapshotting requires understanding of event sourcing patterns, versioned state, and Doctrine DBAL.
  • Laravel developers unfamiliar with EventSauce will need training.
• Onboarding Tasks:
  1. Set up EventSauce (message repository, event bus).
  2. Design snapshot strategy (