Http Message Laravel Package

Getting Started

Install via Composer:

composer require httpsoft/http-message

This package provides pure PSR-7 implementations, so first tasks are straightforward:

1. Import classes in your code: use HttpSoft\Message\{Request, Response, ServerRequest, Stream, URI};
2. Start with ServerRequest for typical web middleware handling (e.g., inspecting incoming requests):

$serverRequest = new ServerRequest($_SERVER, $_GET, $_POST, $_COOKIE, $_FILES);
$requestUri = $serverRequest->getUri(); // Returns a `URI` instance
$method = $serverRequest->getMethod();

3. For outgoing responses:

$response = (new Response())
    ->withStatus(200)
    ->withHeader('Content-Type', 'text/plain')
    ->withBody(new Stream('php://memory', 'r+'))
    ->getBody()->write('Hello world');

Use the README and src as your primary reference—no heavy docs needed.

Implementation Patterns

• Immutable Chaining: Always treat messages as immutable—every with*() method returns a new object. Chain safely:

$request = $request
    ->withHeader('X-Request-ID', $id)
    ->withQueryParams([...$params, 'page' => $page]);

• Stream Efficiency: For large bodies (e.g., file uploads or streaming responses), use php://temp or fopen() streams:

$body = new Stream(fopen('/tmp/data.csv', 'r'));
$response = (new Response())->withBody($body);

• Middleware Integration: Works seamlessly with PSR-15/PSR-12 middleware stacks:

$serverRequest = $requestHandler->handle(new ServerRequest($_SERVER, $_GET));
// Then: return $response->withHeader('X-Cache', 'HIT');

• URI Manipulation: Build/modify URIs without parsing strings:

$uri = (new URI('https://example.com/api'))
    ->withPath('/users')
    ->withQuery('limit=10');

• Factory Helpers: While not included, integrate with httpsoft/http-server-request-factory for clean PSR-17 request creation.

Gotchas and Tips

• Strict Immutability: Forgetting to reassign ($req = $req->with...) is the #1 mistake. Linters like PHPStan with immutable rules help.
• Stream Reusability: Reusing a Stream instance across multiple messages is allowed per PSR-7—but ensure rewind() if reused for reading. php://memory is stateful.
• Header Normalization: Headers like Content-Type use case-insensitive keys internally, but getHeaderLine('content-type') and getHeaderLine('Content-Type') both work. Stick to canonical casing (Content-Type) for clarity.
• Body Length: Always set Content-Length manually if streaming (e.g., files) unless your HTTP server/client handles chunked encoding. Stream::getSize() may return null for non-seekable streams—don’t rely blindly.
• URI Path Encoding: Paths are not automatically URL-encoded. Use withPath(rawurlencode($path)) or rely on withPath() + Uri::getPath()’s decoding.
• Extension Point: Extend Stream for custom behavior (e.g., throttled reads), but avoid overriding immutable with*() methods—just delegate or wrap.
• Compatibility: Works with Symfony Panther, Guzzle, Nyholm/PSR7, etc. No need to convert—instanceof Psr\Http\Message\RequestInterface is enough to swap implementations.