Http Laravel Package

Getting Started

Start by installing via Composer: composer require spiral/http. The core classes (Spiral\Http\Request, Spiral\Http\Response) follow PSR-7/PSR-15 conventions closely, so if you’re familiar with those, the entry point is straightforward. Begin by inspecting Spiral\Http\Request::fromGlobals() to capture current request context, or construct requests/responses manually for testing. The Spiral\Http\Uri and Spiral\Http\Cookie utilities are ideal for parsing or building URIs and cookies programmatically — for example, Uri::fromString('https://example.com/path?foo=bar')->withQuery('foo=baz').

Implementation Patterns

• Middleware Wrapping: Use Request/Response instances as lightweight, immutable wrappers in PSR-15-compatible middleware stacks (e.g., Slim, ReactPHP, or custom dispatchers).
• Request Validation Layer: Wrap external payloads with Request to safely extract and normalize query/body parameters ($request->getParsedBody(), $request->getQueryParams()), avoiding direct $_GET/$_POST usage.
• Testable HTTP Clients: In library code, inject Request/Response abstractions instead of Guzzle/Curl; this makes integration tests trivial with Request::create().
• Header Manipulation: Use Response::withHeader() and withAddedHeader() for centralized header composition (e.g., security headers), leveraging strict type validation on header names/values.
• URI Assembly in API Clients: Combine Uri and Query utilities to build predictable URLs: (new Uri('/api'))->withQuery(http_build_query($params)).

Gotchas and Tips

• No PSR-17 Support: Unlike modern libraries (e.g., Nyholm/psr7), this package lacks factory interfaces — create responses manually via new Response($status, $headers, $body) rather than relying on factory injection.
• Cookie Parsing Quirks: Cookie::parseHeader() handles legacy Set-Cookie syntax, but nested quoting or special characters (e.g., ;, =) in cookie values may break without prior URL encoding. Always double-encode cookie values when setting.
• Immutability Requires Discipline: All Request/Response methods return new instances — forgetting to use the return value ($req = $req->withParsedBody(...)) is a common source of subtle bugs.
• Minimal Body Handling: Only supports string bodies — no streaming, file uploads, or multipart parsing. For large payloads, wrap php://input manually via fopen('php://input', 'r') and pass to custom stream-aware layers.
• Staleness Check: Last release in 2019 — audit for security patches or consider vendorizing critical parts if used in high-risk contexts. Use composer outdated spiral/http to detect drift.