Menu

Reference

Reference / Http

Headers

finalclass
final class Headers

A set of HTTP header fields: case-insensitive lookup on top of the ordered wire lines.

The lookup side answers "what is the Content-Type": names are case-insensitive and a repeated field is comma-joined (a, b). The wire side keeps every line in the order it was added, and does not join repeats, which is what Set-Cookie needs. Request::$headers holds what the client sent; Response::$headers holds what will be sent.

get(), has(), int() and all() use the lookup side. lines() and render() use the wire side.

Example

// Http\Headers: case-insensitive lookup on top of an ordered list of wire lines.

use Http\Headers;

$h = new Headers();
$h->set('Content-Type', 'text/plain');
$h->add('Set-Cookie', 'a=1');
$h->add('Set-Cookie', 'b=2');   // add() keeps both lines on the wire
$h->add('Accept', 'text/html');
$h->add('Accept', 'application/json');

echo $h->get('content-type'), "\n";            // lookup ignores case
echo $h->get('SET-COOKIE'), "\n";              // repeats are comma-joined for lookup
echo var_export($h->has('X-Missing'), true), "\n";
echo $h->get('X-Missing', 'fallback'), "\n";
echo $h->int('Content-Length', -1), "\n";      // absent: the default

$h->set('Content-Length', '42');
echo $h->int('content-length'), "\n";
echo $h->count(), " names\n";

$h->set('Accept', '*/*');                      // set() replaces every earlier line
$h->remove('Content-Type');
print_r($h->lines());                          // wire lines, in order
echo str_replace("\r\n", "|", $h->render()), "\n";

$parsed = Headers::fromLines(['Host: example.com', 'X-Trace:  abc  ', 'not a header line']);
echo $parsed->get('host'), ' / [', $parsed->get('x-trace'), "]\n";

Output

text/plain
a=1, b=2
false
fallback
-1
42
4 names
Array
(
    [0] => Set-Cookie: a=1
    [1] => Set-Cookie: b=2
    [2] => Content-Length: 42
    [3] => Accept: */*
)
Set-Cookie: a=1|Set-Cookie: b=2|Content-Length: 42|Accept: */*||
example.com / [abc]

See also: Request, Response

Methods

fromLines()Builds a header set from raw Name: value lines.
has()Whether a field is present.
get()The value of a field.
int()The value as an int, or $default when absent or not all digits.
set()Sets a field, replacing every existing line with that name.
add()Appends a field line and keeps any lines that are already there.
remove()Removes every line with this name.
count()The number of distinct field names (a repeated field counts once).
all()All fields for lookup: lowercased name to value, repeats comma-joined.
lines()The wire lines, in the order they were added, one Name: value string per line without the CRLF.
render()The block as it goes on the wire: every line followed by CRLF, then the empty line that ends a head.
clear()Removes every field.
copyFrom()Replaces this set with a copy of another, keeping repeated lines and their order.

fromLines()#source

static function fromLines(array<int,string> $lines): Headers

Builds a header set from raw Name: value lines.

A line without a colon, with an empty name, or with a name that is not a valid HTTP token is skipped. Whitespace around the value is trimmed. Lines are not unfolded: pass one complete field per element.

Parameters

$lines array<int,string>
Header lines without the trailing CRLF.

Returns

Headers — A new Headers holding the valid lines, in order.

has()#source

function has(string $n): bool

Whether a field is present. The name is case-insensitive.

Parameters

$n string
Field name.

Returns

bool — true if at least one line with that name exists.

get()#source

function get(string $n, string $default = ''): string

The value of a field. The name is case-insensitive.

If the field occurs more than once, the values are joined with , in the order they were added.

Parameters

$n string
Field name.
$default string = ''
Returned when the field is absent.

Returns

string — The value, or $default.

int()#source

function int(string $n, int $default = 0): int

The value as an int, or $default when absent or not all digits.

Parameters

$n string
Field name.
$default int = 0
Returned when the field is absent, empty, longer than 18 digits, or contains anything but digits.

Returns

int — The value as an integer, or $default.

set()#source

function set(string $n, string $v): void

Sets a field, replacing every existing line with that name.

The new line goes to the end of the wire order and keeps the capitalisation of $n as written.

Parameters

$n string
Field name.
$v string
Field value.

add()#source

function add(string $n, string $v): void

Appends a field line and keeps any lines that are already there.

Lookup (get()) then answers the values comma-joined; the wire gets one line per call, which is what Set-Cookie needs.

Parameters

$n string
Field name.
$v string
Field value.

remove()#source

function remove(string $n): void

Removes every line with this name. The name is case-insensitive; an absent name is not an error.

Parameters

$n string
Field name.

count()#source

function count(): int

The number of distinct field names (a repeated field counts once).

Returns

int — The count.

all()#source

function all(): array<string,string>

All fields for lookup: lowercased name to value, repeats comma-joined.

Returns

array<string,string> — lowercased name => value

lines()#source

function lines(): array<int,string>

The wire lines, in the order they were added, one Name: value string per line without the CRLF.

Returns

array<int,string> — the wire lines, in order

render()#source

function render(): string

The block as it goes on the wire: every line followed by CRLF, then the empty line that ends a head.

Returns

string — The serialized block.

clear()#source

function clear(): void

Removes every field.

copyFrom()#source

function copyFrom(Headers $o): void

Replaces this set with a copy of another, keeping repeated lines and their order.

Parameters

$o Headers
The set to copy.

View source