Psr7 Laravel Package

Getting Started

Install with composer require nyholm/psr7. This is the minimal, strict PSR-7 implementation—no extra helpers, no fluff. Begin by instantiating Nyholm\Psr7\Factory\Psr17Factory, the sole entrypoint for creating PSR-7 objects. For common use cases like server requests, pair it with nyholm/psr7-server to build ServerRequest from superglobals ($_GET, $_POST, etc.). To emit responses, use any PSR-15/17/18-compatible emitter (e.g., laminas/laminas-httphandlerrunner). It’s compatible with Symfony Flex (auto-registers factories as services).

Implementation Patterns

• Factory-first workflow: Always construct objects via Psr17Factory (e.g., createRequest(), createStream(), createResponse()). Avoid direct instantiation—PSR-7 requires immutable objects, and the factory ensures correct compliance.
• Request/response chain: Build immutable flows: $request = $factory->createRequest(...)->withHeader(...)->withBody(...). Prefer method chaining over modification.
• PSR-18 client integration: Use Psr17Factory with any PSR-18 client (e.g., guzzlehttp/guzzle, curl, or buzz). Example: $client->sendRequest($factory->createRequest('POST', $url)->withBody($factory->createStream($json))).
• Server-side bridging: Use nyholm/psr7-server’s ServerRequestCreator::fromGlobals() to convert PHP superglobals into PSR-7 ServerRequest for middleware or framework integration.
• Testing patterns: Avoid mocking PSR-7 classes—treat them as value objects. For unit tests, compose behavior via decorators or implement interfaces directly if extension is unavoidable.

Gotchas and Tips

• No helpers: This package contains only PSR-7/17-compliant classes. No json(), toDto(), or convenience methods—roll your own helpers if needed.
• Mutable misuse: PSR-7 methods (e.g., withHeader()) return new instances—never mutate in-place. Accidentally ignoring return values is a common bug.
• Headers: Always use arrays for header values (even single-value headers). Nyholm enforces strict header value types per PSR-7.
• Stream pitfalls: Stream::getContents() throws exceptions on non-seekable resources (fixed in 1.8.1); avoid calling __toString() on large streams (use fopen('php://memory') for large data).
• ServerRequest body: getParsedBody() is populated on creation only for application/x-www-form-urlencoded and multipart/form-data; raw bodies require manual parsing via getContents().
• PHP 8+ compatibility: All changes in 1.6+ and 1.8.2 address PHP 8+ strictness (e.g., ValueError, nullability). Use Psr17Factory—HttplugFactory is deprecated (removed in next major).
• Security: Upgrade immediately if using versions prior to 1.6.1—CVE-2023-29197 affected header validation.
• Extension: Never extend classes. Use composition (decorator pattern) or implement PSR interfaces from scratch if customization is essential—@final signals intentional immutability.