On this page
Reference
Headers
Laminas\Http\Headers
is a container for HTTP headers. It is typically accessed as
part of a Laminas\Http\Request
or Laminas\Http\Response
instance, via a
getHeaders()
call. The Headers
container will lazily load actual
Laminas\Http\Header\HeaderInterface
instances as to reduce the overhead of header
specific parsing.
The class under the Laminas\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 Laminas\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 Laminas\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();
Laminas\Http\Headers
can also extract headers from a string:
use Laminas\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) Laminas\Http\Header\Host
// (2) Laminas\Http\Header\ContentType
// (3) Laminas\Http\Header\ContentLength
Now that you have an instance of Laminas\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 Laminas\Http\Headers
. For
brevity, we map the following references to the following classes or namespaces:
HeaderInterface
:Laminas\Http\Header\HeaderInterface
Headers
:Laminas\Http\Headers
PluginClassLocator
:Laminas\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
Laminas\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
:Laminas\Http\Header\Accept\FieldValuePart\AcceptFieldValuePart
InvalidArgumentException
:Laminas\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
Laminas\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
:Laminas\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
Laminas\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
:Laminas\Uri\UriInterface
InvalidArgumentException
:Laminas\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 Laminas\Http\Header\*
namespace, as well as any specific methods they contain. Each class implements
Laminas\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 Laminas\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 theRequest
,get
will returnfalse
. - If only one
Content-Type
header was set in theRequest
,get
will return an instance ofLaminas\Http\Header\ContentType
. - If more than one
Content-Type
header was set in theRequest
,get
will return anArrayIterator
containing oneLaminas\Http\Header\ContentType
instance per header.
Adding headers to a Headers object
use Laminas\Http\Header;
use Laminas\Http\Headers;
$headers = new Headers();
// We can directly add any object that implements Laminas\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 Laminas\Http\Header\HeaderInterface
use ArrayIterator;
use Laminas\Http\Header\HeaderInterface;
// $headers is a pre-configured instance of Laminas\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();