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
.
int
599
int
100
array<string, mixed>
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<int>
File range. Used for requesting ranges of files.
array<string, mixed>
Holds type key to mime type mappings for known mime types.
string
Reason Phrase
int
Status code to send to the client
array<int, string>
Allowed HTTP status codes and their default description.
string
Stream mode options.
resource|string
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.
Constructor
Returns an array that can be used to describe the internal state of this object.
String conversion. Fetches the response body as a string. Does not send headers. If body is a callable, a blank string is returned.
Clear header
Creates the stream object.
Apply a file range to a file and set the end offset.
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/*
Sets a header.
Modifier for response status
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.
Get a CorsBuilder instance for defining CORS headers.
Gets the body of the message.
Returns the current charset.
Read a single cookie from the response.
Get the CookieCollection from the response
Get all cookies in the response.
Get the current file if one exists.
Retrieves a message header value by the given case-insensitive name.
Retrieves a comma-separated string of the values for a single header.
Retrieves all message headers.
Returns the mime type definition for an alias
Retrieves the HTTP protocol version as a string.
Gets the response reason phrase associated with the status code.
Gets the response status code.
Returns the current content type.
Checks if a header exists by the given case-insensitive name.
Checks whether a response has not been modified according to the 'If-None-Match' (Etags) and 'If-Modified-Since' (last modification date) request headers.
Maps a content-type back to an alias
Sets the response as Not Modified by removing any body contents setting the status code to "304 Not Modified" and removing all conflicting headers
Returns whether the resulting output will be compressed by PHP
Translate and validate content-types.
Sets a content type definition into the map.
Validate a file path is a valid response body.
Return an instance with the specified header appended with the given value.
Create a new response with the Link header set.
Return an instance with the specified message body.
Create a new instance with the headers to enable client caching.
Get a new instance with an updated charset.
Create a new response with a cookie set.
Get a new instance with provided cookie collection.
Create a new instance with headers to instruct the client to not cache the response
Create a new instance with the Content-Disposition header set.
Create a new instance with the Etag header set.
Create a new response with an expired cookie set.
Create a new instance with the Expires header set.
Create a new instance that is based on a file.
Return an instance with the provided header, replacing any existing values of any headers with the same case-insensitive name.
Create a new response with the Content-Length header set.
Return an instance with an updated location header.
Create an instance with Cache-Control max-age directive set.
Create a new instance with the Last-Modified header set.
Create an instance with Cache-Control must-revalidate directive set.
Create a new instance as 'not modified'
Return an instance with the specified HTTP protocol version.
Create a new instace with the public/private Cache-Control directive set.
Create a new instance with the Cache-Control s-maxage directive.
Return an instance with the specified status code and, optionally, reason phrase.
Convenience method to set a string into the response body
Get an updated response with the content type set.
Create a new instance with the Vary header set.
Return an instance without the specified header.
__construct(array<string, mixed> $options = [])
Constructor
array<string, mixed>
$options optional list of parameters to setup the response. Possible values are:
InvalidArgumentException
__debugInfo(): array<string, mixed>
Returns an array that can be used to describe the internal state of this object.
array<string, mixed>
__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.
string
_clearHeader(string $header): void
Clear header
string
$header Header key.
void
_createStream(): void
Creates the stream object.
void
_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.
SplFileInfo
$file The file to set a range on.
string
$httpRange The range to use.
void
_getUTCDate(DateTimeInterface|string|int|null $time = null): DateTimeInterface
Returns a DateTime object initialized at the $time param and using UTC as timezone
DateTimeInterface|string|int|null
$time optional Valid time string or \DateTimeInterface instance.
DateTimeInterface
_setCacheControl(): void
Helper method to generate a valid Cache-Control header from the options set in other methods
void
_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/*
string
$type The type to set.
void
_setHeader(string $header, string $value): void
Sets a header.
string
$header Header key.
string
$value Header value.
void
_setStatus(int $code, string $reasonPhrase = ''): void
Modifier for response status
int
$code The status code to set.
string
$reasonPhrase optional The response reason phrase.
void
InvalidArgumentException
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.
Cake\Http\ServerRequest
$request Request object
bool
compress(): bool
Sets the correct output buffering handler to send a compressed response. Responses will be compressed with zlib, if the extension is available.
bool
cors(Cake\Http\ServerRequest $request): Cake\Http\CorsBuilder
Get a CorsBuilder instance for defining CORS headers.
Cake\Http\ServerRequest
$request Request object
Cake\Http\CorsBuilder
getBody(): StreamInterface
Gets the body of the message.
StreamInterface
getCharset(): string
Returns the current charset.
string
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.
string
$name The cookie name you want to read.
array|null
getCookieCollection(): Cake\Http\Cookie\CookieCollection
Get the CookieCollection from the response
Cake\Http\Cookie\CookieCollection
getCookies(): array<string, array>
Get all cookies in the response.
Returns an associative array of cookie name => cookie data.
array<string, array>
getFile(): SplFileInfo|null
Get the current file if one exists.
SplFileInfo|null
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.
string
$header Case-insensitive header field name.
string[]
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.
string
$name Case-insensitive header field name.
string
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); } }
array
getMimeType(string $alias): array|string|false
Returns the mime type definition for an alias
e.g getMimeType('pdf'); // returns 'application/pdf'
string
$alias the content type alias to map
array|string|false
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").
string
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.
string
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.
int
getType(): string
Returns the current content type.
string
hasHeader(string $header): bool
Checks if a header exists by the given case-insensitive name.
string
$header Case-insensitive header name.
bool
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.
Cake\Http\ServerRequest
$request Request object
bool
mapType(array|string $ctype): array|string|null
Maps a content-type back to an alias
e.g mapType('application/pdf'); // returns 'pdf'
array|string
$ctype Either a string content type to map, or an array of types.
array|string|null
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.
void
outputCompressed(): bool
Returns whether the resulting output will be compressed by PHP
bool
resolveType(string $contentType): string
Translate and validate content-types.
string
$contentType The content-type or type alias.
string
InvalidArgumentException
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.
string
$type Content type.
array<string>|string
$mimeType Definition of the mime type.
void
validateFile(string $path): SplFileInfo
Validate a file path is a valid response body.
string
$path The path to the file.
SplFileInfo
Cake\Http\Exception\NotFoundException
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.
string
$name Case-insensitive header field name to add.
string|string[]
$value Header value(s).
static
Exception\InvalidArgumentException
withAddedLink(string $url, array<string, mixed> $options = []): static
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<string, mixed>
$options optional The LinkHeader params.
static
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.
StreamInterface
$body Body.
static
Exception\InvalidArgumentException
withCache(string|int $since, string|int $time = '+1 day'): static
Create a new instance with the headers to enable client caching.
string|int
$since a valid time since the response text has not been modified
string|int
$time optional a valid time for cache expiry
static
withCharset(string $charset): static
Get a new instance with an updated charset.
string
$charset Character set string.
static
withCookie(Cake\Http\Cookie\CookieInterface $cookie): static
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): static
Get a new instance with provided cookie collection.
Cake\Http\Cookie\CookieCollection
$cookieCollection Cookie collection to set.
static
withDisabledCache(): static
Create a new instance with headers to instruct the client to not cache the response
static
withDownload(string $filename): static
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 = 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.
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): static
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(DateTimeInterface|string|int|null $time): static
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'))
DateTimeInterface|string|int|null
$time Valid time string or \DateTime instance.
static
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.
true
sets download header and forces file to be downloaded rather than displayed inline.string
$path Absolute path to file.
array<string, mixed>
$options optional Options See above.
static
Cake\Http\Exception\NotFoundException
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.
string
$name Case-insensitive header field name.
string|string[]
$value Header value(s).
static
Exception\InvalidArgumentException
withLength(string|int $bytes): static
Create a new response with the Content-Length header set.
string|int
$bytes Number of bytes
static
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.
string
$url The location to redirect to.
static
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.
int
$seconds The seconds a cached response can be considered valid
static
withModified(DateTimeInterface|string|int $time): static
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'))
DateTimeInterface|string|int
$time Valid time string or \DateTime instance.
static
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.
bool
$enable If boolean sets or unsets the directive.
static
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.
static
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.
string
$version HTTP protocol version
static
withSharable(bool $public, int|null $time = null): static
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): 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).
int
$seconds The number of seconds for shared max-age
static
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
.
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|null $string): static
Convenience method to set a string into the response body
string|null
$string The string to be sent
static
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.
string
$contentType Either a file extension which will be mapped to a mime-type or a concrete mime-type.
static
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
array<string>|string
$cacheVariances A single Vary string or an array containing the list for variances.
static
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.
string
$name Case-insensitive header field name to remove.
static
Holds all the cache directives that will be converted into headers when sending the request
array<string, mixed>
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<int>
Holds type key to mime type mappings for known mime types.
array<string, mixed>
Reason Phrase
string
Status code to send to the client
int
Allowed HTTP status codes and their default description.
array<int, string>
Stream mode options.
string
Stream target or resource object.
resource|string
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.4/class-Cake.Http.Response.html