Cqs Routing Laravel Package

Technical Evaluation

Architecture Fit

• CQS (Command Query Separation) Alignment: The package enforces CQS principles, which aligns well with Laravel’s service-layer architecture (e.g., separating Command/Query handlers from controllers). However, Laravel’s native routing is controller-centric, requiring a paradigm shift in request handling.
• Symfony Dependency: Built for Symfony, but leverages PSR-15 middleware and PSR-11 containers, making it adaptable to Laravel via Symfony’s Bridge or Laravel’s DI container.
• DTO-First Approach: Encourages strong typing via Data Transfer Objects (DTOs), which can improve maintainability but may introduce boilerplate if Laravel’s existing request validation (e.g., Form Requests) is already in use.

Integration Feasibility

• Middleware Integration: The package uses PSR-15 middleware to decode requests into DTOs and dispatch commands/queries. Laravel’s middleware stack can accommodate this, but custom middleware must be written to bridge Symfony’s RequestHandler with Laravel’s Illuminate\Http\Request.
• Routing Override: Requires replacing Laravel’s route resolution with the package’s CqsRouter. This is highly invasive and may conflict with Laravel’s route caching (php artisan route:cache).
• Handler Resolution: Laravel’s service container can register command/query handlers, but the package’s handler resolution (via HandlerLocator) may need custom binding logic to work with Laravel’s bind() or tag() methods.

Technical Risk

• Breaking Changes: Laravel’s request lifecycle (e.g., Illuminate\Foundation\Http\Kernel) differs from Symfony’s. Request decoding (e.g., JSON → DTO) may clash with Laravel’s built-in request parsing.
• Performance Overhead: DTO construction and validation add latency compared to Laravel’s native request handling. Benchmarking is critical for high-traffic APIs.
• Testing Complexity: The package introduces new abstractions (e.g., RequestDecoder, ResponseConstructor), requiring updated unit/integration tests for existing routes.
• Symfony-Specific Assumptions: Some components (e.g., AccessValidator) may rely on Symfony’s security system, needing Laravel alternatives (e.g., Gates/Policies).

Key Questions

1. Why CQS? Does the team need strict separation of reads/writes, or is Laravel’s repository pattern sufficient?
2. Migration Scope: Should this be incremental (e.g., opt-in for new routes) or big-bang (full rewrite)?
3. Validation Strategy: How will DTO validation integrate with Laravel’s existing validation (e.g., Form Requests, API Resources)?
4. Error Handling: How will command/query failures map to Laravel’s exception handling (e.g., App\Exceptions\Handler)?
5. Performance Trade-offs: Are the benefits of CQS (e.g., testability) worth the runtime cost of DTOs?
6. Long-Term Maintenance: Who will support this hybrid Symfony/Laravel stack if issues arise?

Integration Approach

Stack Fit

• Laravel Compatibility:
  • Pros:
    • PSR-15 middleware can be wrapped in Laravel middleware.
    • Laravel’s service container supports PSR-11, allowing dependency injection.
    • DTOs can integrate with Laravel’s API Resources or Form Requests.
  • Cons:
    • No native Laravel support: Requires custom adapters (e.g., LaravelRequestDecoder, LaravelResponseConstructor).
    • Routing system conflict: Laravel’s Router must be extended or replaced.
• Recommended Stack:
  • Laravel 10+ (PHP 8.4/8.5 support).
  • Symfony Bridge (symfony/http-foundation, symfony/dependency-injection) for compatibility.
  • Laravel Octane (if using Symfony’s HttpKernel for performance).

Migration Path

1. Phase 1: Proof of Concept (PoC)
   • Implement one CQS route (e.g., /api/commands/create-user) alongside existing Laravel routes.
   • Compare development speed and performance with traditional Laravel handlers.
2. Phase 2: Incremental Adoption
   • New features use CQS; legacy routes remain unchanged.
   • Use feature flags to toggle between old/new routing.
3. Phase 3: Full Migration
   • Replace Laravel controllers with CQS handlers.
   • Update tests to use the new structure.
   • Deprecate old route resolution in favor of CqsRouter.

Compatibility

• Laravel-Specific Conflicts:
  • Route Caching: The package’s router may bypass Laravel’s cached routes. Solution: Disable caching or extend RouteCollection.
  • Middleware Order: CQS middleware must be placed before Laravel’s global middleware (e.g., TrimStrings, ConvertEmptyStringsToNull).
  • Request Parsing: Laravel’s Request class may interfere with DTO decoding. Solution: Use Symfony\Component\HttpFoundation\Request as a base.
• Symfony Dependencies:
  • Serializer: If using SerializerJsonResponseConstructor, ensure Symfony’s Serializer is installed (symfony/serializer).
  • Validator: Replace AccessValidator with Laravel’s Gates/Policies or a custom validator.

Sequencing

1. Setup Dependencies

   composer require digital-craftsman/cqs-routing symfony/http-foundation symfony/dependency-injection
   

2. Configure Laravel
   • Publish the package’s config (php artisan vendor:publish --provider="DigitalCraftsman\CQSRouting\CqsRoutingServiceProvider").
   • Extend Laravel’s AppServiceProvider to bind CQS components:

     $this->app->bind(\DigitalCraftsman\CQSRouting\RequestDecoder\RequestDecoderInterface::class, \App\CQSRouting\LaravelRequestDecoder::class);
     

3. Implement Custom Adapters
   • Create LaravelRequestDecoder, LaravelResponseConstructor, etc.
4. Register CQS Router
   • Override Laravel’s bootstrap/app.php to use CqsRouter:

     $app->router->setRouter(new \DigitalCraftsman\CQSRouting\CqsRouter($app->make(\DigitalCraftsman\CQSRouting\RequestHandlerInterface::class)));
     

5. Define Routes
   • Use annotations or YAML/XML (Symfony-style) to define CQS routes:

     # config/cqs_routes.yaml
     commands:
       App\Application\Commands\CreateUserCommand:
         path: /api/users
         methods: [POST]
         decoder: App\CQSRouting\DTO\CreateUserRequestDTO
     

Operational Impact

Maintenance

• Pros:
  • Reduced Boilerplate: DTOs enforce consistent request/response shapes.
  • Improved Testability: Commands/queries are easier to mock than controller methods.
• Cons:
  • New Abstraction Layer: Debugging DTO validation errors or handler resolution may require familiarity with Symfony’s ecosystem.
  • Vendor Lock-in: The package is Symfony-centric; future Laravel changes (e.g., route system overhaul) may break compatibility.
• Mitigation:
  • Document custom adapters (e.g., LaravelRequestDecoder).
  • Monitor dependency updates (e.g., Symfony Bridge versions).

Support

• Learning Curve:
  • Developers must learn CQS patterns, DTO design, and Symfony’s middleware.
  • Ops may struggle with new error formats (e.g., command validation failures).
• Tooling Gaps:
  • Laravel Debugbar may not display CQS-specific data (e.g., DTO payloads). Solution: Extend Debugbar or use custom logging.
  • No IDE Support: Symfony’s annotations may not integrate seamlessly with Laravel’s IDE helpers (e.g., PHPStorm route hints).
• Support Plan:
  • Training: Conduct a workshop on CQS and the package’s architecture.
  • Runbooks: Document common failure modes (e.g., "DTO validation failed").

Scaling

• Performance:
  • DTO Construction: Adding validation and serialization may increase latency for high-throughput APIs.
  • Middleware Overhead: Each CQS route adds ~2-3 middleware layers (decoder, validator,