Click the Castor logo or press Ctrl Alt T to change theme.
# Responses An HTTP response is the message a server sends back to a client. It contains a protocol version, a status line, headers, and an optional body. The `Response` class captures these components as a readonly value object. ## Creating responses The `create` factory builds a response with sensible defaults: ```php <?php use Castor\Net\Http\Response; use Castor\Net\Http\Status\Code; $response = Response::create(Code::OK); ``` This gives you an HTTP/1.1 response with a 200 status, empty headers, and a `NoBody` body. You can pass an integer instead of a `Code` enum case: ```php $response = Response::create(201); ``` The factory resolves the reason phrase automatically — `"Created"` in this case. ### Responses with content Pass a body and headers to `create` for richer responses: ```php <?php use Castor\Net\Http\Response; use Castor\Net\Http\Headers; use Castor\Net\Http\Status\Code; use Castor\Io\Stream; $headers = new Headers(); $headers->set('Content-Type', 'application/json'); $body = Stream\Buffer::with('{"users": []}'); $response = Response::create(Code::OK, $body, $headers); ``` ## Accessing response components Like `Request`, every component is a public readonly property: ```php $response->version; // Version instance $response->status; // Status instance $response->headers; // Headers instance $response->body; // Reader & Closer instance ``` ### Inspecting the status The `Status` object carries both the numeric code and the reason phrase: ```php $response->status->code; // 200 $response->status->phrase; // "OK" ``` It also provides semantic helpers: ```php $response->status->isSuccess(); // true for 2xx $response->status->isRedirect(); // true for 3xx $response->status->isClientError(); // true for 4xx $response->status->isServerError(); // true for 5xx $response->status->inRange(200, 299); // custom range check ``` ## Copying responses Responses are readonly, so you create modified copies with `copyWith`: ```php $notFound = $response->copyWith( status: Status::fromCode(Code::NotFound), ); ``` The `version` parameter accepts either a `Version` instance or a string like `"HTTP/2.0"`: ```php $http2 = $response->copyWith(version: 'HTTP/2.0'); ``` ## Writing responses to a stream `Response` implements `Castor\Io\WriterTo`, so you can serialize a complete HTTP response — status line, headers, and body — to any `Writer`: ```php <?php use Castor\Io\Stream; $buffer = Stream\Buffer::empty(); $response->writeTo($buffer); echo $buffer; // "HTTP/1.1 200 OK\nContent-Type: application/json\n\n{\"users\": []}" ``` The output follows the HTTP wire format: the status line, each header on its own line, a blank line separator, and then the body. This is useful for logging, debugging, or building custom HTTP transports. ## Responses vs. ResponseWriter The `Response` class represents a complete response as a value. In server-side code, you typically write responses incrementally using a `ResponseWriter` instead. The [response writer](response-writer.html) page covers that pattern in detail. The `ResponseWriter\Recorder` bridges the two worlds: it implements `ResponseWriter` for testing and can produce a `Response` object after the handler finishes. See the [response writer](response-writer.html) documentation for an example.
Castor ecosystem