Class Response

Responses contain the response text, status and headers of a HTTP response.

There are external packages such as fig/http-message-util that provide HTTP status code constants. These can be used with any method that accepts or returns a status code integer. Keep in mind that these consants might include status codes that are now allowed which will throw an \InvalidArgumentException.

Namespace: Cake\Http

Constants summary

int

STATUS_CODE_MAX

599
int

STATUS_CODE_MIN

100

Properties summary

$_cacheDirectives protected

array

Holds all the cache directives that will be converted into headers when sending the request
$_charset protected

string

The charset the response body is encoded with
$_cookies protected

\Cake\Http\Cookie\CookieCollection

Collection of cookies to send to the client
$_file protected

\SplFileInfo|null

File object for file to be read out as response
$_fileRange protected

array

File range. Used for requesting ranges of files.
$_mimeTypes protected

array

Holds type key to mime type mappings for known mime types.
$_reasonPhrase protected

string

Reason Phrase
$_status protected

int

Status code to send to the client
$_statusCodes protected

string[]

Allowed HTTP status codes and their default description.
$_streamMode protected

string

Stream mode options.
$_streamTarget protected

string|resource

Stream target or resource object.
$headerNames protected

array

Map of normalized header name to original name used to register header.
$headers protected

array

List of all registered headers, as key => array of values.

Method Summary

__construct() public

Constructor
__debugInfo() public

Returns an array that can be used to describe the internal state of this object.
__toString() public

String conversion. Fetches the response body as a string.
_clearHeader() protected

Clear header
_createStream() protected

Creates the stream object.
_fileRange() protected

Apply a file range to a file and set the end offset.
_getUTCDate() protected

Returns a DateTime object initialized at the $time param and using UTC as timezone
_setCacheControl() protected

Helper method to generate a valid Cache-Control header from the options set in other methods
_setContentType() protected

Formats the Content-Type header based on the configured contentType and charset the charset will only be set in the header if the response is of type text/*
_setHeader() protected

Sets a header.
_setStatus() protected

Modifier for response status
checkNotModified() public

Checks whether a response has not been modified according to the 'If-None-Match' (Etags) and 'If-Modified-Since' (last modification date) request headers. If the response is detected to be not modified, it is marked as so accordingly so the client can be informed of that.
compress() public

Sets the correct output buffering handler to send a compressed response. Responses will be compressed with zlib, if the extension is available.
cors() public

Get a CorsBuilder instance for defining CORS headers.
getBody() public

Gets the body of the message.
getCharset() public

Returns the current charset.
getCookie() public

Read a single cookie from the response.
getCookieCollection() public

Get the CookieCollection from the response
getCookies() public

Get all cookies in the response.
getFile() public

Get the current file if one exists.
getHeader() public

Retrieves a message header value by the given case-insensitive name.
getHeaderLine() public

Retrieves a comma-separated string of the values for a single header.
getHeaders() public

Retrieves all message headers.
getMimeType() public

Returns the mime type definition for an alias
getProtocolVersion() public

Retrieves the HTTP protocol version as a string.
getReasonPhrase() public

Gets the response reason phrase associated with the status code.
getStatusCode() public

Gets the response status code.
getType() public

Returns the current content type.
hasHeader() public

Checks if a header exists by the given case-insensitive name.
mapType() public

Maps a content-type back to an alias
notModified() public

Sets the response as Not Modified by removing any body contents setting the status code to "304 Not Modified" and removing all conflicting headers
outputCompressed() public

Returns whether the resulting output will be compressed by PHP
resolveType() protected

Translate and validate content-types.
setTypeMap() public

Sets a content type definition into the map.
validateFile() protected

Validate a file path is a valid response body.
withAddedHeader() public

Return an instance with the specified header appended with the given value.
withAddedLink() public

Create a new response with the Link header set.
withBody() public

Return an instance with the specified message body.
withCache() public

Create a new instance with the headers to enable client caching.
withCharset() public

Get a new instance with an updated charset.
withCookie() public

Create a new response with a cookie set.
withCookieCollection() public

Get a new instance with provided cookie collection.
withDisabledCache() public

Create a new instance with headers to instruct the client to not cache the response
withDownload() public

Create a new instance with the Content-Disposition header set.
withEtag() public

Create a new instance with the Etag header set.
withExpiredCookie() public

Create a new response with an expired cookie set.
withExpires() public

Create a new instance with the Expires header set.
withFile() public

Create a new instance that is based on a file.
withHeader() public

Return an instance with the provided header, replacing any existing values of any headers with the same case-insensitive name.
withLength() public

Create a new response with the Content-Length header set.
withLocation() public

Return an instance with an updated location header.
withMaxAge() public

Create an instance with Cache-Control max-age directive set.
withModified() public

Create a new instance with the Last-Modified header set.
withMustRevalidate() public

Create an instance with Cache-Control must-revalidate directive set.
withNotModified() public

Create a new instance as 'not modified'
withProtocolVersion() public

Return an instance with the specified HTTP protocol version.
withSharable() public

Create a new instace with the public/private Cache-Control directive set.
withSharedMaxAge() public

Create a new instance with the Cache-Control s-maxage directive.
withStatus() public

Return an instance with the specified status code and, optionally, reason phrase.
withStringBody() public

Convenience method to set a string into the response body
withType() public

Get an updated response with the content type set.
withVary() public

Create a new instance with the Vary header set.
withoutHeader() public

Return an instance without the specified header.

Method Detail

__construct() public

__construct(array $options)

Constructor

Parameters

array $options optional

list of parameters to setup the response. Possible values are:

body: the response text that should be sent to the client
status: the HTTP status code to respond with
type: a complete mime-type string or an extension mapped in this class
charset: the charset for the response body

Throws

InvalidArgumentException

__debugInfo() public

__debugInfo()

Returns an array that can be used to describe the internal state of this object.

Returns

array

__toString() public

__toString()

String conversion. Fetches the response body as a string.

Does not send headers. If body is a callable, a blank string is returned.

Returns

string

_clearHeader() protected

_clearHeader(string $header)

Clear header

Parameters

string $header: Header key.

_createStream() protected

_createStream()

Creates the stream object.

_fileRange() protected

_fileRange(\SplFileInfo $file, string $httpRange)

Apply a file range to a file and set the end offset.

If an invalid range is requested a 416 Status code will be used in the response.

Parameters

\SplFileInfo $file: The file to set a range on.
string $httpRange: The range to use.

_getUTCDate() protected

_getUTCDate(mixed $time)

Returns a DateTime object initialized at the $time param and using UTC as timezone

Parameters

string|int|\DateTimeInterface|null $time optional: Valid time string or \DateTimeInterface instance.

Returns

\DateTimeInterface

_setCacheControl() protected

_setCacheControl()

Helper method to generate a valid Cache-Control header from the options set in other methods

_setContentType() protected

_setContentType(string $type)

Formats the Content-Type header based on the configured contentType and charset the charset will only be set in the header if the response is of type text/*

Parameters

string $type: The type to set.

_setHeader() protected

_setHeader(string $header, string $value)

Sets a header.

Parameters

string $header: Header key.
string $value: Header value.

_setStatus() protected

_setStatus(int $code, string $reasonPhrase)

Modifier for response status

Parameters

int $code: The status code to set.
string $reasonPhrase optional: The response reason phrase.

Throws

InvalidArgumentException
For invalid status code arguments.

checkNotModified() public

checkNotModified(\Cake\Http\ServerRequest $request)

Checks whether a response has not been modified according to the 'If-None-Match' (Etags) and 'If-Modified-Since' (last modification date) request headers. If the response is detected to be not modified, it is marked as so accordingly so the client can be informed of that.

In order to mark a response as not modified, you need to set at least the Last-Modified etag response header before calling this method. Otherwise a comparison will not be possible.

Warning This method mutates the response in-place and should be avoided.

Parameters

\Cake\Http\ServerRequest $request: Request object

Returns

bool

Whether the response was marked as not modified or not.

compress() public

compress()

Sets the correct output buffering handler to send a compressed response. Responses will be compressed with zlib, if the extension is available.

Returns

bool

false if client does not accept compressed responses or no handler is available, true otherwise

cors() public

cors(\Cake\Http\ServerRequest $request)

Get a CorsBuilder instance for defining CORS headers.

This method allow multiple ways to setup the domains, see the examples

Full URI

cors($request, 'https://www.cakephp.org');

URI with wildcard

cors($request, 'https://*.cakephp.org');

Ignoring the requested protocol

cors($request, 'www.cakephp.org');

Any URI

cors($request, '*');

Allowed list of URIs

cors($request, ['http://www.cakephp.org', '*.google.com', 'https://myproject.github.io']);

Note The $allowedDomains, $allowedMethods, $allowedHeaders parameters are deprecated. Instead the builder object should be used.

Parameters

\Cake\Http\ServerRequest $request: Request object

Returns

\Cake\Http\CorsBuilder

A builder object the provides a fluent interface for defining additional CORS headers.

getBody() public

getBody()

Gets the body of the message.

Returns

\Psr\Http\Message\StreamInterface

Returns the body as a stream.

getCharset() public

getCharset()

Returns the current charset.

Returns

string

getCookie() public

getCookie(string $name)

Read a single cookie from the response.

This method provides read access to pending cookies. It will not read the Set-Cookie header if set.

Parameters

string $name: The cookie name you want to read.

Returns

array|null

Either the cookie data or null

getCookieCollection() public

getCookieCollection()

Get the CookieCollection from the response

Returns

\Cake\Http\Cookie\CookieCollection

getCookies() public

getCookies()

Get all cookies in the response.

Returns an associative array of cookie name => cookie data.

Returns

array

getFile() public

getFile()

Get the current file if one exists.

Returns

\SplFileInfo|null

The file to use in the response or null

getHeader() public

getHeader(mixed $header)

Retrieves a message header value by the given case-insensitive name.

This method returns an array of all the header values of the given case-insensitive header name.

If the header does not appear in the message, this method MUST return an empty array.

Parameters

string $header: Case-insensitive header field name.

Returns

string[]

An array of string values as provided for the given header. If the header does not appear in the message, this method MUST return an empty array.

getHeaderLine() public

getHeaderLine(mixed $name)

Retrieves a comma-separated string of the values for a single header.

This method returns all of the header values of the given case-insensitive header name as a string concatenated together using a comma.

NOTE: Not all header values may be appropriately represented using comma concatenation. For such headers, use getHeader() instead and supply your own delimiter when concatenating.

If the header does not appear in the message, this method MUST return an empty string.

Parameters

string $name: Case-insensitive header field name.

Returns

string

A string of values as provided for the given header concatenated together using a comma. If the header does not appear in the message, this method MUST return an empty string.

getHeaders() public

getHeaders()

Retrieves all message headers.

The keys represent the header name as it will be sent over the wire, and each value is an array of strings associated with the header.

// Represent the headers as a string
foreach ($message->getHeaders() as $name => $values) {
    echo $name . ": " . implode(", ", $values);
}

// Emit headers iteratively:
foreach ($message->getHeaders() as $name => $values) {
    foreach ($values as $value) {
        header(sprintf('%s: %s', $name, $value), false);
    }
}

Returns

array

Returns an associative array of the message's headers. Each key MUST be a header name, and each value MUST be an array of strings.

getMimeType() public

getMimeType(string $alias)

Returns the mime type definition for an alias

e.g getMimeType('pdf'); // returns 'application/pdf'

Parameters

string $alias: the content type alias to map

Returns

string|array|false

String mapped mime type or false if $alias is not mapped

getProtocolVersion() public

getProtocolVersion()

Retrieves the HTTP protocol version as a string.

The string MUST contain only the HTTP version number (e.g., "1.1", "1.0").

Returns

string

HTTP protocol version.

getReasonPhrase() public

getReasonPhrase()

Gets the response reason phrase associated with the status code.

Because a reason phrase is not a required element in a response status line, the reason phrase value MAY be null. Implementations MAY choose to return the default RFC 7231 recommended reason phrase (or those listed in the IANA HTTP Status Code Registry) for the response's status code.

Returns

string

Reason phrase; must return an empty string if none present.

Links

https://tools.ietf.org/html/rfc7231#section-6

http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml

getStatusCode() public

getStatusCode()

Gets the response status code.

The status code is a 3-digit integer result code of the server's attempt to understand and satisfy the request.

Returns

int

Status code.

getType() public

getType()

Returns the current content type.

Returns

string

hasHeader() public

hasHeader(mixed $header)

Checks if a header exists by the given case-insensitive name.

Parameters

string $header: Case-insensitive header name.

Returns

bool

Returns true if any header names match the given header name using a case-insensitive string comparison. Returns false if no matching header name is found in the message.

mapType() public

mapType(mixed $ctype)

Maps a content-type back to an alias

e.g mapType('application/pdf'); // returns 'pdf'

Parameters

string|array $ctype: Either a string content type to map, or an array of types.

Returns

string|array|null

Aliases for the types provided.

notModified() public

notModified()

Sets the response as Not Modified by removing any body contents setting the status code to "304 Not Modified" and removing all conflicting headers

Warning This method mutates the response in-place and should be avoided.

outputCompressed() public

outputCompressed()

Returns whether the resulting output will be compressed by PHP

Returns

bool

resolveType() protected

resolveType(string $contentType)

Translate and validate content-types.

Parameters

string $contentType: The content-type or type alias.

Returns

string

The resolved content-type

Throws

InvalidArgumentException
When an invalid content-type or alias is used.

setTypeMap() public

setTypeMap(string $type, mixed $mimeType)

Sets a content type definition into the map.

E.g.: setTypeMap('xhtml', ['application/xhtml+xml', 'application/xhtml'])

This is needed for RequestHandlerComponent and recognition of types.

Parameters

string $type: Content type.
string|array $mimeType: Definition of the mime type.

validateFile() protected

validateFile(string $path)

Validate a file path is a valid response body.

Parameters

string $path: The path to the file.

Returns

\SplFileInfo

Throws

Cake\Http\Exception\NotFoundException

withAddedHeader() public

withAddedHeader(mixed $header, mixed $value)

Return an instance with the specified header appended with the given value.

Existing values for the specified header will be maintained. The new value(s) will be appended to the existing list. If the header did not exist previously, it will be added.

This method MUST be implemented in such a way as to retain the immutability of the message, and MUST return an instance that has the new header and/or value.

Parameters

string $header: Case-insensitive header field name to add.
string|string[] $value: Header value(s).

Returns

static

Throws

Laminas\Diactoros\Exception\InvalidArgumentException
for invalid header names or values.

withAddedLink() public

withAddedLink(string $url, array $options)

Create a new response with the Link header set.

Examples

$response = $response->withAddedLink('http://example.com?page=1', ['rel' => 'prev'])
    ->withAddedLink('http://example.com?page=3', ['rel' => 'next']);

Will generate:

Link: <http://example.com?page=1>; rel="prev"
Link: <http://example.com?page=3>; rel="next"

Parameters

string $url: The LinkHeader url.
array $options optional: The LinkHeader params.

Returns

static

withBody() public

withBody(\Psr\Http\Message\StreamInterface $body)

Return an instance with the specified message body.

The body MUST be a StreamInterface object.

This method MUST be implemented in such a way as to retain the immutability of the message, and MUST return a new instance that has the new body stream.

Parameters

\Psr\Http\Message\StreamInterface $body: Body.

Returns

static

Throws

Laminas\Diactoros\Exception\InvalidArgumentException
When the body is not valid.

withCache() public

withCache(mixed $since, mixed $time)

Create a new instance with the headers to enable client caching.

Parameters

int|string $since: a valid time since the response text has not been modified
int|string $time optional: a valid time for cache expiry

Returns

static

withCharset() public

withCharset(string $charset)

Get a new instance with an updated charset.

Parameters

string $charset: Character set string.

Returns

static

withCookie() public

withCookie(\Cake\Http\Cookie\CookieInterface $cookie)

Create a new response with a cookie set.

Example

// add a cookie object
$response = $response->withCookie(new Cookie('remember_me', 1));

Parameters

\Cake\Http\Cookie\CookieInterface $cookie: cookie object

Returns

static

withCookieCollection() public

withCookieCollection(\Cake\Http\Cookie\CookieCollection $cookieCollection)

Get a new instance with provided cookie collection.

Parameters

\Cake\Http\Cookie\CookieCollection $cookieCollection: Cookie collection to set.

Returns

static

withDisabledCache() public

withDisabledCache()

Create a new instance with headers to instruct the client to not cache the response

Returns

static

withDownload() public

withDownload(string $filename)

Create a new instance with the Content-Disposition header set.

Parameters

string $filename: The name of the file as the browser will download the response

Returns

static

withEtag() public

withEtag(string $hash, bool $weak)

Create a new instance with the Etag header set.

Etags are a strong indicative that a response can be cached by a HTTP client. A bad way of generating Etags is creating a hash of the response output, instead generate a unique hash of the unique components that identifies a request, such as a modification time, a resource Id, and anything else you consider it that makes the response unique.

The second parameter is used to inform clients that the content has changed, but semantically it is equivalent to existing cached values. Consider a page with a hit counter, two different page views are equivalent, but they differ by a few bytes. This permits the Client to decide whether they should use the cached data.

Parameters

string $hash: The unique hash that identifies this response
bool $weak optional: Whether the response is semantically the same as other with the same hash or not. Defaults to false

Returns

static

withExpiredCookie() public

withExpiredCookie(\Cake\Http\Cookie\CookieInterface $cookie)

Create a new response with an expired cookie set.

Example

// add a cookie object
$response = $response->withExpiredCookie(new Cookie('remember_me'));

Parameters

\Cake\Http\Cookie\CookieInterface $cookie: cookie object

Returns

static

withExpires() public

withExpires(mixed $time)

Create a new instance with the Expires header set.

Examples:

// Will Expire the response cache now
$response->withExpires('now')

// Will set the expiration in next 24 hours
$response->withExpires(new DateTime('+1 day'))

Parameters

string|int|\DateTimeInterface|null $time: Valid time string or \DateTime instance.

Returns

static

withFile() public

withFile(string $path, array $options)

Create a new instance that is based on a file.

This method will augment both the body and a number of related headers.

If $_SERVER['HTTP_RANGE'] is set, a slice of the file will be returned instead of the entire file.

Options keys

name: Alternate download name
download: If true sets download header and forces file to be downloaded rather than displayed inline.

Parameters

string $path: Absolute path to file.
array $options optional: Options See above.

Returns

static

Throws

Cake\Http\Exception\NotFoundException

withHeader() public

withHeader(mixed $header, mixed $value)

Return an instance with the provided header, replacing any existing values of any headers with the same case-insensitive name.

While header names are case-insensitive, the casing of the header will be preserved by this function, and returned from getHeaders().

This method MUST be implemented in such a way as to retain the immutability of the message, and MUST return an instance that has the new and/or updated header and value.

Parameters

string $header: Case-insensitive header field name.
string|string[] $value: Header value(s).

Returns

static

Throws

Laminas\Diactoros\Exception\InvalidArgumentException
for invalid header names or values.

withLength() public

withLength(mixed $bytes)

Create a new response with the Content-Length header set.

Parameters

int|string $bytes: Number of bytes

Returns

static

withLocation() public

withLocation(string $url)

Return an instance with an updated location header.

If the current status code is 200, it will be replaced with 302.

Parameters

string $url: The location to redirect to.

Returns

static

A new response with the Location header set.

withMaxAge() public

withMaxAge(int $seconds)

Create an instance with Cache-Control max-age directive set.

The max-age is the number of seconds after which the response should no longer be considered a good candidate to be fetched from the local (client) cache.

Parameters

int $seconds: The seconds a cached response can be considered valid

Returns

static

withModified() public

withModified(mixed $time)

Create a new instance with the Last-Modified header set.

Examples:

// Will Expire the response cache now
$response->withModified('now')

// Will set the expiration in next 24 hours
$response->withModified(new DateTime('+1 day'))

Parameters

int|string|\DateTimeInterface $time: Valid time string or \DateTime instance.

Returns

static

withMustRevalidate() public

withMustRevalidate(bool $enable)

Create an instance with Cache-Control must-revalidate directive set.

Sets the Cache-Control must-revalidate directive. must-revalidate indicates that the response should not be served stale by a cache under any circumstance without first revalidating with the origin.

Parameters

bool $enable: If boolean sets or unsets the directive.

Returns

static

withNotModified() public

withNotModified()

Create a new instance as 'not modified'

This will remove any body contents set the status code to "304" and removing headers that describe a response body.

Returns

static

withProtocolVersion() public

withProtocolVersion(mixed $version)

Return an instance with the specified HTTP protocol version.

The version string MUST contain only the HTTP version number (e.g., "1.1", "1.0").

This method MUST be implemented in such a way as to retain the immutability of the message, and MUST return an instance that has the new protocol version.

Parameters

string $version: HTTP protocol version

Returns

static

withSharable() public

withSharable(bool $public, ?int $time)

Create a new instace with the public/private Cache-Control directive set.

Parameters

bool $public: If set to true, the Cache-Control header will be set as public if set to false, the response will be set to private.
int|null $time optional: time in seconds after which the response should no longer be considered fresh.

Returns

static

withSharedMaxAge() public

withSharedMaxAge(int $seconds)

Create a new instance with the Cache-Control s-maxage directive.

The max-age is the number of seconds after which the response should no longer be considered a good candidate to be fetched from a shared cache (like in a proxy server).

Parameters

int $seconds: The number of seconds for shared max-age

Returns

static

withStatus() public

withStatus(mixed $code, mixed $reasonPhrase)

Return an instance with the specified status code and, optionally, reason phrase.

If no reason phrase is specified, implementations MAY choose to default to the RFC 7231 or IANA recommended reason phrase for the response's status code.

This method MUST be implemented in such a way as to retain the immutability of the message, and MUST return an instance that has the updated status and reason phrase.

If the status code is 304 or 204, the existing Content-Type header will be cleared, as these response codes have no body.

There are external packages such as fig/http-message-util that provide HTTP status code constants. These can be used with any method that accepts or returns a status code integer. However, keep in mind that these consants might include status codes that are now allowed which will throw an \InvalidArgumentException.

Parameters

int $code: The 3-digit integer status code to set.
string $reasonPhrase optional: The reason phrase to use with the provided status code; if none is provided, implementations MAY use the defaults as suggested in the HTTP specification.

Returns

static

Throws

InvalidArgumentException
For invalid status code arguments.

Links

https://tools.ietf.org/html/rfc7231#section-6

https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml

withStringBody() public

withStringBody(?string $string)

Convenience method to set a string into the response body

Parameters

string $string: The string to be sent

Returns

static

withType() public

withType(string $contentType)

Get an updated response with the content type set.

If you attempt to set the type on a 304 or 204 status code response, the content type will not take effect as these status codes do not have content-types.

Parameters

string $contentType: Either a file extension which will be mapped to a mime-type or a concrete mime-type.

Returns

static

withVary() public

withVary(mixed $cacheVariances)

Create a new instance with the Vary header set.

If an array is passed values will be imploded into a comma separated string. If no parameters are passed, then an array with the current Vary header value is returned

Parameters

string|array $cacheVariances: A single Vary string or an array containing the list for variances.

Returns

static

withoutHeader() public

withoutHeader(mixed $header)

Return an instance without the specified header.

Header resolution MUST be done without case-sensitivity.

This method MUST be implemented in such a way as to retain the immutability of the message, and MUST return an instance that removes the named header.

Parameters

string $header: Case-insensitive header field name to remove.

Returns

static

List of all registered headers, as key => array of values.

Type

array

© 2005–present The Cake Software Foundation, Inc.
Licensed under the MIT License.
CakePHP is a registered trademark of Cake Software Foundation, Inc.
We are not endorsed by or affiliated with CakePHP.
https://api.cakephp.org/4.1/class-Cake.Http.Response.html