On this page
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 constants might include status codes that are now allowed which will throw an \InvalidArgumentException.
Constants
-
intSTATUS_CODE_MAX599 -
intSTATUS_CODE_MIN100
Property Summary
-
$_cacheDirectives protected
array<string, mixed>Holds all the cache directives that will be converted into headers when sending the request
-
$_charset protected
stringThe charset the response body is encoded with
-
$_cookies protected
Cake\Http\Cookie\CookieCollectionCollection of cookies to send to the client
-
$_file protected
SplFileInfo|nullFile object for file to be read out as response
-
$_fileRange protected
array<int>File range. Used for requesting ranges of files.
-
$_mimeTypes protected
array<string, mixed>Holds type key to mime type mappings for known mime types.
-
$_reasonPhrase protected
stringReason Phrase
-
$_status protected
intStatus code to send to the client
-
$_statusCodes protected
array<int, string>Allowed HTTP status codes and their default description.
-
$_streamMode protected
stringStream mode options.
-
$_streamTarget protected
resource|stringStream target or resource object.
-
$headerNames protected
arrayMap of normalized header name to original name used to register header.
-
$headers protected
arrayList 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. Does not send headers. If body is a callable, a blank string is returned.
_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 deprecated
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.
isNotModified() 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.
mapType() public
Maps a content-type back to an alias
notModified() public deprecated
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<string, mixed> $options = [])
Constructor
Parameters
array<string, mixed>$options optional-
list of parameters to setup the response. Possible values are:
Throws
InvalidArgumentException__debugInfo() public
__debugInfo(): array<string, mixed>
Returns an array that can be used to describe the internal state of this object.
Returns
array<string, mixed>__toString() public
__toString(): string
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): void
Clear header
Parameters
string$header-
Header key.
Returns
void_createStream() protected
_createStream(): void
Creates the stream object.
Returns
void_fileRange() protected
_fileRange(SplFileInfo $file, string $httpRange): void
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.
Returns
void_getUTCDate() protected
_getUTCDate(DateTimeInterface|string|int|null $time = null): DateTimeInterface
Returns a DateTime object initialized at the $time param and using UTC as timezone
Parameters
DateTimeInterface|string|int|null$time optional-
Valid time string or \DateTimeInterface instance.
Returns
DateTimeInterface_setCacheControl() protected
_setCacheControl(): void
Helper method to generate a valid Cache-Control header from the options set in other methods
Returns
void_setContentType() protected
_setContentType(string $type): void
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.
Returns
void_setHeader() protected
_setHeader(string $header, string $value): void
Sets a header.
Parameters
string$header-
Header key.
string$value-
Header value.
Returns
void_setStatus() protected
_setStatus(int $code, string $reasonPhrase = ''): void
Modifier for response status
Parameters
int$code-
The status code to set.
string$reasonPhrase optional-
The response reason phrase.
Returns
voidThrows
InvalidArgumentExceptionFor invalid status code arguments.
checkNotModified() public
checkNotModified(Cake\Http\ServerRequest $request): bool
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
boolcompress() public
compress(): bool
Sets the correct output buffering handler to send a compressed response. Responses will be compressed with zlib, if the extension is available.
Returns
boolcors() public
cors(Cake\Http\ServerRequest $request): Cake\Http\CorsBuilder
Get a CorsBuilder instance for defining CORS headers.
Parameters
Cake\Http\ServerRequest$request-
Request object
Returns
Cake\Http\CorsBuildergetBody() public
getBody(): StreamInterface
Gets the body of the message.
Returns
StreamInterfacegetCharset() public
getCharset(): string
Returns the current charset.
Returns
stringgetCookie() public
getCookie(string $name): array|null
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|nullgetCookieCollection() public
getCookieCollection(): Cake\Http\Cookie\CookieCollection
Get the CookieCollection from the response
Returns
Cake\Http\Cookie\CookieCollectiongetCookies() public
getCookies(): array<string, array>
Get all cookies in the response.
Returns an associative array of cookie name => cookie data.
Returns
array<string, array>getFile() public
getFile(): SplFileInfo|null
Get the current file if one exists.
Returns
SplFileInfo|nullgetHeader() public
getHeader(string $header): string[]
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[]getHeaderLine() public
getHeaderLine(string $name): string
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
stringgetHeaders() public
getHeaders(): array
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
arraygetMimeType() public
getMimeType(string $alias): array|string|false
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
array|string|falsegetProtocolVersion() public
getProtocolVersion(): string
Retrieves the HTTP protocol version as a string.
The string MUST contain only the HTTP version number (e.g., "1.1", "1.0").
Returns
stringgetReasonPhrase() public
getReasonPhrase(): string
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
stringLinks
https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml
getStatusCode() public
getStatusCode(): int
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
intgetType() public
getType(): string
Returns the current content type.
Returns
stringhasHeader() public
hasHeader(string $header): bool
Checks if a header exists by the given case-insensitive name.
Parameters
string$header-
Case-insensitive header name.
Returns
boolisNotModified() public
isNotModified(Cake\Http\ServerRequest $request): bool
Checks whether a response has not been modified according to the 'If-None-Match' (Etags) and 'If-Modified-Since' (last modification date) request headers.
In order to interact with this method you must mark responses as not modified. You need to set at least one of the Last-Modified or Etag response headers before calling this method. Otherwise, a comparison will not be possible.
Parameters
Cake\Http\ServerRequest$request-
Request object
Returns
boolmapType() public
mapType(array|string $ctype): array|string|null
Maps a content-type back to an alias
e.g mapType('application/pdf'); // returns 'pdf'
Parameters
array|string$ctype-
Either a string content type to map, or an array of types.
Returns
array|string|nullnotModified() public
notModified(): void
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.
Returns
voidoutputCompressed() public
outputCompressed(): bool
Returns whether the resulting output will be compressed by PHP
Returns
boolresolveType() protected
resolveType(string $contentType): string
Translate and validate content-types.
Parameters
string$contentType-
The content-type or type alias.
Returns
stringThrows
InvalidArgumentExceptionWhen an invalid content-type or alias is used.
setTypeMap() public
setTypeMap(string $type, array<string>|string $mimeType): void
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.
array<string>|string$mimeType-
Definition of the mime type.
Returns
voidvalidateFile() protected
validateFile(string $path): SplFileInfo
Validate a file path is a valid response body.
Parameters
string$path-
The path to the file.
Returns
SplFileInfoThrows
Cake\Http\Exception\NotFoundExceptionwithAddedHeader() public
withAddedHeader(string $name, string|string[] $value): static
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$name-
Case-insensitive header field name to add.
string|string[]$value-
Header value(s).
Returns
staticThrows
Exception\InvalidArgumentExceptionFor invalid header names or values.
withAddedLink() public
withAddedLink(string $url, array<string, mixed> $options = []): static
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<string, mixed>$options optional-
The LinkHeader params.
Returns
staticwithBody() public
withBody(StreamInterface $body): static
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
StreamInterface$body-
Body.
Returns
staticThrows
Exception\InvalidArgumentExceptionWhen the body is not valid.
withCache() public
withCache(string|int $since, string|int $time = '+1 day'): static
Create a new instance with the headers to enable client caching.
Parameters
string|int$since-
a valid time since the response text has not been modified
string|int$time optional-
a valid time for cache expiry
Returns
staticwithCharset() public
withCharset(string $charset): static
Get a new instance with an updated charset.
Parameters
string$charset-
Character set string.
Returns
staticwithCookie() public
withCookie(Cake\Http\Cookie\CookieInterface $cookie): static
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
staticwithCookieCollection() public
withCookieCollection(Cake\Http\Cookie\CookieCollection $cookieCollection): static
Get a new instance with provided cookie collection.
Parameters
Cake\Http\Cookie\CookieCollection$cookieCollection-
Cookie collection to set.
Returns
staticwithDisabledCache() public
withDisabledCache(): static
Create a new instance with headers to instruct the client to not cache the response
Returns
staticwithDownload() public
withDownload(string $filename): static
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
staticwithEtag() public
withEtag(string $hash, bool $weak = false): static
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
staticwithExpiredCookie() public
withExpiredCookie(Cake\Http\Cookie\CookieInterface $cookie): static
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
staticwithExpires() public
withExpires(DateTimeInterface|string|int|null $time): static
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
DateTimeInterface|string|int|null$time-
Valid time string or \DateTime instance.
Returns
staticwithFile() public
withFile(string $path, array<string, mixed> $options = []): static
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
truesets download header and forces file to be downloaded rather than displayed inline.
Parameters
string$path-
Absolute path to file.
array<string, mixed>$options optional-
Options See above.
Returns
staticThrows
Cake\Http\Exception\NotFoundExceptionwithHeader() public
withHeader(string $name, string|string[] $value): static
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$name-
Case-insensitive header field name.
string|string[]$value-
Header value(s).
Returns
staticThrows
Exception\InvalidArgumentExceptionFor invalid header names or values.
withLength() public
withLength(string|int $bytes): static
Create a new response with the Content-Length header set.
Parameters
string|int$bytes-
Number of bytes
Returns
staticwithLocation() public
withLocation(string $url): static
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
staticwithMaxAge() public
withMaxAge(int $seconds): static
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
staticwithModified() public
withModified(DateTimeInterface|string|int $time): static
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
DateTimeInterface|string|int$time-
Valid time string or \DateTime instance.
Returns
staticwithMustRevalidate() public
withMustRevalidate(bool $enable): static
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
staticwithNotModified() public
withNotModified(): static
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
staticwithProtocolVersion() public
withProtocolVersion(string $version): static
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
staticwithSharable() public
withSharable(bool $public, int|null $time = null): static
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
staticwithSharedMaxAge() public
withSharedMaxAge(int $seconds): static
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
staticwithStatus() public
withStatus(int $code, string $reasonPhrase = ''): static
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 constants 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
staticThrows
InvalidArgumentExceptionFor invalid status code arguments.
Links
https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml
withStringBody() public
withStringBody(string|null $string): static
Convenience method to set a string into the response body
Parameters
string|null$string-
The string to be sent
Returns
staticwithType() public
withType(string $contentType): static
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
staticwithVary() public
withVary(array<string>|string $cacheVariances): static
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
array<string>|string$cacheVariances-
A single Vary string or an array containing the list for variances.
Returns
staticwithoutHeader() public
withoutHeader(string $name): static
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$name-
Case-insensitive header field name to remove.
Returns
staticProperty Detail
$_cacheDirectives protected
Holds all the cache directives that will be converted into headers when sending the request
Type
array<string, mixed>$_charset protected
The charset the response body is encoded with
Type
string$_cookies protected
Collection of cookies to send to the client
Type
Cake\Http\Cookie\CookieCollection$_file protected
File object for file to be read out as response
Type
SplFileInfo|null$_fileRange protected
File range. Used for requesting ranges of files.
Type
array<int>$_mimeTypes protected
Holds type key to mime type mappings for known mime types.
Type
array<string, mixed>$_reasonPhrase protected
Reason Phrase
Type
string$_status protected
Status code to send to the client
Type
int$_statusCodes protected
Allowed HTTP status codes and their default description.
Type
array<int, string>$_streamMode protected
Stream mode options.
Type
string$_streamTarget protected
Stream target or resource object.
Type
resource|string$headerNames protected
Map of normalized header name to original name used to register header.
Type
array$headers protected
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.4/class-Cake.Http.Response.html