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
.
int
599
int
100
array
Holds all the cache directives that will be converted into headers when sending the request
string
The charset the response body is encoded with
\Cake\Http\Cookie\CookieCollection
Collection of cookies to send to the client
\SplFileInfo|null
File object for file to be read out as response
array
File range. Used for requesting ranges of files.
array
Holds type key to mime type mappings for known mime types.
string
Reason Phrase
int
Status code to send to the client
string[]
Allowed HTTP status codes and their default description.
string
Stream mode options.
string|resource
Stream target or resource object.
array
Map of normalized header name to original name used to register header.
array
List of all registered headers, as key => array of values.
Returns an array that can be used to describe the internal state of this object.
Returns a DateTime object initialized at the $time param and using UTC as timezone
Helper method to generate a valid Cache-Control header from the options set in other methods
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/*
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.
Sets the correct output buffering handler to send a compressed response. Responses will be compressed with zlib, if the extension is available.
Sets the response as Not Modified by removing any body contents setting the status code to "304 Not Modified" and removing all conflicting headers
Return an instance with the specified header appended with the given value.
Create a new instance with headers to instruct the client to not cache the response
Return an instance with the provided header, replacing any existing values of any headers with the same case-insensitive name.
Return an instance with the specified status code and, optionally, reason phrase.
__construct(array $options)
Constructor
array
$options optional list of parameters to setup the response. Possible values are:
InvalidArgumentException
__debugInfo()
Returns an array that can be used to describe the internal state of this object.
array
__toString()
String conversion. Fetches the response body as a string.
Does not send headers. If body is a callable, a blank string is returned.
string
_clearHeader(string $header)
Clear header
string
$header Header key.
_createStream()
Creates the stream object.
_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.
\SplFileInfo
$file The file to set a range on.
string
$httpRange The range to use.
_getUTCDate(mixed $time)
Returns a DateTime object initialized at the $time param and using UTC as timezone
string|int|\DateTimeInterface|null
$time optional Valid time string or \DateTimeInterface instance.
\DateTimeInterface
_setCacheControl()
Helper method to generate a valid Cache-Control header from the options set in other methods
_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/*
string
$type The type to set.
_setHeader(string $header, string $value)
Sets a header.
string
$header Header key.
string
$value Header value.
_setStatus(int $code, string $reasonPhrase)
Modifier for response status
int
$code The status code to set.
string
$reasonPhrase optional The response reason phrase.
InvalidArgumentException
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.
\Cake\Http\ServerRequest
$request Request object
bool
Whether the response was marked as not modified or not.
compress()
Sets the correct output buffering handler to send a compressed response. Responses will be compressed with zlib, if the extension is available.
bool
false if client does not accept compressed responses or no handler is available, true otherwise
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
cors($request, 'https://www.cakephp.org');
cors($request, 'https://*.cakephp.org');
cors($request, 'www.cakephp.org');
cors($request, '*');
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.
\Cake\Http\ServerRequest
$request Request object
\Cake\Http\CorsBuilder
A builder object the provides a fluent interface for defining additional CORS headers.
getBody()
Gets the body of the message.
\Psr\Http\Message\StreamInterface
Returns the body as a stream.
getCharset()
Returns the current charset.
string
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.
string
$name The cookie name you want to read.
array|null
Either the cookie data or null
getCookieCollection()
Get the CookieCollection from the response
\Cake\Http\Cookie\CookieCollection
getCookies()
Get all cookies in the response.
Returns an associative array of cookie name => cookie data.
array
getFile()
Get the current file if one exists.
\SplFileInfo|null
The file to use in the response or null
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.
string
$header Case-insensitive header field name.
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(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.
string
$name Case-insensitive header field name.
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()
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); } }
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(string $alias)
Returns the mime type definition for an alias
e.g getMimeType('pdf'); // returns 'application/pdf'
string
$alias the content type alias to map
string|array|false
String mapped mime type or false if $alias is not mapped
getProtocolVersion()
Retrieves the HTTP protocol version as a string.
The string MUST contain only the HTTP version number (e.g., "1.1", "1.0").
string
HTTP protocol version.
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.
string
Reason phrase; must return an empty string if none present.
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.
int
Status code.
getType()
Returns the current content type.
string
hasHeader(mixed $header)
Checks if a header exists by the given case-insensitive name.
string
$header Case-insensitive header name.
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(mixed $ctype)
Maps a content-type back to an alias
e.g mapType('application/pdf'); // returns 'pdf'
string|array
$ctype Either a string content type to map, or an array of types.
string|array|null
Aliases for the types provided.
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()
Returns whether the resulting output will be compressed by PHP
bool
resolveType(string $contentType)
Translate and validate content-types.
string
$contentType The content-type or type alias.
string
The resolved content-type
InvalidArgumentException
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.
string
$type Content type.
string|array
$mimeType Definition of the mime type.
validateFile(string $path)
Validate a file path is a valid response body.
string
$path The path to the file.
\SplFileInfo
Cake\Http\Exception\NotFoundException
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.
string
$header Case-insensitive header field name to add.
string|string[]
$value Header value(s).
static
Laminas\Diactoros\Exception\InvalidArgumentException
withAddedLink(string $url, array $options)
Create a new response with the Link header set.
$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"
string
$url The LinkHeader url.
array
$options optional The LinkHeader params.
static
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.
\Psr\Http\Message\StreamInterface
$body Body.
static
Laminas\Diactoros\Exception\InvalidArgumentException
withCache(mixed $since, mixed $time)
Create a new instance with the headers to enable client caching.
int|string
$since a valid time since the response text has not been modified
int|string
$time optional a valid time for cache expiry
static
withCharset(string $charset)
Get a new instance with an updated charset.
string
$charset Character set string.
static
withCookie(\Cake\Http\Cookie\CookieInterface $cookie)
Create a new response with a cookie set.
// add a cookie object $response = $response->withCookie(new Cookie('remember_me', 1));
\Cake\Http\Cookie\CookieInterface
$cookie cookie object
static
withCookieCollection(\Cake\Http\Cookie\CookieCollection $cookieCollection)
Get a new instance with provided cookie collection.
\Cake\Http\Cookie\CookieCollection
$cookieCollection Cookie collection to set.
static
withDisabledCache()
Create a new instance with headers to instruct the client to not cache the response
static
withDownload(string $filename)
Create a new instance with the Content-Disposition header set.
string
$filename The name of the file as the browser will download the response
static
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.
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
static
withExpiredCookie(\Cake\Http\Cookie\CookieInterface $cookie)
Create a new response with an expired cookie set.
// add a cookie object $response = $response->withExpiredCookie(new Cookie('remember_me'));
\Cake\Http\Cookie\CookieInterface
$cookie cookie object
static
withExpires(mixed $time)
Create a new instance with the Expires header set.
// Will Expire the response cache now $response->withExpires('now') // Will set the expiration in next 24 hours $response->withExpires(new DateTime('+1 day'))
string|int|\DateTimeInterface|null
$time Valid time string or \DateTime instance.
static
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.
true
sets download header and forces file to be downloaded rather than displayed inline.string
$path Absolute path to file.
array
$options optional Options See above.
static
Cake\Http\Exception\NotFoundException
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.
string
$header Case-insensitive header field name.
string|string[]
$value Header value(s).
static
Laminas\Diactoros\Exception\InvalidArgumentException
withLength(mixed $bytes)
Create a new response with the Content-Length header set.
int|string
$bytes Number of bytes
static
withLocation(string $url)
Return an instance with an updated location header.
If the current status code is 200, it will be replaced with 302.
string
$url The location to redirect to.
static
A new response with the Location header set.
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.
int
$seconds The seconds a cached response can be considered valid
static
withModified(mixed $time)
Create a new instance with the Last-Modified header set.
// Will Expire the response cache now $response->withModified('now') // Will set the expiration in next 24 hours $response->withModified(new DateTime('+1 day'))
int|string|\DateTimeInterface
$time Valid time string or \DateTime instance.
static
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.
bool
$enable If boolean sets or unsets the directive.
static
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.
static
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.
string
$version HTTP protocol version
static
withSharable(bool $public, ?int $time)
Create a new instace with the public/private Cache-Control directive set.
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.
static
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).
int
$seconds The number of seconds for shared max-age
static
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
.
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.
static
InvalidArgumentException
withStringBody(?string $string)
Convenience method to set a string into the response body
string
$string The string to be sent
static
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.
string
$contentType Either a file extension which will be mapped to a mime-type or a concrete mime-type.
static
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
string|array
$cacheVariances A single Vary string or an array containing the list for variances.
static
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.
string
$header Case-insensitive header field name to remove.
static
Holds all the cache directives that will be converted into headers when sending the request
array
The charset the response body is encoded with
string
Collection of cookies to send to the client
\Cake\Http\Cookie\CookieCollection
File object for file to be read out as response
\SplFileInfo|null
File range. Used for requesting ranges of files.
array
Holds type key to mime type mappings for known mime types.
array
Reason Phrase
string
Status code to send to the client
int
Allowed HTTP status codes and their default description.
string[]
Stream mode options.
string
Stream target or resource object.
string|resource
Map of normalized header name to original name used to register header.
array
List of all registered headers, as key => array of values.
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