Reference

In This Article

Headers

Zend\Http\Headers is a container for HTTP headers. It is typically accessed as part of a Zend\Http\Request or Zend\Http\Response instance, via a getHeaders() call. The Headers container will lazily load actual Zend\Http\Header\HeaderInterface instances as to reduce the overhead of header specific parsing.

The class under the Zend\Http\Header namespace are the domain specific implementations for the various types of headers that one might encounter during the typical HTTP request. If a header of unknown type is encountered, it will be implemented as a Zend\Http\Header\GenericHeader instance. See the below table for a list of the various HTTP headers and the API that is specific to each header type.

Quick Start

The quickest way to get started interacting with header objects is by retrieving an already populated Headers container from a request or response instance.

// $client is an instance of Zend\Http\Client

// You can retrieve the request headers by first retrieving
// the Request object and then calling getHeaders on it
$requestHeaders  = $client->getRequest()->getHeaders();

// The same method also works for retrieving Response headers
$responseHeaders = $client->getResponse()->getHeaders();

Zend\Http\Headers can also extract headers from a string:

use Zend\Http\Headers;

$headerString = <<<EOB
Host: www.example.com
Content-Type: text/html
Content-Length: 1337
EOB;

$headers = Headers::fromString($headerString);
// $headers is now populated with three objects
//   (1) Zend\Http\Header\Host
//   (2) Zend\Http\Header\ContentType
//   (3) Zend\Http\Header\ContentLength

Now that you have an instance of Zend\Http\Headers, you can manipulate the individual headers it contains using the provided public API methods outlined in the Available Methods section.

Configuration Options

No configuration options are available.

Available Methods

The following is a list of methods available to Zend\Http\Headers. For brevity, we map the following references to the following classes or namespaces:

  • HeaderInterface: Zend\Http\Header\HeaderInterface
  • Headers: Zend\Http\Headers
  • PluginClassLocator: Zend\Loader\PluginClassLocator
Method signature Description
static fromString(string $string) : Headers Parses a string for headers, and aggregates them, in order, a new Headers instance, primarily as strings until they are needed (they will be lazy loaded).
setPluginClassLoader(PluginClassLocator $pluginClassLoader) : self Set an alternate implementation for the plugin class loader.
getPluginClassLoader() : PluginClassLocator Return an instance of a PluginClassLocator; lazy-load and inject map if necessary.
addHeaders(array|Traversable $headers) : self Add many headers at once; expects an array (or Traversable object) of type/value pairs.
addHeaderLine(string $headerFieldNameOrLine, string $fieldValue) : self Add a raw header line, either as separate name and value arguments, or as a single string in the form name: value This method allows for lazy-loading in that the parsing and instantiation of a HeaderInterface implementation will be delayed until they are retrieved by either get() or current().
addHeader(HeaderInterface $header) : self Add a header instance to the container; for raw values see addHeaderLine() and addHeaders().
removeHeader(HeaderInterface $header) : bool Remove a Header from the container.
clearHeaders() : self Removes all headers from the container.
get(string $name) : false|HeaderInterface|ArrayIterator Get all values for a given header. If none are found, false is returned. If the header is a single-value header, a HeaderInterface is returned. If the header is a multi-value header, an ArrayIterator containing all values is returned.
has(string $name) : bool Test for existence of a header.
next() : void Advance the pointer for this object as an iterator.
key() : mixed Return the current key for this object as an iterator.
valid() : bool Is this iterator still valid?
rewind() : void Reset the internal pointer for this object as an iterator.
current() : HeaderInterface Return the current value for this iterator, lazy loading it if need be.
count() : int Return the number of headers in this container. If all headers have not been parsed, the actual count could decrease if MultipleHeader instances exist. If you need an exact count, iterate.
toString() : string Render all headers at once. This method handles the normal iteration of headers; it is up to the concrete classes to prepend with the appropriate status/request line.
toArray() : array Return all headers as an associative array.
forceLoading() : bool By calling this, it will force parsing and loading of all headers, ensuring count() is accurate.

HeaderInterface Methods

The following are methods available to all HeaderInterface implementations.

Method signature Description
static fromString(string $headerLine) : HeaderInterface Factory to generate a header object from a string.
getFieldName() : string Retrieve header field name.
getFieldValue() : string Retrieve header field value.
toString() : string Cast the header to a well-formed HTTP header line (Name: Value).

AbstractAccept Methods

Zend\Http\Header\AbstractAccept defines the following methods in addition to those it inherits from the HeaderInterface. The Accept, AcceptCharset, AcceptEncoding, and AcceptLanguage header types inherit from it.

For brevity, we map the following references to the following classes or namespaces:

  • AcceptFieldValuePart: Zend\Http\Header\Accept\FieldValuePart\AcceptFieldValuePart
  • InvalidArgumentException: Zend\Http\Header\Exception\InvalidArgumentException
Method signature Description
parseHeaderLine(string $headerLine) : void Parse the given header line and add the values discovered to the instance.
getFieldValuePartsFromHeaderLine(string $headerLine) : array Parse the field value parts represented by an Accept* header line. Throws InvalidArgumentException if the header is invalid.
getFieldValue(array|null $values = null) : string Get field value.
match(array|string $matchAgainst) : bool|AcceptFieldValuePart Match a media string against this header. Returns the matched value or false.
getPrioritized() : array Returns all the keys, values and parameters this header represents.

AbstractDate Methods

Zend\Http\Header\AbstractDate defines the following methods in addition to those it inherits from the HeaderInterface. The Date, Expires, IfModifiedSince, IfUnmodifiedSince, LastModified, and RetryAfter header types inherit from it.

For brevity, we map the following references to the following classes or namespaces:

  • InvalidArgumentException: Zend\Http\Header\Exception\InvalidArgumentException
Method signature Description
static fromTimestamp(int $time) : AbstractDate Create date-based header from Unix timestamp.
static fromTimeString(string $time) : AbstractDate Create date-based header from strtotime()-compatible string.
static setDateFormat(int $format) : void Set date output format; should be an index from the implementation's $dateFormat static property.
static getDateFormat() : string Return current date output format.
setDate(string|DateTime $date) : self Set the date for this header; this can be a string or an instance of DateTime. Throws InvalidArgumentException if the date is neither a valid string nor an instance of DateTime.
getDate() : string Return string representation of the date for this header.
compareTo(string|DateTime $date) : int Compare provided date to date for this header. Returns < 0 if date in header is less than $date; > 0 if it's greater, and = 0 if they are equal. See strcmp.
date() | DateTime Return date for this header as an instance of DateTime.

AbstractLocation Methods

Zend\Http\Header\AbstractLocation defines the following methods in addition to those it inherits from the HeaderInterface. The ContentLocation, Location, and Referer header types inherit from it.

For brevity, we map the following references to the following classes or namespaces:

  • Uri: Zend\Uri\UriInterface
  • InvalidArgumentException: Zend\Http\Header\Exception\InvalidArgumentException
Method signature Description
setUri(string|Uri $uri) : self Set the URI for this header; throws InvalidArgumentException for invalid $uri arguments.
getUri() : string Return the URI for this header.
uri() : Uri Return the Uri instance for this header.

List of HTTP Header Types

Some header classes expose methods for manipulating their value. The following list contains all of the classes available in the Zend\Http\Header\* namespace, as well as any specific methods they contain. Each class implements Zend\Http\Header\HeaderInterface.

Accept

Extends AbstractAccept.

Method signature Description
addMediaType(string $type, int|float $priority = 1) : self Add a media type, with the given priority.
hasMediaType(string $type): bool Does the header have the requested media type?

AcceptCharset

Extends AbstractAccept.

Method signature Description
addCharset(string $type, int|float $priority = 1) : self Add a charset, with the given priority.
hasCharset(string $type) : bool Does the header have the requested charset?

AcceptEncoding

Extends AbstractAccept.

Method signature Description
addEncoding(string $type, int|float $priority = 1) : self Add an encoding, with the given priority.
hasEncoding(string $type) : bool Does the header have the requested encoding?

AcceptLanguage

Extends AbstractAccept.

Method signature Description
addLanguage(string $type, int|float $priority = 1): self Add a language, with the given priority.
hasLanguage(string $type) : bool Does the header have the requested language?

AcceptRanges

Method signature Description
getRangeUnit() : mixed (unknown)
setRangeUnit(mixed $rangeUnit) : self (unkown)

Age

Method signature Description
getDeltaSeconds() : int Get number of seconds.
setDeltaSeconds(int $seconds) : self Set number of seconds

Allow

Method signature Description
getAllMethods() : string[] Get list of all defined methods.
getAllowedMethods() : string[] Get list of allowed methods.
allowMethods(array|string $allowedMethods) : self Allow methods or list of methods.
disallowMethods(array|string $allowedMethods) self Disallow methods or list of methods.
denyMethods(array|string $allowedMethods) : self Convenience alias for disallowMethods().
isAllowedMethod(string $method) : bool Check whether method is allowed.

AuthenticationInfo

No additional methods.

Authorization

No additional methods.

CacheControl

Method signature Description
isEmpty(): bool Checks if the internal directives array is empty.
addDirective(string $key, string|bool $value = true) : self Add a directive. For directives like max-age=60, call as addDirective('max-age', 60). For directives like private, use the default $value (true).
hasDirective(string $key) : bool Check the internal directives array for a directive.
getDirective(string $key) : null|string Fetch the value of a directive from the internal directive array.
removeDirective(string $key) : self Remove a directive.

Connection

Method signature Description
setValue($value) : self Set arbitrary header value. RFC allows any token as value; 'close' and 'keep-alive' are commonly used.
isPersistent() : bool Whether or not the connection is persistent.
setPersistent(bool $flag) : self Set Connection header to define persistent connection.

ContentDisposition

No additional methods.

ContentEncoding

No additional methods.

ContentLanguage

No additional methods.

ContentLength

No additional methods.

ContentLocation

See AbstractLocation.

ContentMD5

No additional methods.

ContentRange

No additional methods.

ContentSecurityPolicy

Method signature Description
getDirectives(): array Retrieve the defined directives for the policy.
setDirective(string $name, array $sources) : self Set the directive with the given name to include the sources. See below for an example.

As an example: an auction site wishes to load images from any URI, plugin content from a list of trusted media providers (including a content distribution network), and scripts only from a server under its control hosting sanitized Javacript:

// http://www.w3.org/TR/2012/CR-CSP-20121115/#sample-policy-definitions
$csp = new ContentSecurityPolicy();
$csp->setDirective('default-src', []); // No sources
$csp->setDirective('img-src', ['*']);
$csp->setDirective('object-src', ['media1.example.com', 'media2.example.com', '*.cdn.example.com']);
$csp->setDirective('script-src', ['trustedscripts.example.com']);

ContentTransferEncoding

No additional methods.

ContentType

Method signature Description
match(array|string $matchAgainst) : bool|string Determine if the mediatype value in this header matches the provided criteria.
getMediaType() : string Get the media type.
setMediaType(string $mediaType) : self Set the media type.
getParameters() : array Get any additional content-type parameters currently set.
setParameters(array $parameters) : self Set additional content-type parameters.
getCharset() : null|string Get the content-type character set encoding, if any.
setCharset(string $charset) : self Set the content-type character set encoding.

Cookie

Extends ArrayObject.

Method signature Description
static fromSetCookieArray(array $setCookies) : Cookie Create an instance from the $_COOKIE array, or one structured like it.
setEncodeValue(bool $encode) : self Set flag indicating whether or not to urlencode() the cookie values.
getEncodeValue() : bool Get flag indicating whether or not to urlencode() the cookie values.

Date

See AbstractDate.

Etag

No additional methods.

Expect

No additional methods.

Expires

See AbstractDate.

From

No additional methods.

Host

No additional methods.

IfMatch

No additional methods.

IfModifiedSince

See AbstractDate.

IfNoneMatch

No additional methods.

IfRange

No additional methods.

IfUnmodifiedSince

See AbstractDate.

KeepAlive

No additional methods.

LastModified

See AbstractDate.

Location

See AbstractLocation.

MaxForwards

No additional methods.

Origin

No additional methods.

Pragma

No additional methods.

ProxyAuthenticate

Method signature Description
toStringMultipleHeaders(array $headers) : string Creates a string representation when multiple values are present.

ProxyAuthorization

No additional methods.

Range

No additional methods.

Referer

See AbstractLocation.

Refresh

No additional methods.

RetryAfter

See AbstractDate.

Method signature Description
setDeltaSeconds(int $delta) : self Set number of seconds.
getDeltaSeconds() : int Get number of seconds.

Server

No additional methods.

SetCookie

Method signature Description
static matchCookieDomain(string $cookieDomain, string $host) : bool Check if a cookie's domain matches a host name.
static matchCookiePath(string $cookiePath, string $path) : bool Check if a cookie's path matches a URL path.
getName() : string Retrieve the cookie name.
setName(string $name) : self Set the cookie name.
getValue() : string Retrieve the cookie value.
setValue(string $value) : self Set the cookie value.
getExpires() : int Retrieve the expiration date for the cookie.
setExpires(int|string $expires) : self Set the cookie expiration timestamp; null indicates a session cookie.
getPath() : string Retrieve the URI path the cookie is bound to.
setPath(string $path) : self Set the URI path the cookie is bound to.
getDomain() : string Retrieve the domain the cookie is bound to.
setDomain(string $domain) : self Set the domain the cookie is bound to.
getMaxAge() : int Retrieve the maximum age for the cookie.
setMaxAge(int|string $maxAge) : self Set the maximum age for the cookie.
getVersion() : int Retrieve the cookie version.
setVersion(int|string $version) : self Set the cookie version.
isSecure(): bool Whether the cookies contains the Secure flag.
setSecure(bool $secure) : self Set whether the cookies contain the Secure flag.
isHttponly() : bool Whether the cookies can be accessed via the HTTP protocol only.
setHttponly(bool $httponly) : self Set whether the cookies can be accessed only via HTTP protocol.
getSameSite() : ?string Retrieve the SameSite directive value (null when it is not set).
setSameSite(?string $sameSite) : self Set SameSite directive value - allowed values are: Strict, Lax and None.
isExpired() : bool Whether the cookie is expired.
isSessionCookie() : bool Whether the cookie is a session cookie.
setQuoteFieldValue(bool $quotedValue) : self Set whether the value for this cookie should be quoted.
hasQuoteFieldValue() : bool Check whether the value for this cookie should be quoted.
isValidForRequest() : bool Whether the cookie is valid for a given request domain, path and isSecure.
match(string $uri, bool $matchSessionCookies, int $now) : bool Checks whether the cookie should be sent or not in a specific scenario.
toStringMultipleHeaders(array $headers) : string Returns string representation when multiple values are present.

TE

No additional methods.

Trailer

No additional methods.

TransferEncoding

No additional methods.

Upgrade

No additional methods.

UserAgent

No additional methods.

Vary

No additional methods.

Via

No additional methods.

Warning

No additional methods.

WWWAuthenticate

Defines a toStringMultipleHeaders(array $headers) method for serializing to string when multiple values are present.

Examples

Retrieving headers from a Headers object

// $client is an instance of Zend\Http\Client
$response = $client->send();
$headers = $response->getHeaders();

// We can check if the Request contains a specific header by
// using the ``has`` method. Returns boolean ``TRUE`` if at least
// one matching header found, and ``FALSE`` otherwise
$headers->has('Content-Type');

// We can retrieve all instances of a specific header by using
// the ``get`` method:
$contentTypeHeaders = $headers->get('Content-Type');

There are three possibilities for the return value of the above call to the get method:

  • If no Content-Type header was set in the Request, get will return false.
  • If only one Content-Type header was set in the Request, get will return an instance of Zend\Http\Header\ContentType.
  • If more than one Content-Type header was set in the Request, get will return an ArrayIterator containing one Zend\Http\Header\ContentType instance per header.

Adding headers to a Headers object

use Zend\Http\Header;
use Zend\Http\Headers;

$headers = new Headers();

// We can directly add any object that implements Zend\Http\Header\HeaderInterface
$typeHeader = Header\ContentType::fromString('Content-Type: text/html');
$headers->addHeader($typeHeader);

// We can add headers using the raw string representation, either
// passing the header name and value as separate arguments...
$headers->addHeaderLine('Content-Type', 'text/html');

// .. or we can pass the entire header as the only argument
$headers->addHeaderLine('Content-Type: text/html');

// We can also add headers in bulk using addHeaders, which accepts
// an array of individual header definitions that can be in any of
// the accepted formats outlined below:
$headers->addHeaders([
    // An object implementing Header\HeaderInterface
    Header\ContentType::fromString('Content-Type: text/html'),

    // A raw header string
    'Content-Type: text/html',

    // We can also pass the header name as the array key and the
    // header content as that array key's value
    'Content-Type' => 'text/html',
]);

Removing headers from a Headers object

We can remove all headers of a specific type using the removeHeader method, which accepts a single object implementing Zend\Http\Header\HeaderInterface

use ArrayIterator;
use Zend\Http\Header\HeaderInterface;

// $headers is a pre-configured instance of Zend\Http\Headers

// We can also delete individual headers or groups of headers
$matches = $headers->get('Content-Type');

if ($matches instanceof ArrayIterator) {
    // If more than one header was found, iterate over the collection
    // and remove each one individually
    foreach ($headers as $header) {
        $headers->removeHeader($header);
    }
} elseif ($matches instanceof HeaderInterface) {
    // If only a single header was found, remove it directly
    $headers->removeHeader($header);
}

// In addition to this, we can clear all the headers currently stored in
// the container by calling the clearHeaders() method
$matches->clearHeaders();

Found a mistake or want to contribute to the documentation? Edit this page on GitHub!