Http Server Handler Laravel Package

Getting Started

This package provides only the Psr\Http\Server\RequestHandlerInterface—a tiny, framework-agnostic contract for HTTP request handlers defined in PSR-15. You’ll rarely install it directly; instead, it’s a transitive dependency of middleware-capable frameworks or libraries (e.g., Slim, Laminas Stratigility, Nyholm/psr7-server, or your own stack). To start using it:

1. Install a PSR-15 implementation (e.g., laminas/laminas-stratigility, nyholm/psr7-server, or php-http/discovery).
2. Implement the interface in your handlers:

   use Psr\Http\Server\RequestHandlerInterface;
   use Psr\Http\Message\ServerRequestInterface;
   use Psr\Http\Message\ResponseInterface;
   
   class ApiHandler implements RequestHandlerInterface {
       public function handle(ServerRequestInterface $request): ResponseInterface {
           // Handle request, return response
       }
   }
   

First real-world use: Write a handler for your router or middleware stack, then register it as a delegate.

Implementation Patterns

• Middleware delegation: Inject RequestHandlerInterface into middleware as $next to chain the stack:

  public function __invoke(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface {
      $response = $handler->handle($request);
      return $response->withHeader('X-Powered-By', 'MyApp');
  }
  

• Route-to-handler mapping: Use routers (e.g., FastRoute, Aura.Router) that output RequestHandlerInterface objects as handlers—ideal for PSR-15–compliant dispatch.
• Handler delegation patterns: Leverage DelegateHandler wrappers (e.g., in Stratigility) or custom delegation to apply cross-cutting concerns (auth, logging, rate limiting).
• Polyfill pattern: Wrap legacy callables/controllers ([$controller, 'index']) in a handler adapter:

  class CallableHandler implements RequestHandlerInterface {
      public function __construct(private callable $callable) {}
      public function handle(ServerRequestInterface $request): ResponseInterface {
          return ($this->callable)($request);
      }
  }
  

Gotchas and Tips

• No runtime code: This package is pure interface. No functionality is shipped—debug middleware chains by checking concrete handler types (e.g., get_class($next)).
• PSR-7/PSR-17 version conflicts: Ensure your HTTP message implementation (e.g., guzzlehttp/psr7, nyholm/psr7) is compatible with psr/http-message:^1.0||^2.0. Explicitly pin versions if using PHP 8.0+ with typed return types.
• Laravel/Symfony users: These frameworks internally implement this interface but don’t expose it directly in app code—you can type-hint it for compatibility with PSR-15 middleware, but avoid relying on it unless building reusable packages.
• Dependency hygiene: Avoid installing psr/http-server-handler manually. Its presence may conflict if your framework pins a specific PSR version (e.g., nyholm/psr7-server locks psr/http-message:^1.0). Let composers resolve it transitively.
• Testing tip: Mock RequestHandlerInterface in middleware unit tests using getMockBuilder()->disableOriginalConstructor()->getMockForAbstractInterface() to avoid HTTP message dependencies.