Broadway Laravel Package

Technical Evaluation

Architecture Fit

• CQRS/ES Alignment: Broadway is a strong fit for Laravel applications requiring CQRS (Command Query Responsibility Segregation) and Event Sourcing (ES) patterns. It enforces separation between read/write models, making it ideal for high-coherence domains (e.g., financial systems, inventory management).
• Loose Coupling: Components (e.g., EventStore, CommandBus, ReadModel) are modular, allowing selective adoption (e.g., use EventStore without full ES).
• Domain-Driven Design (DDD) Support: Provides abstractions for Aggregate Roots, Domain Events, and Sagas, aligning with DDD principles.
• Laravel Compatibility: The Laravel package bridges Broadway’s core with Laravel’s service container, middleware, and routing.

Integration Feasibility

• Event Store Backends: Supports Doctrine DBAL (via broadway/event-store-dbal), MongoDB, and in-memory stores. Laravel’s Eloquent or Query Builder can integrate with DBAL.
• Read Model Projections: Supports Elasticsearch and MongoDB for read models, requiring additional packages but enabling scalable queries.
• Command/Event Buses: Can replace Laravel’s native request handling with Broadway’s CommandBus for structured workflows (e.g., API endpoints dispatching commands).
• Testing Helpers: Built-in scenario-based testing for ES aggregates simplifies test writing (critical for complex domains).

Technical Risk

• Learning Curve: CQRS/ES introduces new paradigms (e.g., event replay, projection management). Teams unfamiliar with these patterns may face adoption resistance.
• Performance Overhead:
  • Event Store: DBAL-backed stores may introduce latency for high-throughput systems (mitigated by snapshotting).
  • Read Models: Projections require background processing (e.g., Laravel Queues) to avoid blocking requests.
• Laravel-Specific Gaps:
  • No native HTTP middleware for command dispatching (requires custom middleware or API gateways).
  • Authentication/Authorization: Must be implemented manually (e.g., via middleware or command guards).
• Dependency Complexity:
  • Optional Components: Saga, Snapshotting, and Sensitive Data Handling add surface area but aren’t required.
  • PHP Version: Requires PHP 7+ (compatible with Laravel 8+).

Key Questions

1. Domain Complexity:
   • Is the use case event-driven (e.g., auditing, workflows) or CRUD-heavy? If the latter, Broadway may be overkill.
2. Scaling Needs:
   • Will read models require real-time projections (e.g., Elasticsearch) or batch updates?
3. Team Expertise:
   • Does the team have experience with CQRS/ES? If not, budget for training or proof-of-concept development.
4. Persistence Layer:
   • Is Doctrine DBAL acceptable, or are other backends (e.g., PostgreSQL JSONB) preferred?
5. Testing Strategy:
   • Will scenario-based testing replace Laravel’s native testing tools (e.g., HTTP tests)?

Integration Approach

Stack Fit

• Laravel Compatibility:
  • Service Container: Broadway components register as Laravel services via nWidart/Laravel-broadway.
  • Middleware: Custom middleware can dispatch commands from HTTP requests (e.g., HandleCommandMiddleware).
  • Routing: API routes can resolve to command handlers (e.g., Route::post('/orders', OrderCommandHandler::class)).
• Database:
  • Event Store: Use broadway/event-store-dbal with Laravel’s database connection.
  • Read Models: Store projections in Eloquent models or dedicated databases (e.g., MongoDB).
• Queues:
  • Projection Jobs: Use Laravel Queues to process events asynchronously (e.g., ProjectReadModelJob).
  • Command Processing: Dispatch commands to queues for background execution.

Migration Path

1. Phase 1: Proof of Concept
   • Implement a single aggregate (e.g., Order) with:
     • Command handlers (e.g., CreateOrderCommand).
     • Event store (DBAL-backed).
     • In-memory read model for testing.
   • Validate with scenario tests.
2. Phase 2: Core Integration
   • Replace Laravel’s request handling with Broadway’s CommandBus for critical paths.
   • Add read model projections (e.g., Elasticsearch for search).
   • Implement snapshotting for performance-critical aggregates.
3. Phase 3: Full Adoption
   • Migrate remaining endpoints to command handlers.
   • Replace Eloquent models with Broadway aggregates where applicable.
   • Set up monitoring for event store performance.

Compatibility

• Laravel Features:
  • Eloquent: Can coexist with Broadway (e.g., read models stored in Eloquent).
  • Validation: Use Laravel’s validator in command handlers.
  • Authentication: Integrate with Laravel’s auth (e.g., resolve user from middleware).
• Third-Party Packages:
  • Laravel Queues: Required for async projections.
  • Scout/Elasticsearch: For read model projections.
  • Laravel Horizon: To monitor projection jobs.

Sequencing

1. Infrastructure Setup:
   • Install broadway/broadway and nwidart/laravel-broadway.
   • Configure event store (DBAL/MongoDB) and read models.
2. Domain Modeling:
   • Define aggregates, commands, and events.
   • Implement command handlers and event listeners.
3. Projection Layer:
   • Set up read models and projection jobs.
   • Test with sample event streams.
4. API Integration:
   • Create middleware to map HTTP requests to commands.
   • Gradually replace controllers with command handlers.
5. Testing:
   • Write scenario tests for aggregates.
   • Test read model projections.

Operational Impact

Maintenance

• Component Updates:
  • Broadway’s loose coupling reduces ripple effects, but breaking changes (e.g., v2.0’s PHP 7 requirement) may require refactoring.
  • Dependency Management: Track broadway/event-store-dbal, broadway/read-model-elasticsearch, etc., separately.
• Schema Management:
  • Event store schemas may evolve (e.g., adding metadata). Use migrations for DBAL stores.
  • Read models require projection updates when event formats change.
• Logging/Monitoring:
  • Add auditing (via CommandLogger) for command success/failure tracking.
  • Monitor event store latency and projection job failures.

Support

• Debugging Complexity:
  • Event Replay: Debugging requires replaying events to a known state (use EventStoreTest helpers).
  • Projection Issues: Failed projections may silently corrupt read models (implement health checks).
• Community Resources:
  • Limited Activity: Low GitHub stars (0) and dependents (0) suggest community support may be minimal.
  • Documentation: Comprehensive but outdated examples (e.g., Symfony 3 references).
• Laravel-Specific Issues:
  • Error Handling: Customize EventDispatchingCommandBus to integrate with Laravel’s exception handling.
  • Caching: Clear caches when event store schemas change.

Scaling

• Event Store:
  • DBAL Backend: Scales vertically; consider partitioning for high throughput.
  • MongoDB Backend: Better for horizontal scaling but may require sharding.
• Read Models:
  • Projection Performance: Batch events to avoid overwhelming read models.
  • Caching: Cache read models (e.g., Redis) to reduce database load.
• Command Processing:
  • Queue Saturation: Use Laravel Queues with retries for failed commands.
  • Concurrency: Broadway’s Processor component can handle parallel command processing.

Failure Modes

Ramp-Up

• Onboarding:
  • Workshops: Dedicate time for team training on **CQ