Laminas Httphandlerrunner Laravel Package

Technical Evaluation

Architecture Fit

• PSR-15 Compliance: Remains a natural fit for Laravel’s middleware stack (PSR-15 is core to Laravel’s HTTP layer since v8+). The package’s adherence to PSR-15 ensures seamless integration with Laravel’s Pipelines and Route Resolvers, enabling modular request handling.
• Decoupling: Continues to be ideal for microservices or API-first architectures, where request handlers are decoupled from framework-specific logic (e.g., replacing Laravel’s Route::get() with a RequestHandler instance).
• Middleware Integration: Can still be used to wrap Laravel middleware or inject custom PSR-15 handlers into the pipeline, enabling finer-grained control over request/response cycles.
• Server Push/Edge Use Cases: Useful for serverless (e.g., AWS Lambda, Bref) or edge computing (e.g., Cloudflare Workers), where PSR-15 handlers are already a standard.

Integration Feasibility

• Laravel Native Support: Laravel’s Http\Kernel and Pipeline classes continue to support PSR-15, ensuring low-effort integration (e.g., replacing Closure-based routes with RequestHandler instances).
• Existing Ecosystem: Works with:
  • Laravel’s middleware (convertible to PSR-15 middleware via Laminas\Stratigility).
  • API resources (e.g., encapsulate JsonResource logic within a RequestHandler).
  • Event-driven architectures (e.g., handle requests asynchronously).
• Database/ORM Agnostic: No direct coupling to Laravel’s Eloquent or database layer, but can be used alongside it for DDD-style request handling.

Technical Risk

• Learning Curve: Developers unfamiliar with PSR-15 may still require training, though Laravel’s middleware system abstracts much of this.
• Performance Overhead: Minimal, but double-dispatch (PSR-15 + Laravel’s middleware) could add negligible latency. Benchmark if critical.
• Dependency Bloat: Adds laminas/laminas-httphandlerrunner (~1MB) and optionally laminas/stratigility for middleware conversion. Justify with use case.
• Route Caching: Laravel’s route caching may need adjustment if using dynamic RequestHandler instances (e.g., dependency-injected handlers).
• Testing Complexity: PSR-15 handlers encourage unit-testing over integration tests, which may require refactoring existing test suites.
• PHP 8.5 Compatibility: New – The package now supports PHP 8.5, which may require updating Laravel’s PHP version (if not already on 8.5+). This could necessitate dependency updates (e.g., Laravel 11+) or testing for compatibility with existing PHP 8.1/8.2 codebases.

Key Questions

1. Why PSR-15? What problem does this solve that Laravel’s existing middleware/route system doesn’t?
   • Example: Need asynchronous request handling, framework-agnostic middleware, or serverless compatibility.
2. Migration Strategy: Will this replace existing routes/middleware incrementally, or as a full rewrite?
3. Handler Lifecycle: How will RequestHandler instances be instantiated (e.g., via Laravel’s IoC container, manual DI)?
4. Error Handling: How will exceptions from PSR-15 handlers integrate with Laravel’s error handling (e.g., App\Exceptions\Handler)?
5. Performance Impact: Will this be used in high-throughput scenarios (e.g., API gateways)? If so, benchmark against current middleware.
6. Tooling Support: Does the team have experience with PSR-15 tools (e.g., php-http/middleware-serializer)?
7. Long-Term Maintenance: Who will own the PSR-15 handler layer? Will it require additional documentation or training?
8. PHP Version Upgrade: Given PHP 8.5 support, does the team need to upgrade Laravel (e.g., to Laravel 11+) or test compatibility with existing PHP 8.1/8.2 codebases?

Integration Approach

Stack Fit

• Laravel Core: Directly compatible with:
  • Routing: Replace Route::get(..., fn() => ...) with Route::get(..., new MyHandler()).
  • Middleware: Convert Laravel middleware to PSR-15 via Laminas\Stratigility\MiddlewarePipe.
  • API Resources: Use RequestHandler to encapsulate JsonResource logic.
• Serverless: Ideal for Bref (AWS Lambda) or Vapor, where PSR-15 is the standard.
• Edge Computing: Works with Cloudflare Workers or Fly.io for low-latency request handling.
• Microservices: Enables framework-agnostic request handlers shared across Laravel and other PHP frameworks.

Migration Path

1. Incremental Adoption:
   • Start with non-critical routes (e.g., admin endpoints).
   • Replace Closure-based routes with RequestHandler instances.
   • Example:

     // Before
     Route::get('/api/data', fn() => DataController::fetch());
     
     // After
     Route::get('/api/data', new DataHandler());
     

2. Middleware Conversion:
   • Use Laminas\Stratigility to wrap Laravel middleware:

     $middleware = new Laminas\Stratigility\MiddlewarePipe();
     $middleware->pipe(new AuthMiddleware());
     $middleware->pipe(new LogMiddleware());
     Route::get('/protected', $middleware);
     

3. API Layer Refactor:
   • Replace JsonResource logic with RequestHandler for cleaner separation.
   • Example:

     class UserHandler implements RequestHandlerInterface {
         public function __invoke(ServerRequestInterface $request): ResponseInterface {
             $user = User::find($request->getAttribute('id'));
             return new JsonResponse(['data' => $user]);
         }
     }
     

4. Serverless Deployment:
   • For Bref/Vapor, ensure RequestHandler is the entry point (Bref already supports PSR-15).
5. PHP Version Upgrade (New):
   • If leveraging PHP 8.5 features, upgrade Laravel (e.g., to Laravel 11+) and test for compatibility.

Compatibility

• Laravel Versions: Works with Laravel 8+ (PSR-15 support). For Laravel 7, use a PSR-15 bridge (e.g., laminas/laminas-diactoros).
• PHP Versions: Now requires PHP 8.1+ (with explicit support for PHP 8.5). Laravel 9+ recommended for full compatibility.
• Dependencies:
  • Requires psr/http-message (already in Laravel).
  • Optional: laminas/stratigility for middleware conversion.
• Database/Queue: No direct impact, but handlers can integrate with Laravel’s queues (e.g., async processing).

Sequencing

1. Phase 1: Proof of Concept
   • Implement 1-2 routes with RequestHandler.
   • Test with Laravel’s built-in server (php artisan serve).
2. Phase 2: Middleware Integration
   • Convert critical middleware to PSR-15.
   • Test with API load testing (e.g., Laravel Dusk + HTTP client).
3. Phase 3: Full Adoption
   • Migrate all routes to RequestHandler.
   • Update CI/CD to validate PSR-15 compliance (e.g., static analysis).
4. Phase 4: Serverless/Edge
   • Deploy to Bref/Vapor or Cloudflare Workers.
   • Optimize for cold starts (if applicable).
5. Phase 5: PHP 8.5 Upgrade (New)
   • If targeting PHP 8.5 features, upgrade Laravel and test thoroughly.

Operational Impact

Maintenance

• Pros:
  • Decoupled Logic: Easier to swap implementations (e.g., replace a handler without touching routes).
  • Testability: PSR-15 handlers are unit-testable by design (no reliance on Laravel’s Request facade).
  • Reusability: Handlers can be shared across projects or microservices.
• Cons:
  • Additional Abstraction: May require more boilerplate for simple routes.
  • Dependency Management: Need to track laminas/laminas-httphandlerrunner updates.
  • Debugging: Stack traces may be less intuitive if mixing PSR-15 and Laravel middleware.
  • PHP 8.5 Dependency: Upgrading to PHP 8.5 may introduce new compatibility risks (e