Api Platform Event Engine Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Event-Driven CQRS Alignment: The package bridges API Platform (REST/GraphQL API layer) with Event Engine (CQRS/Event Sourcing), enabling a clean separation between read/write models. This aligns well with domain-driven design (DDD) and event-driven architectures, particularly for systems requiring auditability, eventual consistency, or complex business workflows.
• Aggregate-Centric Design: Forces explicit modeling of aggregates (via AggregateRoot) and commands (via AggregateCommand), which enforces bounded context boundaries and reduces accidental coupling between API endpoints and business logic.
• Schema-Driven Contracts: Leverages JSON Schema (JsonSchemaAwareRecord) for both commands and state, ensuring machine-readable contracts between API Platform and Event Engine. This is valuable for API-first and microservices architectures where schema validation is critical.

Integration Feasibility

• API Platform Compatibility: Works with API Platform 3.x, which is stable but not the latest (current is 4.x). Backward compatibility risks exist if upgrading API Platform later.
• Event Engine Dependency: Tightly coupled with arnedesmedt/event-engine-symfony-bundle (v0.8.0), which may introduce vendor lock-in or maintenance overhead if the upstream bundle evolves.
• Symfony Ecosystem: Assumes a Symfony-based stack (e.g., dependency injection, messenger component). Non-Symfony PHP projects (e.g., pure Laravel) would require significant adaptation.
• Laravel-Specific Challenges:
  • No Native Laravel Support: The bundle is Symfony-first, requiring workarounds (e.g., Symfony’s Bundle system, ContainerInterface) in Laravel.
  • Event Dispatching: Laravel’s event system differs from Symfony’s Messenger/EventDispatcher. Mapping API Platform operations to Event Engine commands would need custom middleware or listeners.
  • Serialization: Laravel uses Laravel Serialization (e.g., Illuminate\Support\Collection), while this bundle relies on team-blue/php-json-immutable-objects. Potential serialization mismatches could arise.

Technical Risk

Key Questions

1. Why Event Engine?

   • What specific CQRS/Event Sourcing requirements justify this over native Laravel solutions (e.g., laravel-echo, spatie/laravel-event-sourcing)?
   • Is the team already invested in the Event Engine ecosystem?

2. Laravel Adaptation Effort

   • How will Symfony’s Bundle system be replaced in Laravel? (e.g., via service providers, package wrappers)
   • Are there alternative Laravel packages (e.g., spatie/laravel-cqrs) that could achieve similar goals with less friction?

3. Aggregate Design

   • How will aggregate roots and commands map to existing Laravel models/resources?
   • Will this introduce duplication (e.g., separate API Platform entities vs. Event Engine aggregates)?

4. Operation Mapping

   • How will API Platform’s operations (e.g., POST /orders, PATCH /orders/{id}) be explicitly mapped to Event Engine commands?
   • What happens with unmapped operations (e.g., bulk actions, custom API routes)?

5. Error Handling & Rollback

   • How will failed commands or invalid state transitions be handled? (e.g., retries, compensating events)
   • Does Event Engine support saga patterns for distributed transactions?

6. Testing Strategy

   • How will event-command flows be tested? (e.g., unit tests for aggregates, integration tests for API ↔ Event Engine)
   • Are there mocking challenges given the tight coupling with Event Engine?

7. Long-Term Maintenance

   • Who will maintain this integration if the upstream bundles (event-engine-symfony-bundle) evolve?
   • Is there a fallback plan if the package becomes unmaintained?

Integration Approach

Stack Fit

Migration Path

1. Assessment Phase

   • Audit existing API Platform resources and business workflows to identify aggregate boundaries.
   • Map current CRUD operations to potential Event Engine commands/queries.

2. Proof of Concept (PoC)

   • Implement a single aggregate (e.g., Order) with:
     • API Platform resource → Event Engine command mapping.
     • JSON Schema validation for commands/state.
   • Test with Laravel’s event system as a proxy for Event Engine.

3. Abstraction Layer

   • Create a Laravel-specific wrapper for event-engine-symfony-bundle:
     • Replace Bundle with a service provider.
     • Adapt ContainerInterface to Laravel’s Illuminate\Container.
     • Use Laravel’s queue system for command dispatching.
   • Example:

     // app/Providers/EventEngineServiceProvider.php
     public function register()
     {
         $this->app->singleton(EventEngine::class, function ($app) {
             return new EventEngine(
                 $app->make(CommandBus::class), // Laravel queue-based
                 $app->make(Store::class)       // Custom store adapter
             );
         });
     }
     

4. Incremental Rollout

   • Phase 1: Migrate write-heavy aggregates (e.g., orders, users) first.
   • Phase 2: Gradually replace read models with projections from Event Engine.
   • Phase 3: Deprecate direct model updates in favor of command-based mutations.

5. Fallback Strategy

   • If integration proves too cumbersome, consider:
     • Hybrid approach: Use Event Engine for critical aggregates, keep others in Laravel.
     • Alternative packages: Evaluate spatie/laravel-cqrs or laravel-echo for simpler event-driven needs.

Compatibility

Sequencing

1. Setup Dependencies
   • Install api-platform/laravel and `arnedesmedt/event-engine