Message Repository For Doctrine Laravel Package

Technical Evaluation

Architecture Fit

• Event Sourcing Fit: The package is a specialized message repository for EventSauce, a PHP event-sourcing library. It aligns well with CQRS/ES architectures where events are stored persistently for replay, auditing, or projection.
• Doctrine DBAL Integration: Since it uses Doctrine DBAL 3, it fits seamlessly into Laravel (which uses Doctrine DBAL under the hood) without requiring full Doctrine ORM.
• Schema Flexibility: Supports custom table schemas, allowing adaptation to existing event storage patterns (e.g., legacy systems or optimized indexing).
• UUID Handling: Provides binary vs. string UUID encoding, accommodating databases with/without native UUID support.

Integration Feasibility

• Laravel Compatibility: Works with Laravel’s DBAL connection (\Illuminate\Database\Connection), requiring minimal setup.
• EventSauce Ecosystem: Requires EventSauce core (for serialization, UUIDs, etc.), adding dependency complexity if not already in use.
• No ORM Dependency: Avoids Eloquent/Doctrine Entities, making it lightweight but requiring manual schema management.

Technical Risk

• Schema Migrations: Adopting this may require database migrations to align with DefaultTableSchema or LegacyTableSchema.
• UUID Storage Overhead: Binary UUIDs (default) may complicate queries in non-UUID-aware databases (e.g., MySQL without UUID extension).
• EventSauce Lock-in: Tight coupling with EventSauce may limit flexibility if switching event-sourcing libraries later.
• Performance Unknowns: No benchmarks or dependent projects suggest real-world performance characteristics.

Key Questions

1. Why EventSauce? Is this replacing an existing event store (e.g., Laravel’s events table, Redis, or a custom solution)?
2. Database Support: Does the target DB (e.g., MySQL, PostgreSQL) handle UUIDs efficiently? If not, will binary encoding suffice?
3. Schema Compatibility: Will the default schema conflict with existing event tables? Can additionalColumns extend it?
4. Event Serialization: Is the team already using EventSauce’s serializer? If not, what’s the migration path?
5. Concurrency: How will concurrent event writes be handled (e.g., versioning, optimistic locking)?
6. Query Capabilities: Does the app need to query events by type/aggregate/date? If so, does the schema support indexing?
7. Testing: Are there existing tests for event replay, projections, or auditing that depend on this repo?

Integration Approach

Stack Fit

• Laravel + Doctrine DBAL: Native integration via Laravel’s DBAL connection (db()->getDoctrineConnection()).
• EventSauce Core: Required for UUIDs, serialization, and event metadata. Must be installed alongside this package.
• Database: Works with PostgreSQL (native UUID), MySQL (binary UUIDs), or SQLite (with UUID extensions).
• Alternatives: If avoiding EventSauce, consider Laravel’s built-in event system or ProophEventStore (another PHP ES library).

Migration Path

1. Assess Current Event Storage:
   • If using a custom table, adapt TableSchema to match.
   • If using Laravel’s events table, migrate data to the new schema.
2. Install Dependencies:

   composer require eventsauce/message-repository-for-doctrine eventsauce/event-sauce eventsauce/uuid-encoding
   

3. Configure Repository:

   use EventSauce\MessageRepository\DoctrineMessageRepository\DoctrineUuidV4MessageRepository;
   use EventSauce\MessageRepository\TableSchema\DefaultTableSchema;
   use EventSauce\UuidEncoding\BinaryUuidEncoder;
   
   $repository = new DoctrineUuidV4MessageRepository(
       connection: app('db')->getDoctrineConnection(),
       tableName: 'event_store',
       serializer: $eventSauceSerializer,
       tableSchema: new DefaultTableSchema(),
       uuidEncoder: new BinaryUuidEncoder(),
   );
   

4. Update Event Publishing:
   • Replace direct DB inserts with repository->store($event).
   • Ensure UUIDs are generated via EventSauce’s Uuid (not Laravel’s Str::uuid()).
5. Schema Migration:
   • Create a migration for the new table (e.g., event_id, aggregate_root_id, version, payload).
   • For legacy systems, use LegacyTableSchema.

Compatibility

• Doctrine DBAL 3: Laravel 8+ uses DBAL 3 by default; older versions may need updates.
• EventSauce Version: Ensure compatibility with the EventSauce major version (e.g., v1.x).
• PHP 8.0+: EventSauce requires PHP 8.0+, which Laravel 9+ supports.

Sequencing

1. Prototype: Test with a single aggregate type to validate schema and performance.
2. Benchmark: Compare write/read speeds against current storage (e.g., Redis, custom table).
3. Rollout:
   • Phase 1: Use in non-critical projections first.
   • Phase 2: Migrate core aggregates after validating replayability.
4. Fallback Plan: Maintain dual-writes if risk is high.

Operational Impact

Maintenance

• Schema Updates: Future changes to TableSchema may require migrations (e.g., adding columns).
• Dependency Updates: EventSauce/Doctrine DBAL updates could introduce breaking changes.
• Monitoring: Track event storage growth (e.g., payload size) and query performance (e.g., aggregate_root_id indexes).

Support

• Limited Community: No stars/dependents suggest low community support; issues may require upstream (EventSauce) resolution.
• Debugging: Binary UUIDs or custom schemas may complicate troubleshooting (e.g., "Why is my event not found?").
• Documentation: README is minimal; expect to reverse-engineer usage from tests/examples.

Scaling

• Read Scaling: Supports read replicas if the DB allows (e.g., PostgreSQL streaming replicas).
• Write Scaling: No built-in sharding; rely on DB-level partitioning or Laravel queues for batch writes.
• Performance:
  • Writes: Single-row inserts per event; overhead from UUID encoding/serialization.
  • Reads: Efficient for aggregate_root_id lookups but slow for global event queries (e.g., "all OrderCreated events").

Failure Modes

Ramp-Up

• Learning Curve:
  • Moderate: Requires understanding of EventSauce’s event model (e.g., Event, Metadata).
  • Low: If already using EventSauce; high if new to event sourcing.
• Onboarding Tasks:
  1. Set up EventSauce core (UUIDs, serialization).
  2. Configure Doctrine DBAL connection in Laravel.
  3. Design table schema (default vs. custom).
  4. Write migration scripts for existing events.
• Training Needed:
  • Event sourcing patterns (e.g., replaying events for projections).
  • Doctrine DBAL query building (if custom queries are needed).