Class Response

Cake Response is responsible for managing the response text, status and headers of a HTTP response.

By default controllers will use this class to render their response. If you are going to use a custom response class it should subclass this object in order to ensure compatibility.

Namespace: Cake\Http

Property 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
$_contentType protected

string

Content type to send. This can be an 'extension' that will be transformed using the $_mimetypes array or a complete mime-type
$_cookies protected

array

Holds cookies to be sent to the client
$_file protected

Cake\Filesystem\File

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

array

Holds HTTP response statuses
$_streamMode protected

string

Stream mode options.
$_streamTarget protected

string|resource

Stream target or resource object.
$headerNames protected

array

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

array

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

Method Summary

__construct() public

Constructor
__debugInfo() public

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

String conversion. Fetches the response body as a string. Does not send headers. If body is a callable, a blank string is returned.
_clearBuffer() protected deprecated

Clears the contents of the topmost output buffer and discards them
_clearHeader() protected

Clear header
_createStream() protected

Creates the stream object.
_fileRange() protected deprecated

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

Flushes the contents of the output buffer
_getUTCDate() protected

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

Handles the callable body for backward compatibility reasons.
_isActive() protected deprecated

Returns true if connection is still active
_sendContent() protected deprecated

Sends a content string to the client.
_sendFile() protected deprecated

Reads out a file, and echos the content to the client.
_sendHeader() protected deprecated

Sends a header to the client.
_setCacheControl() protected

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

Sets the response body to an empty text if the status code is 204 or 304
_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 deprecated

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

Sets a header.
body() public deprecated

Buffers the response message to be sent if $content is null the current buffer is returned
cache() public deprecated

Sets the correct headers to instruct the client to cache the response.
charset() public deprecated

Sets the response charset if $charset is null the current charset 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.
cookie() public deprecated

Getter/Setter for cookie configs
cors() public

Setup access for origin and methods on cross origin requests
disableCache() public deprecated

Sets the correct headers to instruct the client to not cache the response
download() public deprecated

Sets the correct headers to instruct the browser to download the response as a file.
etag() public deprecated

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 deprecated

Sets the Expires header for the response by taking an expiration time If called with no parameters it will return the current Expires value
file() public deprecated

Setup for display or download the given file.
getBody() public

Gets the body of the message.
getCookie() public

Read a single cookie 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.
getSimpleHeaders() protected

Backwards compatibility helper for getting flattened headers.
getStatusCode() public

Gets the response status code.
hasHeader() public

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

Buffers a header string to be sent Returns the complete list of buffered headers
httpCodes() public deprecated

Queries & sets valid HTTP response codes & messages.
length() public deprecated

Sets the Content-Length header for the response If called with no arguments returns the last Content-Length set
location() public deprecated

Accessor for the location header.
mapType() public

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

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
modified() public deprecated

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
mustRevalidate() public deprecated

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.
notModified() public

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

Returns whether the resulting output will be compressed by PHP
protocol() public deprecated

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
resolveType() protected

Translate and validate content-types.
send() public deprecated

Sends the complete response to the client including headers and message body. Will echo out the content in the response body.
sendHeaders() public deprecated

Sends the HTTP headers and cookies.
sharable() public

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
sharedMaxAge() public

Sets the Cache-Control s-maxage directive.
statusCode() public deprecated

Sets the HTTP status code to be sent if $code is null the current code is returned
stop() public deprecated

Stop execution of the current script. Wraps exit() making testing easier.
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
validateFile() protected

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

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.
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.
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.
withExpires() public

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Return an instance without the specified header.

Method Detail

__construct() ¶ public

__construct(array $options = [])

Constructor

Parameters

array $options optional

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

body: the response text that should be sent to the client
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

__debugInfo() ¶ public

__debugInfo(): array

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

Returns

array

__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

_clearBuffer() ¶ protected

_clearBuffer(): bool

Clears the contents of the topmost output buffer and discards them

Returns

bool

_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(Cake\Filesystem\File $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

Cake\Filesystem\File $file: The file to set a range on.
string $httpRange: The range to use.

Returns

void

_flushBuffer() ¶ protected

_flushBuffer(): void

Flushes the contents of the output buffer

Returns

void

_getUTCDate() ¶ protected

_getUTCDate(string|intDateTime|null $time = null): DateTime

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

Parameters

string|intDateTime|null $time optional: Valid time string or \DateTime instance.

Returns

DateTime

_handleCallableBody() ¶ protected

_handleCallableBody(callable $content): string

Handles the callable body for backward compatibility reasons.

Parameters

callable $content: Callable content.

Returns

string

_isActive() ¶ protected

_isActive(): bool

Returns true if connection is still active

Returns

bool

_sendContent() ¶ protected

_sendContent(string|callable $content): void

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.

Returns

void

_sendFile() ¶ protected

_sendFile(Cake\Filesystem\File $file, array $range): bool

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

_sendHeader() ¶ protected

_sendHeader(string $name, string|null $value = null): void

Sends a header to the client.

Parameters

string $name: the header name
string|null $value optional: the header value

Returns

void

_setCacheControl() ¶ protected

_setCacheControl(): void

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

Returns

void

_setContent() ¶ protected

_setContent(): void

Sets the response body to an empty text if the status code is 204 or 304

Returns

void

_setContentType() ¶ protected

_setContentType(): 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/*

Returns

void

_setCookies() ¶ protected

_setCookies(): void

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.

Returns

void

_setHeader() ¶ protected

_setHeader(string $header, string $value): void

Sets a header.

Parameters

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

Returns

void

body() ¶ public

body(string|callable|null $content = null): string

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

cache() ¶ public

cache(string $since, string $time = '+1 day'): void

Sets the correct headers to instruct the client to cache the response.

Parameters

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

Returns

void

charset() ¶ public

charset(string|null $charset = null): string

Sets the response charset if $charset is null the current charset is returned

Parameters

string|null $charset optional: Character set string.

Returns

string

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.

Parameters

Cake\Http\ServerRequest $request: Request object

Returns

bool

compress() ¶ 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

bool

cookie() ¶ public

cookie(array|null $options = null): mixed

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, string|array $allowedDomains = [], string|array $allowedMethods = [], string|array $allowedHeaders = []): Cake\Network\CorsBuilder

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|array $allowedDomains optional: List of allowed domains, see method description for more details
string|array $allowedMethods optional: List of HTTP verbs allowed
string|array $allowedHeaders optional: List of HTTP headers allowed

Returns

Cake\Network\CorsBuilder

disableCache() ¶ public

disableCache(): void

Sets the correct headers to instruct the client to not cache the response

Returns

void

download() ¶ public

download(string $filename): void

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

Returns

void

etag() ¶ public

etag(string|null $hash = null, bool $weak = false): string|null

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(stringDateTime|null $time = null): string|null

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

stringDateTime|null $time optional: Valid time string or \DateTime instance.

Returns

string|null

file() ¶ public

file(string $path, array $options = []): void

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.
array $options optional: Options See above.

Returns

void

Throws

Cake\Network\Exception\NotFoundException

getBody() ¶ public

getBody(): StreamInterface

Gets the body of the message.

Returns

StreamInterface

getCookie() ¶ 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|null

getCookies() ¶ public

getCookies(): array

Get all cookies in the response.

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

Returns

array

getFile() ¶ public

getFile(): Cake\Filesystem\File|null

Get the current file if one exists.

Returns

Cake\Filesystem\File|null

getHeader() ¶ 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

string

getHeaders() ¶ 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

array

getMimeType() ¶ public

getMimeType(string $alias): mixed

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

mixed

getProtocolVersion() ¶ 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

string

getReasonPhrase() ¶ 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

string

Links

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

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

getSimpleHeaders() ¶ protected

getSimpleHeaders(): array

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(): 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

int

hasHeader() ¶ public

hasHeader(string $header): bool

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

Parameters

string $header: Case-insensitive header name.

Returns

bool

header() ¶ public

header(string|array|null $header = null, string|array|null $value = null): array

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

httpCodes() ¶ public

httpCodes(int|array|null $code = null): mixed

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:

Returns

mixed

Throws

InvalidArgumentException
If an attempt is made to add an invalid status code

length() ¶ public

length(int|null $bytes = null): int|null

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

int|null

location() ¶ public

location(null|string $url = null): string|null

Accessor for the location header.

Get/Set the Location header value.

Parameters

null|string $url optional: Either null to get the current location, or a string to set one.

Returns

string|null

mapType() ¶ public

mapType(string|array $ctype): string|array|null

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

maxAge() ¶ public

maxAge(int|null $seconds = null): int|null

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(stringDateTime|null $time = null): string|null

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

stringDateTime|null $time optional: Valid time string or \DateTime instance.

Returns

string|null

mustRevalidate() ¶ public

mustRevalidate(bool|null $enable = null): bool

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(): 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

Returns

void

outputCompressed() ¶ public

outputCompressed(): bool

Returns whether the resulting output will be compressed by PHP

Returns

bool

protocol() ¶ public

protocol(string|null $protocol = null): string

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

resolveType() ¶ protected

resolveType(string $contentType): string

Translate and validate content-types.

Parameters

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

sharable(bool|null $public = null, int|null $time = null): bool|null

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(int|null $seconds = null): int|null

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(int|null $code = null): int

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

Throws

InvalidArgumentException
When an unknown status code is reached.

stop() ¶ public

stop(int|string $status = 0): void

Stop execution of the current script. Wraps exit() making testing easier.

Parameters

int|string $status optional: See https://secure.php.net/exit for values

Returns

void

type() ¶ public

type(string|null $contentType = null): mixed

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|null $contentType optional: Content type key.

Returns

mixed

validateFile() ¶ protected

validateFile(string $path): Cake\Filesystem\File

Validate a file path is a valid response body.

Parameters

string $path: The path to the file.

Returns

Cake\Filesystem\File

Throws

Cake\Network\Exception\NotFoundException

vary() ¶ public

vary(string|array|null $cacheVariances = null): array|null

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(string $header, 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 $header: Case-insensitive header field name to add.
string|string[] $value: Header value(s).

Returns

static

Throws

InvalidArgumentException
for invalid header names or values.

withBody() ¶ 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

static

Throws

InvalidArgumentException
When the body is not valid.

withCache() ¶ public

withCache(string $since, string $time = '+1 day'): static

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

Parameters

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

Returns

static

withCharset() ¶ public

withCharset(string $charset): static

Get a new instance with an updated charset.

Parameters

string $charset: Character set string.

Returns

static

withCookie() ¶ public

withCookie(string $name, array|string $data = ''): static

Create a new response with a cookie set.

Options

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

// set scalar value with defaults
$response = $response->withCookie('remember_me', 1);

// customize cookie attributes
$response = $response->withCookie('remember_me', ['path' => '/login']);

Parameters

string $name: The name of the cookie to set.
array|string $data optional: Either a string value, or an array of cookie options.

Returns

static

withDisabledCache() ¶ public

withDisabledCache(): static

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

Returns

static

withDownload() ¶ 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

static

withEtag() ¶ 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

static

withExpires() ¶ public

withExpires(stringDateTime $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

stringDateTime $time: Valid time string or \DateTime instance.

Returns

static

withFile() ¶ public

withFile(string $path, array $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 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.
array $options optional: Options See above.

Returns

static

Throws

Cake\Network\Exception\NotFoundException

withHeader() ¶ public

withHeader(string $header, 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 $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(int|string $bytes): static

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

Parameters

int|string $bytes: Number of bytes

Returns

static

withLocation() ¶ 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

static

withMaxAge() ¶ 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

static

withModified() ¶ public

withModified(stringDateTime $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

stringDateTime $time: Valid time string or \DateTime instance.

Returns

static

withMustRevalidate() ¶ 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

static

withNotModified() ¶ 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

static

withProtocolVersion() ¶ 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

static

withSharable() ¶ 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

static

withSharedMaxAge() ¶ 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

static

withStatus() ¶ 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.

Parameters

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

Returns

static

Throws

InvalidArgumentException
For invalid status code arguments.

Links

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

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

withStringBody() ¶ public

withStringBody(string $string): static

Convenience method to set a string into the response body

Parameters

string $string: The string to be sent

Returns

static

withType() ¶ public

withType(string $contentType): 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

static

withVary() ¶ public

withVary(string|array $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

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

Returns

static

withoutHeader() ¶ public

withoutHeader(string $header): 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 $header: Case-insensitive header field name to remove.

Returns

static

array

Namespaces

Class Response

Property Summary

Method Summary

__construct() public

__debugInfo() public

__toString() public

_clearBuffer() protected deprecated

_clearHeader() protected

_createStream() protected

_fileRange() protected deprecated

_flushBuffer() protected deprecated

_getUTCDate() protected

_handleCallableBody() protected

_isActive() protected deprecated

_sendContent() protected deprecated

_sendFile() protected deprecated

_sendHeader() protected deprecated

_setCacheControl() protected

_setContent() protected deprecated

_setContentType() protected

_setCookies() protected deprecated

_setHeader() protected

body() public deprecated

cache() public deprecated

charset() public deprecated

checkNotModified() public

compress() public

cookie() public deprecated

cors() public

disableCache() public deprecated

download() public deprecated

etag() public deprecated

expires() public deprecated

file() public deprecated

getBody() public

getCookie() public

getCookies() public

getFile() public

getHeader() public

getHeaderLine() public

getHeaders() public

getMimeType() public

getProtocolVersion() public

getReasonPhrase() public

getSimpleHeaders() protected

getStatusCode() public

hasHeader() public

header() public deprecated

httpCodes() public deprecated

length() public deprecated

location() public deprecated

mapType() public

maxAge() public

modified() public deprecated

mustRevalidate() public deprecated

notModified() public

outputCompressed() public

protocol() public deprecated

resolveType() protected

send() public deprecated

sendHeaders() public deprecated

sharable() public

sharedMaxAge() public

statusCode() public deprecated

stop() public deprecated

type() public

validateFile() protected

vary() public deprecated

withAddedHeader() public

withBody() public

withCache() public

withCharset() public

withCookie() public

withDisabledCache() public

withDownload() public

withEtag() public

withExpires() public

withFile() public

withHeader() public