W3cubDocs

/CakePHP 3.4

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.

Cake\Http\Response implements Psr\Http\Message\ResponseInterface uses Zend\Diactoros\MessageTrait

Direct Subclasses

Namespace: Cake\Http
Location: Http/Response.php

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
  • $_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
    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
    integer
    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.

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
    Clears the contents of the topmost output buffer and discards them
  • _clearHeader() protected
    Clear header
  • _createStream() protected
    Creates the stream object.
  • _fileRange() protected
    Apply a file range to a file and set the end offset.
  • _flushBuffer() protected
    Flushes the contents of the output buffer
  • _getUTCDate() protected

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

  • Handles the callable body for backward compatibility reasons.
  • _isActive() protected
    Returns true if connection is still active
  • _sendContent() protected
    Sends a content string to the client.
  • _sendFile() protected
    Reads out a file, and echos the content to the client.
  • _sendHeader() protected
    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
    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

    Sets the cookies that have been added via Cake\Network\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

    Buffers the response message to be sent if $content is null the current buffer is returned

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

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

  • 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
    Getter/Setter for cookie configs
  • cors() public
    Setup access for origin and methods on cross origin requests
  • Sets the correct headers to instruct the client to not cache the response
  • 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

  • file() public
    Setup for display or download the given file.
  • 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.
  • getMimeType() public
    Returns the mime type definition for an alias
  • Gets the response reason phrase associated with the status code.
  • getSimpleHeaders() protected
    Backwards compatibility helper for getting flattened headers.
  • Gets the response status code.
  • header() public

    Buffers a header string to be sent Returns the complete list of buffered headers

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

    Sets the Content-Length header for the response If called with no arguments returns the last Content-Length set

  • location() public
    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

    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

  • 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

  • Returns whether the resulting output will be compressed by PHP
  • 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

  • resolveType() protected
    Translate and validate content-types.
  • send() public

    Sends the complete response to the client including headers and message body. Will echo out the content in the response body.

  • sendHeaders() public
    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

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

    Sets the HTTP status code to be sent if $code is null the current code is returned

  • stop() public

    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

    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

  • 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.
  • 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.
  • 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.
  • withLength() public
    Create a new response with the Content-Length header set.
  • Return an instance with an updated location header.
  • withMaxAge() public
    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'
  • Create a new instace with the public/private Cache-Control directive set.
  • 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.
  • withType() public
    Get an updated response with the content type set.
  • withVary() public
    Create a new instance with the Vary header set.

Method Detail

__construct()source 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()source public

__debugInfo( )

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

Returns

array

__toString()source 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()source protected

_clearBuffer( )

Clears the contents of the topmost output buffer and discards them

Deprecated

3.2.4 This function is not needed anymore

Returns

boolean

_clearHeader()source protected

_clearHeader( string $header )

Clear header

Parameters

string $header
Header key.

_createStream()source protected

_createStream( )

Creates the stream object.

_fileRange()source protected

_fileRange( Cake\Filesystem\File $file , string $httpRange )

Apply a file range to a file and set the end offset.

If an invalid range is requested a 416 Status code will be used in the response.

Deprecated

3.4.0 Long term this needs to be refactored to follow immutable paradigms. However for now, it is simpler to leave this alone.


Parameters

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

_flushBuffer()source protected

_flushBuffer( )

Flushes the contents of the output buffer

Deprecated

3.2.4 This function is not needed anymore

_getUTCDate()source protected

_getUTCDate( string|integer|DateTime|null $time null )

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

Parameters

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

Returns

DateTime

_handleCallableBody()source protected

_handleCallableBody( callable $content )

Handles the callable body for backward compatibility reasons.

Parameters

callable $content
Callable content.

Returns

string

_isActive()source protected

_isActive( )

Returns true if connection is still active

Deprecated

3.4.0 Will be removed in 4.0.0

Returns

boolean

_sendContent()source protected

_sendContent( string|callable $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.

Deprecated

3.4.0 Will be removed in 4.0.0

Parameters

string|callable $content

String to send as response body or callable which returns/outputs content.

_sendFile()source protected

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

Reads out a file, and echos the content to the client.

Deprecated

3.4.0 Will be removed in 4.0.0

Parameters

Cake\Filesystem\File $file
File object
array $range
The range to read out of the file.

Returns

boolean
True is whole file is echoed successfully or false if client connection is lost in between

_sendHeader()source protected

_sendHeader( string $name , string|null $value null )

Sends a header to the client.

Deprecated

3.4.0 Will be removed in 4.0.0

Parameters

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

_setCacheControl()source protected

_setCacheControl( )

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

_setContent()source protected

_setContent( )

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

Deprecated

3.4.0 Will be removed in 4.0.0

_setContentType()source protected

_setContentType( )

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

_setCookies( )

Sets the cookies that have been added via Cake\Network\Response::cookie() before any other output is sent to the client. Will set the cookies in the order they have been set.

Deprecated

3.4.0 Will be removed in 4.0.0

_setHeader()source protected

_setHeader( string $header , string $value )

Sets a header.

Parameters

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

body()source public

body( string|callable|null $content null )

Buffers the response message to be sent if $content is null the current buffer is returned

Deprecated

3.4.0 Mutable response methods are deprecated. Use withBody() and getBody() instead.

Parameters

string|callable|null $content optional null
the string or callable message to be sent

Returns

string
Current message buffer if $content param is passed as null

cache()source public

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

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

Deprecated

3.4.0 Use withCache() instead.

Parameters

string $since
a valid time since the response text has not been modified
string $time optional '+1 day'
a valid time for cache expiry

charset()source public

charset( string|null $charset null )

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

Deprecated

3.4.0 Use withCharset() instead.

Parameters

string|null $charset optional null
Character set string.

Returns

string
Current charset

checkNotModified()source 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.

Parameters

Cake\Http\ServerRequest $request
Request object

Returns

boolean
Whether the response was marked as not modified or not.

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

boolean
false if client does not accept compressed responses or no handler is available, true otherwise
cookie( array|null $options null )

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)

Deprecated

3.4.0 Use getCookie(), getCookies() and withCookie() instead.

Parameters

array|null $options optional null

Either null to get all cookies, string for a specific cookie or array to set cookie.

Returns

mixed

cors()source public

cors( Cake\Http\ServerRequest $request , string|array $allowedDomains [] , string|array $allowedMethods [] , string|array $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, 'http://www.cakephp.org');

URI with wildcard

cors($request, 'http://*.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

A builder object the provides a fluent interface for defining additional CORS headers.


disableCache()source public

disableCache( )

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

Deprected

3.4.0 Use withDisabledCache() instead.

download()source public

download( string $filename )

Sets the correct headers to instruct the browser to download the response as a file.

Deprecated

3.4.0 Use withDownload() instead.

Parameters

string $filename
The name of the file as the browser will download the response

etag()source public

etag( string|null $hash null , boolean $weak false )

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.

Deprecated

3.4.0 Use withEtag() instead.

Parameters

string|null $hash optional null
The unique hash that identifies this response
boolean $weak optional false

Whether the response is semantically the same as other with the same hash or not

Returns

string|null

expires()source public

expires( string|DateTime|null $time 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

Deprecated

3.4.0 Use withExpires() instead.

Parameters

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

Returns

string|null

file()source public

file( string $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

Deprecated

3.4.0 Use withFile() instead.

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.

Throws

Cake\Network\Exception\NotFoundException

getCookie()source public

getCookie( string $name )

Read a single cookie from the response.

This method provides read access to pending cookies. It will not read the Set-Cookie header if set.

Parameters

string $name
The cookie name you want to read.

Returns

array|null
Either the cookie data or null

getCookies()source public

getCookies( )

Get all cookies in the response.

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

Returns

array

getFile()source public

getFile( )

Get the current file if one exists.

Returns

Cake\Filesystem\File|null
The file to use in the response or null

getMimeType()source public

getMimeType( string $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

mixed
String mapped mime type or false if $alias is not mapped

getReasonPhrase()source 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.

Link

http://tools.ietf.org/html/rfc7231#section-6
http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml

getSimpleHeaders()source 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()source 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

integer
Status code.

header()source public

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

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');

Deprecated

3.4.0 Use withHeader(), getHeaderLine() and getHeaders() instead.

Parameters

string|array|null $header optional null

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 null
The header value(s)

Returns

array
List of headers to be sent

httpCodes()source public

httpCodes( integer|array|null $code null )

Queries & sets valid HTTP response codes & messages.

Deprecated

3.4.0 Will be removed in 4.0.0

Parameters

integer|array|null $code optional null

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

length( integer|null $bytes null )

Sets the Content-Length header for the response If called with no arguments returns the last Content-Length set

Deprecated

3.4.0 Use withLength() to set length instead.

Parameters

integer|null $bytes optional null
Number of bytes

Returns

integer|null

location()source public

location( null|string $url null )

Accessor for the location header.

Get/Set the Location header value.

Deprecated

3.4.0 Mutable responses are deprecated. Use withLocation() and getHeaderLine() instead.


Parameters

null|string $url optional null
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()source public

mapType( string|array $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()source public

maxAge( integer|null $seconds 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

integer|null $seconds optional null
if null, the method will return the current max-age value

Returns

integer|null

modified()source public

modified( string|DateTime|null $time 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

Deprecated

3.4.0 Use withModified() instead.

Parameters

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

Returns

string|null

mustRevalidate()source public

mustRevalidate( boolean|null $enable null )

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.

Deprecated

3.4.0 Use withMustRevalidate() instead.

Parameters

boolean|null $enable optional null

if null, the method will return the current must-revalidate value. If boolean sets or unsets the directive.

Returns

boolean

notModified()source 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

outputCompressed()source public

outputCompressed( )

Returns whether the resulting output will be compressed by PHP

Returns

boolean

protocol()source public

protocol( string|null $protocol null )

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

Deprecated

3.4.0 Use getProtocolVersion() instead.

Parameters

string|null $protocol optional null
Protocol to be used for sending response.

Returns

string
Protocol currently set

resolveType()source protected

resolveType( string $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()source public

send( )

Sends the complete response to the client including headers and message body. Will echo out the content in the response body.

Deprecated

3.4.0 Will be removed in 4.0.0

sendHeaders()source public

sendHeaders( )

Sends the HTTP headers and cookies.

Deprecated

3.4.0 Will be removed in 4.0.0

sharable()source public

sharable( boolean|null $public null , integer|null $time 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

boolean|null $public optional null

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

integer|null $time optional null
time in seconds after which the response should no longer be considered fresh

Returns

boolean|null

sharedMaxAge()source public

sharedMaxAge( integer|null $seconds 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

integer|null $seconds optional null
if null, the method will return the current s-maxage value

Returns

integer|null

statusCode()source public

statusCode( integer|null $code null )

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.

Deprecated

3.4.0 Use getStatusCode() and withStatus() instead.

Parameters

integer|null $code optional null
the HTTP status code

Returns

integer
Current status code

Throws

InvalidArgumentException
When an unknown status code is reached.

stop()source public

stop( integer|string $status 0 )

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

Deprecated

3.4.0 Will be removed in 4.0.0

Parameters

integer|string $status optional 0
See http://php.net/exit for values

type()source public

type( string|null $contentType null )

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 null
Content type key.

Returns

mixed
Current content type or false if supplied an invalid content type

validateFile()source protected

validateFile( string $path )

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

vary( string|array|null $cacheVariances 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

Deprecated

3.4.0 Use withVary() instead.

Parameters

string|array|null $cacheVariances optional null

A single Vary string or an array containing the list for variances.

Returns

array|null

withCache()source public

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

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 '+1 day'
a valid time for cache expiry

Returns

Cake\Http\Response

withCharset()source public

withCharset( string $charset )

Get a new instance with an updated charset.

Parameters

string $charset
Character set string.

Returns

Cake\Http\Response

withCookie()source public

withCookie( string $name , array|string $data '' )

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

Cake\Http\Response

withDisabledCache()source public

withDisabledCache( )

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

Returns

Cake\Http\Response

withDownload()source public

withDownload( string $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

Cake\Http\Response

withEtag()source public

withEtag( string $hash , boolean $weak false )

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
boolean $weak optional false

Whether the response is semantically the same as other with the same hash or not. Defaults to false

Returns

Cake\Http\Response

withExpires()source public

withExpires( string|DateTime $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|DateTime $time
Valid time string or \DateTime instance.

Returns

Cake\Http\Response

withFile()source public

withFile( string $path , array $options [] )

Create a new instance that is based on a file.

This method will augment both the body and a number of related headers.

If $_SERVER['HTTP_RANGE'] is set, a slice of the file will be returned instead of the entire file.

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

Cake\Http\Response

Throws

Cake\Network\Exception\NotFoundException

withLength()source public

withLength( integer|string $bytes )

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

Parameters

integer|string $bytes
Number of bytes

Returns

Cake\Http\Response

withLocation()source public

withLocation( string $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

Cake\Http\Response
A new response with the Location header set.

withMaxAge()source public

withMaxAge( integer $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

integer $seconds
The seconds a cached response can be considered valid

Returns

Cake\Http\Response

withModified()source public

withModified( string|DateTime $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|DateTime $time
Valid time string or \DateTime instance.

Returns

Cake\Http\Response

withMustRevalidate()source public

withMustRevalidate( boolean $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

boolean $enable
If boolean sets or unsets the directive.

Returns

Cake\Http\Response

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

Cake\Http\Response

withSharable()source public

withSharable( boolean $public , integer|null $time null )

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

Parameters

boolean $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.

integer|null $time optional null
time in seconds after which the response should no longer be considered fresh.

Returns

Cake\Http\Response

withSharedMaxAge()source public

withSharedMaxAge( integer $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

integer $seconds
The number of seconds for shared max-age

Returns

Cake\Http\Response

withStatus()source public

withStatus( integer $code , string $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.

Parameters

integer $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

Cake\Http\Response

Throws

InvalidArgumentException
For invalid status code arguments.

Link

http://tools.ietf.org/html/rfc7231#section-6
http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml

withType()source public

withType( string $contentType )

Get an updated response with the content type set.

If you attempt to set the type on a 304 or 204 status code response, the content type will not take effect as these status codes do not have content-types.

Parameters

string $contentType
Either a file extension which will be mapped to a mime-type or a concrete mime-type.

Returns

Cake\Http\Response

withVary()source public

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

Cake\Http\Response

Properties detail

$_cacheDirectivessource

protected array

Holds all the cache directives that will be converted into headers when sending the request

[]

$_charsetsource

protected string

The charset the response body is encoded with

'UTF-8'

$_contentTypesource

protected string

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

'text/html'

$_cookiessource

protected array

Holds cookies to be sent to the client

[]

$_filesource

protected Cake\Filesystem\File

File object for file to be read out as response

null

$_fileRangesource

protected array

File range. Used for requesting ranges of files.

[]

$_mimeTypessource

protected array

Holds type key to mime type mappings for known mime types.

[
    'html' => ['text/html', '*/*'],
    'json' => 'application/json',
    'xml' => ['application/xml', 'text/xml'],
    'xhtml' => ['application/xhtml+xml', 'application/xhtml', 'text/xhtml'],
    'webp' => 'image/webp',
    'rss' => 'application/rss+xml',
    'ai' => 'application/postscript',
    'bcpio' => 'application/x-bcpio',
    'bin' => 'application/octet-stream',
    'ccad' => 'application/clariscad',
    'cdf' => 'application/x-netcdf',
    'class' => 'application/octet-stream',
    'cpio' => 'application/x-cpio',
    'cpt' => 'application/mac-compactpro',
    'csh' => 'application/x-csh',
    'csv' => ['text/csv', 'application/vnd.ms-excel'],
    'dcr' => 'application/x-director',
    'dir' => 'application/x-director',
    'dms' => 'application/octet-stream',
    'doc' => 'application/msword',
    'docx' => 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
    'drw' => 'application/drafting',
    'dvi' => 'application/x-dvi',
    'dwg' => 'application/acad',
    'dxf' => 'application/dxf',
    'dxr' => 'application/x-director',
    'eot' => 'application/vnd.ms-fontobject',
    'eps' => 'application/postscript',
    'exe' => 'application/octet-stream',
    'ez' => 'application/andrew-inset',
    'flv' => 'video/x-flv',
    'gtar' => 'application/x-gtar',
    'gz' => 'application/x-gzip',
    'bz2' => 'application/x-bzip',
    '7z' => 'application/x-7z-compressed',
    'hdf' => 'application/x-hdf',
    'hqx' => 'application/mac-binhex40',
    'ico' => 'image/x-icon',
    'ips' => 'application/x-ipscript',
    'ipx' => 'application/x-ipix',
    'js' => 'application/javascript',
    'jsonapi' => 'application/vnd.api+json',
    'latex' => 'application/x-latex',
    'lha' => 'application/octet-stream',
    'lsp' => 'application/x-lisp',
    'lzh' => 'application/octet-stream',
    'man' => 'application/x-troff-man',
    'me' => 'application/x-troff-me',
    'mif' => 'application/vnd.mif',
    'ms' => 'application/x-troff-ms',
    'nc' => 'application/x-netcdf',
    'oda' => 'application/oda',
    'otf' => 'font/otf',
    'pdf' => 'application/pdf',
    'pgn' => 'application/x-chess-pgn',
    'pot' => 'application/vnd.ms-powerpoint',
    'pps' => 'application/vnd.ms-powerpoint',
    'ppt' => 'application/vnd.ms-powerpoint',
    'pptx' => 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
    'ppz' => 'application/vnd.ms-powerpoint',
    'pre' => 'application/x-freelance',
    'prt' => 'application/pro_eng',
    'ps' => 'application/postscript',
    'roff' => 'application/x-troff',
    'scm' => 'application/x-lotusscreencam',
    'set' => 'application/set',
    'sh' => 'application/x-sh',
    'shar' => 'application/x-shar',
    'sit' => 'application/x-stuffit',
    'skd' => 'application/x-koan',
    'skm' => 'application/x-koan',
    'skp' => 'application/x-koan',
    'skt' => 'application/x-koan',
    'smi' => 'application/smil',
    'smil' => 'application/smil',
    'sol' => 'application/solids',
    'spl' => 'application/x-futuresplash',
    'src' => 'application/x-wais-source',
    'step' => 'application/STEP',
    'stl' => 'application/SLA',
    'stp' => 'application/STEP',
    'sv4cpio' => 'application/x-sv4cpio',
    'sv4crc' => 'application/x-sv4crc',
    'svg' => 'image/svg+xml',
    'svgz' => 'image/svg+xml',
    'swf' => 'application/x-shockwave-flash',
    't' => 'application/x-troff',
    'tar' => 'application/x-tar',
    'tcl' => 'application/x-tcl',
    'tex' => 'application/x-tex',
    'texi' => 'application/x-texinfo',
    'texinfo' => 'application/x-texinfo',
    'tr' => 'application/x-troff',
    'tsp' => 'application/dsptype',
    'ttc' => 'font/ttf',
    'ttf' => 'font/ttf',
    'unv' => 'application/i-deas',
    'ustar' => 'application/x-ustar',
    'vcd' => 'application/x-cdlink',
    'vda' => 'application/vda',
    'xlc' => 'application/vnd.ms-excel',
    'xll' => 'application/vnd.ms-excel',
    'xlm' => 'application/vnd.ms-excel',
    'xls' => 'application/vnd.ms-excel',
    'xlsx' => 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
    'xlw' => 'application/vnd.ms-excel',
    'zip' => 'application/zip',
    'aif' => 'audio/x-aiff',
    'aifc' => 'audio/x-aiff',
    'aiff' => 'audio/x-aiff',
    'au' => 'audio/basic',
    'kar' => 'audio/midi',
    'mid' => 'audio/midi',
    'midi' => 'audio/midi',
    'mp2' => 'audio/mpeg',
    'mp3' => 'audio/mpeg',
    'mpga' => 'audio/mpeg',
    'ogg' => 'audio/ogg',
    'oga' => 'audio/ogg',
    'spx' => 'audio/ogg',
    'ra' => 'audio/x-realaudio',
    'ram' => 'audio/x-pn-realaudio',
    'rm' => 'audio/x-pn-realaudio',
    'rpm' => 'audio/x-pn-realaudio-plugin',
    'snd' => 'audio/basic',
    'tsi' => 'audio/TSP-audio',
    'wav' => 'audio/x-wav',
    'aac' => 'audio/aac',
    'asc' => 'text/plain',
    'c' => 'text/plain',
    'cc' => 'text/plain',
    'css' => 'text/css',
    'etx' => 'text/x-setext',
    'f' => 'text/plain',
    'f90' => 'text/plain',
    'h' => 'text/plain',
    'hh' => 'text/plain',
    'htm' => ['text/html', '*/*'],
    'ics' => 'text/calendar',
    'm' => 'text/plain',
    'rtf' => 'text/rtf',
    'rtx' => 'text/richtext',
    'sgm' => 'text/sgml',
    'sgml' => 'text/sgml',
    'tsv' => 'text/tab-separated-values',
    'tpl' => 'text/template',
    'txt' => 'text/plain',
    'text' => 'text/plain',
    'avi' => 'video/x-msvideo',
    'fli' => 'video/x-fli',
    'mov' => 'video/quicktime',
    'movie' => 'video/x-sgi-movie',
    'mpe' => 'video/mpeg',
    'mpeg' => 'video/mpeg',
    'mpg' => 'video/mpeg',
    'qt' => 'video/quicktime',
    'viv' => 'video/vnd.vivo',
    'vivo' => 'video/vnd.vivo',
    'ogv' => 'video/ogg',
    'webm' => 'video/webm',
    'mp4' => 'video/mp4',
    'm4v' => 'video/mp4',
    'f4v' => 'video/mp4',
    'f4p' => 'video/mp4',
    'm4a' => 'audio/mp4',
    'f4a' => 'audio/mp4',
    'f4b' => 'audio/mp4',
    'gif' => 'image/gif',
    'ief' => 'image/ief',
    'jpg' => 'image/jpeg',
    'jpeg' => 'image/jpeg',
    'jpe' => 'image/jpeg',
    'pbm' => 'image/x-portable-bitmap',
    'pgm' => 'image/x-portable-graymap',
    'png' => 'image/png',
    'pnm' => 'image/x-portable-anymap',
    'ppm' => 'image/x-portable-pixmap',
    'ras' => 'image/cmu-raster',
    'rgb' => 'image/x-rgb',
    'tif' => 'image/tiff',
    'tiff' => 'image/tiff',
    'xbm' => 'image/x-xbitmap',
    'xpm' => 'image/x-xpixmap',
    'xwd' => 'image/x-xwindowdump',
    'psd' => ['application/photoshop', 'application/psd', 'image/psd', 'image/x-photoshop', 'image/photoshop', 'zz-application/zz-winassoc-psd'],
    'ice' => 'x-conference/x-cooltalk',
    'iges' => 'model/iges',
    'igs' => 'model/iges',
    'mesh' => 'model/mesh',
    'msh' => 'model/mesh',
    'silo' => 'model/mesh',
    'vrml' => 'model/vrml',
    'wrl' => 'model/vrml',
    'mime' => 'www/mime',
    'pdb' => 'chemical/x-pdb',
    'xyz' => 'chemical/x-pdb',
    'javascript' => 'application/javascript',
    'form' => 'application/x-www-form-urlencoded',
    'file' => 'multipart/form-data',
    'xhtml-mobile' => 'application/vnd.wap.xhtml+xml',
    'atom' => 'application/atom+xml',
    'amf' => 'application/x-amf',
    'wap' => ['text/vnd.wap.wml', 'text/vnd.wap.wmlscript', 'image/vnd.wap.wbmp'],
    'wml' => 'text/vnd.wap.wml',
    'wmlscript' => 'text/vnd.wap.wmlscript',
    'wbmp' => 'image/vnd.wap.wbmp',
    'woff' => 'application/x-font-woff',
    'appcache' => 'text/cache-manifest',
    'manifest' => 'text/cache-manifest',
    'htc' => 'text/x-component',
    'rdf' => 'application/xml',
    'crx' => 'application/x-chrome-extension',
    'oex' => 'application/x-opera-extension',
    'xpi' => 'application/x-xpinstall',
    'safariextz' => 'application/octet-stream',
    'webapp' => 'application/x-web-app-manifest+json',
    'vcf' => 'text/x-vcard',
    'vtt' => 'text/vtt',
    'mkv' => 'video/x-matroska',
    'pkpass' => 'application/vnd.apple.pkpass',
    'ajax' => 'text/html'
]

$_protocolsource

protected string

Protocol header to send to the client

'HTTP/1.1'

$_reasonPhrasesource

protected string

Reason Phrase

'OK'

$_statussource

protected integer

Status code to send to the client

200

$_statusCodessource

protected array

Holds HTTP response statuses

[
    100 => 'Continue',
    101 => 'Switching Protocols',
    102 => 'Processing',
    200 => 'OK',
    201 => 'Created',
    202 => 'Accepted',
    203 => 'Non-Authoritative Information',
    204 => 'No Content',
    205 => 'Reset Content',
    206 => 'Partial Content',
    207 => 'Multi-status',
    208 => 'Already Reported',
    226 => 'IM used',
    300 => 'Multiple Choices',
    301 => 'Moved Permanently',
    302 => 'Found',
    303 => 'See Other',
    304 => 'Not Modified',
    305 => 'Use Proxy',
    306 => '(Unused)',
    307 => 'Temporary Redirect',
    308 => 'Permanent Redirect',
    400 => 'Bad Request',
    401 => 'Unauthorized',
    402 => 'Payment Required',
    403 => 'Forbidden',
    404 => 'Not Found',
    405 => 'Method Not Allowed',
    406 => 'Not Acceptable',
    407 => 'Proxy Authentication Required',
    408 => 'Request Timeout',
    409 => 'Conflict',
    410 => 'Gone',
    411 => 'Length Required',
    412 => 'Precondition Failed',
    413 => 'Request Entity Too Large',
    414 => 'Request-URI Too Large',
    415 => 'Unsupported Media Type',
    416 => 'Requested range not satisfiable',
    417 => 'Expectation Failed',
    418 => 'I\'m a teapot',
    421 => 'Misdirected Request',
    422 => 'Unprocessable Entity',
    423 => 'Locked',
    424 => 'Failed Dependency',
    425 => 'Unordered Collection',
    426 => 'Upgrade Required',
    428 => 'Precondition Required',
    429 => 'Too Many Requests',
    431 => 'Request Header Fields Too Large',
    444 => 'Connection Closed Without Response',
    451 => 'Unavailable For Legal Reasons',
    499 => 'Client Closed Request',
    500 => 'Internal Server Error',
    501 => 'Not Implemented',
    502 => 'Bad Gateway',
    503 => 'Service Unavailable',
    504 => 'Gateway Timeout',
    505 => 'Unsupported Version',
    506 => 'Variant Also Negotiates',
    507 => 'Insufficient Storage',
    508 => 'Loop Detected',
    510 => 'Not Extended',
    511 => 'Network Authentication Required',
    599 => 'Network Connect Timeout Error',
]

$_streamModesource

protected string

Stream mode options.

'wb+'

$_streamTargetsource

protected string|resource

Stream target or resource object.

'php://memory'

© 2005–2017 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.4/class-Cake.Http.Response.html