Click the Castor logo or press Ctrl Alt T to change theme.
# Headers `Castor\Net\Http\Headers` is a mutable, case-insensitive collection of HTTP header fields. It stores every value for a header key, preserves repeated header lines, and can write itself in HTTP wire format. ## Creating headers Start with an empty collection: ```php <?php use Castor\Net\Http\Headers; $headers = new Headers(); ``` Or create one from a simple map: ```php $headers = Headers::fromMap([ 'Content-Type' => 'application/json', 'Cache-Control' => 'no-store', ]); ``` `fromMap` is intentionally simple: one string value per key. Use `add` or variadic `set` when a header needs multiple values. ## Canonical, case-insensitive keys Header lookups are case-insensitive. Internally, keys are canonicalized by lowercasing, removing spaces, and title-casing hyphen-separated words: ```php $headers->set('content-type', 'application/json'); $headers->get('Content-Type'); // "application/json" $headers->get('CONTENT-TYPE'); // "application/json" $headers->has('content type'); // true ``` When you iterate or write headers, keys are emitted in their canonical form, such as `Content-Type`. ## Setting and adding values Use `set` when the header should have exactly the provided values: ```php $headers->set('Accept', 'application/json'); $headers->set('Vary', 'Accept-Encoding', 'Origin'); ``` Calling `set` replaces all previous values for that header. Use `add` when you want another header line with the same key: ```php $headers->add('Set-Cookie', 'session=abc; Path=/; HttpOnly'); $headers->add('Set-Cookie', 'theme=dark; Path=/'); ``` ## Reading values There are three read methods, each with a different missing-value behavior: ```php $headers->lookup('Accept'); // first value or null $headers->get('Accept'); // first value or "" $headers->values('Vary'); // all values, or [] ``` Use `lookup` when you need to distinguish an absent header from an explicitly empty header. Use `get` when an empty string is an acceptable default. ## Deleting and checking headers ```php $headers->has('Authorization'); // bool $headers->del('Authorization'); ``` `del` removes every value for the canonicalized key. ## Copying headers ```php $copy = $headers->copy(); ``` `copy` returns a clone. This is useful when you need to reuse a header set as a template without sharing subsequent mutations. ## Iteration `Headers` implements `IteratorAggregate<string,string>`. Iteration yields one item per header value: ```php foreach ($headers as $name => $value) { echo $name . ': ' . $value . PHP_EOL; } ``` A header with two values yields two iterations with the same key. ## Writing wire format `Headers` implements `Castor\Io\WriterTo`: ```php <?php use Castor\Io\Stream; $buffer = Stream\Buffer::empty(); $headers->writeTo($buffer); ``` The output is one `Name: value` line per header value followed by a blank line. This makes the collection suitable for response serialization and custom transports. ## Headers and responses When using a `ResponseWriter`, set headers before calling `writeHeaders` or writing the body: ```php $writer->headers()->set('Content-Type', 'text/plain'); $writer->writeHeaders(); $writer->write('Hello'); ``` After headers have been sent, some writers may return a copy from `headers()` so late mutations do not affect the already-sent response.
Castor ecosystem