Zend Stratigility Laravel Package

Getting Started

Start by installing zendframework/zend-stratigility via Composer (note: package is archived; consider migrating to middlewares/utils or nyholm/psr7-server for newer projects). For initial use, instantiate a Server or MiddlewarePipe, attach middleware callables or classes implementing Interop\Http\ServerMiddleware\MiddlewareInterface, and dispatch with process().

First use case: build a minimal microservice handling JSON API requests. Create a basic pipeline: authentication → routing → controller → final handler for error responses. Use MiddlewarePipe::pipe($path, $middleware) to scope middleware to URL prefixes.

Look first at the MiddlewarePipe class and Server class in the Zend\Stratigility namespace—these form the core pipeline surface. Check src/Http/ServerRequest.php and src/Utils.php for helpers like prepareResponse() and prepareRequest(). The test/ directory contains useful examples (e.g., test/Asset/Middleware/Foo.php).

Implementation Patterns

• Pipeline Composition: Layer middleware in order: logging → auth → routing → CORS → controller → fallback. Use pipe('/api', $apiMiddleware) for prefix-scoped routes.
• Middleware Reusability: Write middleware as invokable classes with __invoke(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface. Avoid direct access to globals—inject dependencies via constructor.
• Route-Driven Handlers: Use PathMiddlewareDecorator to wrap middleware so it only executes if the path matches (e.g., for /admin).
• Error Handling: Catch exceptions in middleware, or register a final handler via pipe(null, $finalHandler) or setDispatch($finalHandler) to return consistent error responses (e.g., 500 with JSON).
• Integration: Pair with php-http/discovery + guzzlehttp/psr7 or nyholm/psr7 for PSR-7 support. Use MiddlewarePipe::pipe() instead of Next::handle() to avoid tight coupling to Next (deprecated in newer forks).

Gotchas and Tips

• Archived Package: zendframework/zend-stratigility is unmaintained. Prefer middlewares/utils (its spiritual successor) or nyholm/psr7-server + a modern router (e.g., symfony/routing).
• Path Matching Quirks: Path-based pipe() matching is prefix-based, not exact. pipe('/api', $m) matches /api, /api/users, /api/123, but not /api with trailing slash unless normalized.
• Middleware Order Matters: Early middleware see incoming request; late middleware see mutated responses. Always call $handler->handle($request) unless short-circuiting (e.g., auth rejection).
• Request/Response Mutability: PSR-7 objects are immutable. Ensure you return a new response from middleware (e.g., $response = $response->withStatus(401))—otherwise changes won’t propagate.
• Error Handling Hook: Exception thrown in middleware won’t automatically reach final handler unless setDispatch() is used or custom error middleware catches it. Use pipe(null, new ErrorMiddleware()) as last resort.
• Testing Tip: Middleware is easily unit-tested by mocking ServerRequestInterface and RequestHandlerInterface, asserting on handle() arguments and returned response. Use MiddlewarePipe::process() for integration tests.