Zend Psr7Bridge Laravel Package

Getting Started

Start by installing the package via Composer:

composer require zendframework/zend-psr7bridge

This package is not meant to be used directly in application code — it serves as an integration layer. Its primary use case is converting between Zend Framework’s Zend\Stdlib\Request/Response objects and PSR-7 implementations (e.g., GuzzleHttp\Psr7). Begin by identifying where Zend and PSR-7 boundaries exist in your stack — e.g., in middleware adapters or legacy Bootstrap code.

First use case: Wrapping PSR-7 requests/responses for legacy Zend Framework 2 controllers that expect Zend\Http\Request/Response.

Implementation Patterns

• Middleware Adapters: Convert incoming PSR-7 requests (e.g., from a Slim or Expressive-compatible server) into Zend\Http\Request for routing/handling by legacyZF2 controllers. Use Bridge\Factory ZendPsr7BridgeFactory or directly call Zend\Psr7Bridge\Psr7Bridge::convertRequest() / convertResponse().

• Gradual Migration: When modernizing to PSR-7, keep core logic unchanged and inject bridges at entry points (e.g., in public/index.php). Convert $_SERVER, $_GET, $_POST, etc. → Zend\Http\PhpEnvironment\Request → PSR-7 for middleware pipelines (Laminas Stratigility, Nyholm/PSR7).

• Stream & Header Syncing: When returning Zend\Http\Response, use Psr7ResponseFactory to sync body streams, headers, cookies, and status codes to PSR-7 cleanly — avoiding double encoding or header mangling.

• Testing: Use bridges in integration tests to simulate PSR-7 incoming requests while testing legacy Zend-based controller actions.

Gotchas and Tips

• ⚠️ Deprecation: This package is archived (as of 2018) and unlikely to receive updates. Consider migrating to laminas/laminas-psr7bridge if on Laminas, or use modern PSR-7-first middleware frameworks (e.g., Nyholm/psr7, Slim, Mezzio).

• Header Case Sensitivity: Zend headers are case-insensitive; PSR-7 headers are case-insensitive per spec but implementations vary. Test cookie/header normalization carefully — especially Set-Cookie (often duplicated or mis-sorted).

• Stream Offset Issues: Zend\Stdlib\Stream doesn’t support all stream_wrapper features expected by PSR-7 (e.g., seek() to negative offsets). Convert streams using Psr7StreamBridge::toPsr7() before manipulation.

• No PSR-17 Support: The bridge predates PSR-17 (HTTP Factories), so it cannot be used with modern factory-based setups (e.g., Symfony’s HttpFoundationBridge + PSR-17). Prefer direct Psr7 message creation unless you need Bidirectional conversion.

• Extension Points: Override Zend\Psr7Bridge\Converter methods for custom cookie or URI handling (e.g., URL encoding quirks, subdomain cookie scoping). Use BridgeFactory::setConverter() in custom application bootstrap.