Click the Castor logo or press Ctrl Alt T to change theme.
# Getting started This guide walks you through installing `castor/http` and using it to build HTTP messages and handle requests. ## Installation Castor packages are published in the Castor Composer repository. Add the repository to your project first: ```json { "repositories": [ { "type": "composer", "url": "https://castor-labs.github.io/php-packages" } ] } ``` Then require the package: ```bash composer require castor/http ``` The package requires PHP 8.3 or later. ## Dependencies Castor HTTP depends on a small set of sibling packages: - **castor/io** — streaming I/O primitives (`Reader`, `Writer`, `Closer`). - **castor/context** — immutable request-scoped value carrier. - **castor/uri** — URI parsing and manipulation. - **castor/functions** — small utility functions used internally. All of these are installed automatically by Composer. ## Creating a request The fastest way to create a request is with the `Request::create` factory: ```php <?php use Castor\Net\Http\Request; $request = Request::create('GET', 'https://api.example.com/users?page=2'); ``` This gives you a `Request` with the `GET` method, the parsed URI, empty headers, an HTTP/1.1 version, and a `NoBody` body. You can then inspect or modify the request: ```php $request->method; // Method::Get $request->uri->getQuery()->lookup('page'); // "2" $request->headers->add('Accept', 'application/json'); ``` ## Creating a response Responses work the same way: ```php <?php use Castor\Net\Http\Response; use Castor\Net\Http\Status\Code; $response = Response::create(Code::OK); $response->status->code; // 200 $response->status->phrase; // "OK" $response->status->isSuccess(); // true ``` You can pass a body and custom headers too: ```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('{"id": 1}'); $response = Response::create(Code::OK, $body, $headers); ``` ## Handling a request Castor HTTP provides a server-side handler pattern. Implement the `Handler` interface or use the `Callback` adapter: ```php <?php use Castor\Context; use Castor\Net\Http\Handler; use Castor\Net\Http\Handler\Callback; use Castor\Net\Http\Request; use Castor\Net\Http\ResponseWriter; use Castor\Net\Http\Status\Code; $handler = Callback::fromCallable( function (Context $ctx, Request $request, ResponseWriter $writer): void { $writer->headers()->set('Content-Type', 'text/plain'); $writer->writeHeaders(Code::OK); $writer->write('Hello, World!'); } ); ``` The handler receives a context, the incoming request, and a response writer. You set headers, write the status line, and then stream the body — in that order. ## Next steps Read about [requests](requests.html) and [responses](responses.html) in depth, or jump to the [handler pattern](handler-pattern.html) to learn how to build server-side HTTP applications.
Castor ecosystem