Class Response
A response class intended for test cases.
Constants summary
-
int
STATUS_CODE_MAX599
-
int
STATUS_CODE_MIN100
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
\Cake\Filesystem\File|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.
- $_protocol protected
string
Protocol header to send to the client
- $_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
- __debugInfo() public
Returns an array that can be used to describe the internal state of this object.
- _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/*
- _setCookies() protected
Sets the cookies that have been added via Cake\Http\Response::cookie() before any other output is sent to the client. Will set the cookies in the order they have been set.
- body() public
Buffers the response message to be sent if $content is null the current buffer is returned
- 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.
- download() public
Sets the correct headers to instruct the browser to download the response as a file.
- etag() public
Sets the response Etag, 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 makes it unique.
- expires() public
Sets the Expires header for the response by taking an expiration time If called with no parameters it will return the current Expires value
- length() public
Sets the Content-Length header for the response If called with no arguments returns the last Content-Length set
- modified() public
Sets the Last-Modified header for the response by taking a modification time If called with no parameters it will return the current Last-Modified value
- 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
- protocol() public
Sets the protocol to be used when sending the response. Defaults to HTTP/1.1 If called with no arguments, it will return the current configured protocol
- sharable() public
Sets whether a response is eligible to be cached by intermediate proxies This method controls the
public
orprivate
directive in the Cache-Control header - type() public
Sets the response content type. It can be either a file extension which will be mapped internally to a mime-type or a string representing a mime-type if $contentType is null the current content type is returned if $contentType is an associative array, content type definitions will be stored/replaced
- vary() public
Sets the Vary header for the response, 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
- withAddedHeader() public
Return an instance with the specified header appended with the given value.
- withDisabledCache() public
Create a new instance with headers to instruct the client to not cache the response
- withHeader() public
Return an instance with the provided header, replacing any existing values of any headers with the same case-insensitive name.
- withStatus() public
Return an instance with the specified status code and, optionally, reason phrase.
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
- statusCodes: additional allowable response codes
- 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
_clearBuffer() protected
_clearBuffer()
Clears the contents of the topmost output buffer and discards them
Returns
bool
_clearHeader() protected
_clearHeader(mixed $header)
Clear header
Parameters
-
string
$header Header key.
_createStream() protected
_createStream()
Creates the stream object.
_fileRange() protected
_fileRange(mixed $file, mixed $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
-
\Cake\Filesystem\File
$file The file to set a range on.
-
string
$httpRange The range to use.
_flushBuffer() protected
_flushBuffer()
Flushes the contents of the output buffer
_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
_handleCallableBody() protected
_handleCallableBody(callable $content)
Handles the callable body for backward compatibility reasons.
Parameters
-
callable
$content Callable content.
Returns
string
_isActive() protected
_isActive()
Returns true if connection is still active
Returns
bool
_sendContent() protected
_sendContent(mixed $content)
Sends a content string to the client.
If the content is a callable, it is invoked. The callable should either return a string or output content directly and have no return value.
Parameters
-
string|callable
$content String to send as response body or callable which returns/outputs content.
_sendFile() protected
_sendFile(mixed $file, mixed $range)
Reads out a file, and echos the content to the client.
Parameters
-
\Cake\Filesystem\File
$file File object
-
array
$range The range to read out of the file.
Returns
bool
True is whole file is echoed successfully or false if client connection is lost in between
_sendHeader() protected
_sendHeader(mixed $name, mixed $value)
Sends a header to the client.
Parameters
-
string
$name the header name
-
string|null
$value optional the header value
_setCacheControl() protected
_setCacheControl()
Helper method to generate a valid Cache-Control header from the options set in other methods
_setContent() protected
_setContent()
Sets the response body to an empty text if the status code is 204 or 304
_setContentType() protected
_setContentType(mixed $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.
_setCookies() protected
_setCookies()
Sets the cookies that have been added via Cake\Http\Response::cookie() before any other output is sent to the client. Will set the cookies in the order they have been set.
_setHeader() protected
_setHeader(mixed $header, mixed $value)
Sets a header.
Parameters
-
string
$header Header key.
-
string
$value Header value.
_setStatus() protected
_setStatus(mixed $code, mixed $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.
body() public
body(mixed $content)
Buffers the response message to be sent if $content is null the current buffer is returned
Parameters
-
string|callable|null
$content optional the string or callable message to be sent
Returns
string|null
Current message buffer if $content param is passed as null
cache() public
cache(mixed $since, mixed $time)
Sets the correct headers to instruct the client to cache the response.
Parameters
-
string|int|\DateTimeInterface|null
$since a valid time since the response text has not been modified
-
string|int
$time optional a valid time for cache expiry
Throws
InvalidArgumentException
charset() public
charset(mixed $charset)
Sets the response charset if $charset is null the current charset is returned
Parameters
-
string|null
$charset optional Character set string.
Returns
string
Current charset
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
convertCookieToArray() protected
convertCookieToArray(\Cake\Http\Cookie\CookieInterface $cookie)
Convert the cookie into an array of its properties.
This method is compatible with the historical behavior of Cake\Http\Response, where httponly
is httpOnly
and expires
is expire
Parameters
-
\Cake\Http\Cookie\CookieInterface
$cookie Cookie object.
Returns
array
cookie() public
cookie(mixed $options)
Getter/Setter for cookie configs
This method acts as a setter/getter depending on the type of the argument. If the method is called with no arguments, it returns all configurations.
If the method is called with a string as argument, it returns either the given configuration if it is set, or null, if it's not set.
If the method is called with an array as argument, it will set the cookie configuration to the cookie container.
Options (when setting a configuration)
- name: The Cookie name
- value: Value of the cookie
- expire: Time the cookie expires in
- path: Path the cookie applies to
- domain: Domain the cookie is for.
- secure: Is the cookie https?
- httpOnly: Is the cookie available in the client?
Examples
Getting all cookies
$this->cookie()
Getting a certain cookie configuration
$this->cookie('MyCookie')
Setting a cookie configuration
$this->cookie((array) $options)
Parameters
-
array|null
$options optional Either null to get all cookies, string for a specific cookie or array to set cookie.
Returns
mixed
cors() public
cors(\Cake\Http\ServerRequest $request, mixed $allowedDomains, mixed $allowedMethods, mixed $allowedHeaders)
Setup access for origin and methods on cross origin requests
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, '*');
Whitelist 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
-
string|string[]
$allowedDomains optional List of allowed domains, see method description for more details
-
string|string[]
$allowedMethods optional List of HTTP verbs allowed
-
string|string[]
$allowedHeaders optional List of HTTP headers allowed
Returns
\Cake\Http\CorsBuilder
A builder object the provides a fluent interface for defining additional CORS headers.
disableCache() public
disableCache()
Sets the correct headers to instruct the client to not cache the response
download() public
download(mixed $filename)
Sets the correct headers to instruct the browser to download the response as a file.
Parameters
-
string
$filename The name of the file as the browser will download the response
etag() public
etag(mixed $hash, mixed $weak)
Sets the response Etag, 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 makes it unique.
Second parameter is used to instruct clients that the content has changed, but semantically, it can be used as the same thing. Think for instance of a page with a hit counter, two different page views are equivalent, but they differ by a few bytes. This leaves off to the Client the decision of using or not the cached page.
If no parameters are passed, current Etag header is returned.
Parameters
-
string|null
$hash optional 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
Returns
string|null
expires() public
expires(mixed $time)
Sets the Expires header for the response by taking an expiration time If called with no parameters it will return the current Expires value
Examples:
$response->expires('now')
Will Expire the response cache now $response->expires(new DateTime('+1 day'))
Will set the expiration in next 24 hours $response->expires()
Will return the current expiration header value
Parameters
-
string|int|\DateTimeInterface|null
$time optional Valid time string or \DateTime instance.
Returns
string|null
file() public
file(mixed $path, array $options)
Setup for display or download the given file.
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 in browser
Parameters
-
string
$path Path to file. If the path is not an absolute path that resolves to a file,
APP
will be prepended to the path (this behavior is deprecated).-
array
$options optional Options See above.
Throws
Cake\Http\Exception\NotFoundException
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(mixed $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
\Cake\Filesystem\File|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(mixed $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
getSimpleHeaders() protected
getSimpleHeaders()
Backwards compatibility helper for getting flattened headers.
Previously CakePHP would store headers as a simple dictionary, now that we're supporting PSR7, the internal storage has each header as an array.
Returns
array
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.
header() public
header(mixed $header, mixed $value)
Buffers a header string to be sent Returns the complete list of buffered headers
Single header
header('Location', 'http://example.com');
Multiple headers
header(['Location' => 'http://example.com', 'X-Extra' => 'My header']);
String header
header('WWW-Authenticate: Negotiate');
Array of string headers
header(['WWW-Authenticate: Negotiate', 'Content-type: application/pdf']);
Multiple calls for setting the same header name will have the same effect as setting the header once with the last value sent for it
header('WWW-Authenticate: Negotiate'); header('WWW-Authenticate: Not-Negotiate');
will have the same effect as only doing
header('WWW-Authenticate: Not-Negotiate');
Parameters
-
string|array|null
$header optional -
An array of header strings or a single header string
- an associative array of "header name" => "header value" is also accepted
- an array of string headers is also accepted
-
string|array|null
$value optional The header value(s)
Returns
array
List of headers to be sent
httpCodes() public
httpCodes(mixed $code)
Queries & sets valid HTTP response codes & messages.
Parameters
-
int|array|null
$code optional -
If $code is an integer, then the corresponding code/message is returned if it exists, null if it does not exist. If $code is an array, then the keys are used as codes and the values as messages to add to the default HTTP codes. The codes must be integers greater than 99 and less than 1000. Keep in mind that the HTTP specification outlines that status codes begin with a digit between 1 and 5, which defines the class of response the client is to expect. Example:
httpCodes(404); // returns [404 => 'Not Found']
httpCodes([ 381 => 'Unicorn Moved', 555 => 'Unexpected Minotaur' ]); // sets these new values, and returns true
httpCodes([ 0 => 'Nothing Here', -1 => 'Reverse Infinity', 12345 => 'Universal Password', 'Hello' => 'World' ]); // throws an exception due to invalid codes
For more on HTTP status codes see: http://www.w3.org/Protocols/rfc2616/rfc2616-sec6.html#sec6.1
Returns
mixed
Associative array of the HTTP codes as keys, and the message strings as values, or null of the given $code does not exist.
Throws
InvalidArgumentException
If an attempt is made to add an invalid status code
length() public
length(mixed $bytes)
Sets the Content-Length header for the response If called with no arguments returns the last Content-Length set
Parameters
-
int|null
$bytes optional Number of bytes
Returns
string|null
location() public
location(mixed $url)
Accessor for the location header.
Get/Set the Location header value.
Parameters
-
string|null
$url optional Either null to get the current location, or a string to set one.
Returns
string|null
When setting the location null will be returned. When reading the location a string of the current location header value (if any) will be returned.
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.
maxAge() public
maxAge(mixed $seconds)
Sets the Cache-Control max-age 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 the local (client) cache. If called with no parameters, this function will return the current max-age value if any
Parameters
-
int|null
$seconds optional if null, the method will return the current max-age value
Returns
int|null
modified() public
modified(mixed $time)
Sets the Last-Modified header for the response by taking a modification time If called with no parameters it will return the current Last-Modified value
Examples:
$response->modified('now')
Will set the Last-Modified to the current time $response->modified(new DateTime('+1 day'))
Will set the modification date in the past 24 hours $response->modified()
Will return the current Last-Modified header value
Parameters
-
string|int|\DateTimeInterface|null
$time optional Valid time string or \DateTime instance.
Returns
string|null
mustRevalidate() public
mustRevalidate(mixed $enable)
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. If called with no parameters, this function will return whether must-revalidate is present.
Parameters
-
bool|null
$enable optional if null, the method will return the current must-revalidate value. If boolean sets or unsets the directive.
Returns
bool
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
protocol() public
protocol(mixed $protocol)
Sets the protocol to be used when sending the response. Defaults to HTTP/1.1 If called with no arguments, it will return the current configured protocol
Parameters
-
string|null
$protocol optional Protocol to be used for sending response.
Returns
string
Protocol currently set
resolveType() protected
resolveType(mixed $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.
send() public
send()
Stub the send() method so headers and output are not sent.
Returns
$this
sendHeaders() public
sendHeaders()
Sends the HTTP headers and cookies.
setTypeMap() public
setTypeMap(mixed $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.
sharable() public
sharable(mixed $public, mixed $time)
Sets whether a response is eligible to be cached by intermediate proxies This method controls the public
or private
directive in the Cache-Control header
Parameters
-
bool|null
$public optional If set to true, the Cache-Control header will be set as public if set to false, the response will be set to private if no value is provided, it will return whether the response is sharable or not
-
int|null
$time optional time in seconds after which the response should no longer be considered fresh
Returns
bool|null
sharedMaxAge() public
sharedMaxAge(mixed $seconds)
Sets 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). If called with no parameters, this function will return the current max-age value if any
Parameters
-
int|null
$seconds optional if null, the method will return the current s-maxage value
Returns
int|null
statusCode() public
statusCode(mixed $code)
Sets the HTTP status code to be sent.
If $code is null the current code is returned
If the status code is 304 or 204, the existing Content-Type header will be cleared, as these response codes have no body.
Parameters
-
int|null
$code optional the HTTP status code
Returns
int
Current status code
Throws
InvalidArgumentException
When an unknown status code is reached.
stop() public
stop(mixed $status)
Stop execution of the current script. Wraps exit() making testing easier.
Parameters
-
int|string
$status optional See https://secure.php.net/exit for values
type() public
type(mixed $contentType)
Sets the response content type. It can be either a file extension which will be mapped internally to a mime-type or a string representing a mime-type if $contentType is null the current content type is returned if $contentType is an associative array, content type definitions will be stored/replaced
Setting the content type
type('jpg');
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.
Returning the current content type
type();
Storing content type definitions
type(['keynote' => 'application/keynote', 'bat' => 'application/bat']);
Replacing a content type definition
type(['jpg' => 'text/plain']);
Parameters
-
string|array|null
$contentType optional Content type key.
Returns
mixed
Current content type or false if supplied an invalid content type.
validateFile() protected
validateFile(mixed $path)
Validate a file path is a valid response body.
Parameters
-
string
$path The path to the file.
Returns
\Cake\Filesystem\File
Throws
Cake\Http\Exception\NotFoundException
vary() public
vary(mixed $cacheVariances)
Sets the Vary header for the response, 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|null
$cacheVariances optional A single Vary string or an array containing the list for variances.
Returns
array|null
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
InvalidArgumentException
for invalid header names or values.
withAddedLink() public
withAddedLink(mixed $url, mixed $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
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
-
string|int|\DateTimeInterface|null
$since A valid time since the response text has not been modified
-
string|int
$time optional A valid time for cache expiry
Returns
static
Throws
InvalidArgumentException
withCharset() public
withCharset(mixed $charset)
Get a new instance with an updated charset.
Parameters
-
string
$charset Character set string.
Returns
static
withCookie() public
withCookie(mixed $name, mixed $data)
Create a new response with a cookie set.
Data
-
value
: Value of the cookie -
expire
: Time the cookie expires in -
path
: Path the cookie applies to -
domain
: Domain the cookie is for. -
secure
: Is the cookie https? -
httpOnly
: Is the cookie available in the client?
Examples
// set scalar value with defaults $response = $response->withCookie('remember_me', 1); // customize cookie attributes $response = $response->withCookie('remember_me', ['path' => '/login']); // add a cookie object $response = $response->withCookie(new Cookie('remember_me', 1));
Parameters
-
string|\Cake\Http\Cookie\Cookie
$name The name of the cookie to set, or a cookie object
-
array|string
$data optional Either a string value, or an array of cookie options.
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(mixed $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(mixed $hash, mixed $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(mixed $name, mixed $options)
Create a new response with an expired cookie set.
Options
-
path
: Path the cookie applies to -
domain
: Domain the cookie is for. -
secure
: Is the cookie https? -
httpOnly
: Is the cookie available in the client?
Examples
// set scalar value with defaults $response = $response->withExpiredCookie('remember_me'); // customize cookie attributes $response = $response->withExpiredCookie('remember_me', ['path' => '/login']); // add a cookie object $response = $response->withExpiredCookie(new Cookie('remember_me'));
Parameters
-
string|\Cake\Http\Cookie\CookieInterface
$name The name of the cookie to expire, or a cookie object
-
array
$options optional An array of cookie options.
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(mixed $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 Path to file. If the path is not an absolute path that resolves to a file,
APP
will be prepended to the path (this behavior is deprecated).-
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
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(mixed $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(mixed $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
-
string|int|\DateTimeInterface|null
$time Valid time string or \DateTimeInterface instance.
Returns
static
withMustRevalidate() public
withMustRevalidate(mixed $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(mixed $public, mixed $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(mixed $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
withStringBody() public
withStringBody(mixed $string)
Convenience method to set a string into the response body
Parameters
-
string
$string The string to be sent
Returns
static
withType() public
withType(mixed $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
Property Detail
$_cacheDirectives protected
Holds all the cache directives that will be converted into headers when sending the request
Type
array
$_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
\Cake\Filesystem\File|null
$_fileRange protected
File range. Used for requesting ranges of files.
Type
array
$_mimeTypes protected
Holds type key to mime type mappings for known mime types.
Type
array
$_protocol protected
Protocol header to send to the client
Type
string
$_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
string[]
$_streamMode protected
Stream mode options.
Type
string
$_streamTarget protected
Stream target or resource object.
Type
string|resource
$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/3.9/class-Cake.TestSuite.Stub.Response.html