Http Server Middleware Laravel Package

Getting Started

This package provides only the MiddlewareInterface (PSR-15) definition—no implementation, no runtime logic. Start here if you’re building or integrating middleware into a PSR-15-compliant HTTP server (e.g., Expressive/Laminas, Symfony with middleware bridge, custom stack). First step: require it via Composer to get the interface:

composer require psr/http-server-middleware

Then implement the interface in your middleware classes:

use Psr\Http\Server\MiddlewareInterface;
use Psr\Http\Server\RequestHandlerInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Message\ResponseInterface;

class ExampleMiddleware implements MiddlewareInterface
{
    public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
    {
        // Pre-processing (e.g., logging, auth check)
        $response = $handler->handle($request);
        // Post-processing (e.g., add headers, modify body)
        return $response->withHeader('X-Processed-By', 'ExampleMiddleware');
    }
}

Most modern frameworks (Laravel via laravel/framework + middleware adapter, Symfony with symfony/http-kernel + middleware bridge, Laminas Expressive) already consume this interface indirectly.

Implementation Patterns

• Framework Integration: In non-native PSR-15 frameworks (e.g., Laravel), wrap this interface in adapter classes. Laravel internally uses its own Middleware contract, but adapters like laravel/framework's Pipeline or third-party bridges (eloquent/php-psr15-bridge) can translate between them.
• Middleware Chaining: Implement reusable middleware—e.g., AuthenticationMiddleware, RateLimitingMiddleware, LocaleMiddleware—all conforming to MiddlewareInterface. Chaining is handled by the framework’s request handler stack, not this package.
• Delegation Pattern: Use RequestHandlerInterface to delegate processing cleanly. In tests, mock handlers to isolate middleware logic.
• PSR-7/17 Compatibility: Always type-hint against PSR-7 (messages) and PSR-17 (factories) interfaces. Ensure your middleware is compatible with both psr/http-message 1.x and 2.x (1.0.2 added 2.x support).
• Testing: Write unit tests for each middleware independently by mocking both the request and the next handler, verifying side effects and response transformation.

Gotchas and Tips

• Not a Standalone Stack: This package does not run middleware—you need a framework or router (e.g., relax/psr15-middleware, Nyholm/psr7, php-http/discovery, or a full framework) that consumes the interface.
• Empty Dependents Hint: The "0 dependents" on Packagist is misleading—frameworks like Laravel, Symfony, and Slim adopt it indirectly (they implement PSR-15 in their own packages). Look for psr/http-server-middleware-implementation providers on Packagist for actual implementations.
• Version 1.0.2+ is Minimalist: The interface has been stable since PSR-15 finalization. Avoid pinning to older forks; stick to the official PSR-FIG release.
• Framework Caveats:
  • In Laravel: Register middleware in app/Http/Kernel.php, but note Laravel uses its own abstraction—PSR-15 is only used internally via adapter layers or if you explicitly integrate it.
  • In Symfony: Use the symfony/psr-http-message-bridge to convert Symfony Request/Response to PSR-7 and feed into a PSR-15 middleware stack.
• Testing Tip: Use phpspec or phpunit mocks for RequestHandlerInterface. A common anti-pattern is calling $handler->handle() more than once; assert exactly once to avoid bugs.
• Extending Gracefully: If you need non-PSR context (e.g., database connection), inject dependencies via constructor—not via static globals or container lookups in process(). Keep middleware pure and testable.