Castor HTTP — castor/http

# Castor HTTP Castor HTTP is a pure, dependency-light implementation of the HTTP protocol data structures for PHP 8.3+. It models requests, responses, headers, cookies, status codes, and handler patterns as clean, strongly-typed objects — without pulling in a PSR-7 implementation or a full framework. ## Install Castor packages are published in the Castor Composer repository, not Packagist. Add the repository first, then require the package: ```bash composer config repositories.castor composer https://castor-labs.github.io/php-packages composer require castor/http ``` ## Quick example ```php <?php use Castor\Net\Http\Request; use Castor\Io; $request = Request::create('GET', 'https://example.com?foo=bar'); $request->uri->getQuery()->lookup('foo'); // "bar" $request->headers->add('Authorization', 'Bearer <token>'); $request->headers->values('authorization'); // ["Bearer <token>"] $request->method->isSafe(); // true $request->method->isIdempotent(); // true ``` Requests, responses, headers, and cookies are first-class objects that map directly to the plain-text HTTP protocol. There are no message interfaces, no stream abstractions on top of streams — just the data that travels over the wire, expressed in PHP. ## Design philosophy Most PHP HTTP libraries either implement PSR-7 or wrap it. Castor HTTP takes a different path: it models the HTTP protocol itself, using modern PHP features like enums, readonly classes, and intersection types. The body of a request or response is a `Castor\Io\Reader & Castor\Io\Closer` — the same streaming I/O abstraction used across the Castor ecosystem. Headers are a mutable collection with case-insensitive canonical keys. Methods and status codes are backed enums with semantic helper methods. This design means you work with HTTP the way the protocol actually works, rather than through an abstraction layer that tries to be everything to everyone. ## What's in the box - **Request** and **Response** — readonly value objects representing HTTP messages. - **Headers** — a mutable, case-insensitive header collection that can write itself in wire format. - **Method** — a backed enum covering all standard HTTP methods with safety and idempotency checks. - **Status** and **Status\Code** — status line representation with a comprehensive code enum. - **Cookie** and **Cookies** — full RFC 6265 cookie parsing and serialization. - **Handler** and **ResponseWriter** — a server-side handler pattern inspired by Go's `net/http`. - **Version** — HTTP protocol version parsing and representation. - **NoBody** — a zero-allocation body for messages without content. - **Error types** — `HandlerError`, `ProtocolError`, and `HeadersAlreadySent` for clear failure signaling. ## Next steps Head to the [getting started](docs/getting-started.html) guide for installation details and your first handler, or dive into the [core concepts](docs/requests.html) to understand how each piece fits together.

Next → Documentation