Class CakeResponse
CakeResponse 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.
Copyright: Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
License: MIT License
Located at Cake/Network/CakeResponse.php
Method Detail
__constructsource public
__construct( array $options array() )
Constructor
Parameters
- array
$options
optional array() - 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
__toStringsource public
__toString( )
String conversion. Fetches the response body as a string. Does not send headers.
Returns
string
string
_clearBuffersource protected
_clearBuffer( )
Clears the contents of the topmost output buffer and discards them
Returns
boolean
bool
_fileRangesource protected
_fileRange( 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.
Parameters
-
File
$file
- The file to set a range on.
- string
$httpRange
- The range to use.
_getUTCDatesource protected
_getUTCDate( string|DateTime $time null )
Returns a DateTime object initialized at the $time param and using UTC as timezone
Parameters
- string|DateTime
$time
optional null - Valid time string or unix timestamp or DateTime object.
Returns
DateTime
DateTime
_isActivesource protected
_isActive( )
Returns true if connection is still active
Returns
boolean
bool
_normalizeCorsDomainssource protected
_normalizeCorsDomains( array $domains , boolean $requestIsSSL false )
Normalize the origin to regular expressions and put in an array format
Parameters
- array
$domains
- Domains to normalize
- boolean
$requestIsSSL
optional false - Whether it's a SSL request.
Returns
array
array
_sendContentsource protected
_sendContent( string $content )
Sends a content string to the client.
Parameters
- string
$content
- string to send as response body
_sendFilesource protected
_sendFile( File $file , array $range )
Reads out a file, and echos the content to the client.
Parameters
-
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
_sendHeadersource protected
_sendHeader( string $name , string $value null )
Sends a header to the client.
Will skip sending headers if headers have already been sent.
Parameters
- string
$name
- the header name
- string
$value
optional null - the header value
_setCacheControlsource protected
_setCacheControl( )
Helper method to generate a valid Cache-Control header from the options set in other methods
_setContentsource protected
_setContent( )
Sets the response body to an empty text if the status code is 204 or 304
_setContentLengthsource protected
_setContentLength( )
Calculates the correct Content-Length and sets it as a header in the response Will not set the value if already set or if the output is compressed.
_setContentTypesource 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
_setCookiessource protected
_setCookies( )
Sets the cookies that have been added via CakeResponse::cookie() before any other output is sent to the client. Will set the cookies in the order they have been set.
bodysource public
body( string $content null )
Buffers the response message to be sent if $content is null the current buffer is returned
Parameters
- string
$content
optional null - the string message to be sent
Returns
string
current message buffer if $content param is passed as null
cachesource public
cache( string $since , string $time '+1 day' )
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 '+1 day' - a valid time for cache expiry
charsetsource public
charset( string $charset null )
Sets the response charset if $charset is null the current charset is returned
Parameters
- string
$charset
optional null - Character set string.
Returns
string
current charset
checkNotModifiedsource public
checkNotModified( CakeRequest $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
-
CakeRequest
$request
- Request object
Returns
boolean
whether the response was marked as not modified or not.
compresssource 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
cookiesource public
cookie( array $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.
Parameters
- array
$options
optional null - Either null to get all cookies, string for a specific cookie or array to set cookie. ### 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)
Returns
mixed
mixed
corssource public
cors( CakeRequest $request , string|array $allowedDomains , string|array $allowedMethods array() , string|array $allowedHeaders array() )
Setup access for origin and methods on cross origin requests
This method allow multiple ways to setup the domains, see the examples
Full URI
e.g cors($request, 'http://www.cakephp.org');
URI with wildcard
e.g cors($request, 'http://*.cakephp.org');
Ignoring the requested protocol
e.g cors($request, 'www.cakephp.org');
Any URI
e.g cors($request, '*');
Whitelist of URIs
e.g cors($request, array('http://www.cakephp.org', '*.google.com', 'https://myproject.github.io'));
Parameters
-
CakeRequest
$request
- Request object
- string|array
$allowedDomains
- List of allowed domains, see method description for more details
- string|array
$allowedMethods
optional array() - List of HTTP verbs allowed
- string|array
$allowedHeaders
optional array() - List of HTTP headers allowed
disableCachesource public
disableCache( )
Sets the correct headers to instruct the client to not cache the response
downloadsource public
download( string $filename )
Sets the correct headers to instruct the browser to download the response as a file.
Parameters
- string
$filename
- the name of the file as the browser will download the response
etagsource public
etag( string $tag 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 sematicallly, 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
$tag
optional null - Tag to set.
- boolean
$weak
optional false - whether the response is semantically the same as other with the same hash or not
Returns
string
string
expiressource public
expires( string|DateTime $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
Parameters
- string|DateTime
$time
optional null - Valid time string or DateTime object.
Returns
string
string
filesource public
file( string $path , array $options array() )
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 array() - Options See above.
Throws
NotFoundException
NotFoundException
getMimeTypesource 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
headersource public
header( string|array $header null , string|array $value null )
Buffers a header string to be sent Returns the complete list of buffered headers
Single header
e.g header('Location', 'http://example.com');
Multiple headers
e.g header(array('Location' => 'http://example.com', 'X-Extra' => 'My header'));
String header
e.g header('WWW-Authenticate: Negotiate');
Array of string headers
e.g header(array('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 e.g 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
$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
$value
optional null - The header value(s)
Returns
array
list of headers to be sent
httpCodessource public
httpCodes( integer|array $code null )
Queries & sets valid HTTP response codes & messages.
Parameters
- integer|array
$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 array(404 => 'Not Found') httpCodes(array( 381 => 'Unicorn Moved', 555 => 'Unexpected Minotaur' )); // sets these new values, and returns true httpCodes(array( 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
CakeException
If an attempt is made to add an invalid status code
lengthsource public
length( integer $bytes null )
Sets the Content-Length header for the response If called with no arguments returns the last Content-Length set
Parameters
- integer
$bytes
optional null - Number of bytes
Returns
integer|null
int|null
locationsource public
location( null|string $url null )
Accessor for the location header.
Get/Set the Location header value.
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.
mapTypesource 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
mixed
Aliases for the types provided.
maxAgesource public
maxAge( integer $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
$seconds
optional null - if null, the method will return the current max-age value
Returns
integer
int
modifiedsource public
modified( string|DateTime $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
Parameters
- string|DateTime
$time
optional null - Valid time string or DateTime object.
Returns
string
string
mustRevalidatesource public
mustRevalidate( boolean $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.
Parameters
- boolean
$enable
optional null - If null returns whether directive is set, if boolean sets or unsets directive.
Returns
boolean
bool
notModifiedsource 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
outputCompressedsource public
outputCompressed( )
Returns whether the resulting output will be compressed by PHP
Returns
boolean
bool
protocolsource public
protocol( string $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
Parameters
- string
$protocol
optional null - Protocol to be used for sending response.
Returns
string
protocol currently set
sendsource public
send( )
Sends the complete response to the client including headers and message body. Will echo out the content in the response body.
sharablesource public
sharable( boolean $public null , integer $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
$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
$time
optional null - time in seconds after which the response should no longer be considered fresh
Returns
boolean
bool
sharedMaxAgesource public
sharedMaxAge( integer $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
$seconds
optional null - if null, the method will return the current s-maxage value
Returns
integer
int
statusCodesource public
statusCode( integer $code null )
Sets the HTTP status code to be sent if $code is null the current code is returned
Parameters
- integer
$code
optional null - the HTTP status code
Returns
integer
current status code
Throws
CakeException
When an unknown status code is reached.
typesource public
type( string $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
e.g type('jpg');
Returning the current content type
e.g type();
Storing content type definitions
e.g type(array('keynote' => 'application/keynote', 'bat' => 'application/bat'));
Replacing a content type definition
e.g type(array('jpg' => 'text/plain'));
Parameters
- string
$contentType
optional null - Content type key.
Returns
mixed
current content type or false if supplied an invalid content type
varysource public
vary( string|array $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
Parameters
- string|array
$cacheVariances
optional null - a single Vary string or an array containing the list for variances.
Returns
array
array
Properties summary
© 2005–2016 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.
http://api.cakephp.org/2.7/class-CakeResponse.html