Request & Response Objects

Request & Response Objects

The request and response objects provide an abstraction around HTTP requests andresponses. The request object in CakePHP allows you to introspect an incomingrequest, while the response object allows you to effortlessly create HTTPresponses from your controllers.

Request

class Cake\Http\ServerRequest

ServerRequest is the default request object used in CakePHP. It centralizes anumber of features for interrogating and interacting with request data.On each request one Request is created and then passed by reference to thevarious layers of an application that use request data. By default the requestis assigned to $this->request, and is available in Controllers, Cells, Viewsand Helpers. You can also access it in Components using the controllerreference. Some of the duties ServerRequest performs include:

Processing the GET, POST, and FILES arrays into the data structures you arefamiliar with.
Providing environment introspection pertaining to the request. Informationlike the headers sent, the client’s IP address, and the subdomain/domainnames the server your application is running on.
Providing access to request parameters both as array indexes and objectproperties.

CakePHP’s request object implements the PSR-7ServerRequestInterface making it easier touse libraries from outside of CakePHP.

Request Parameters

The request exposes routing parameters through the getParam() method:

$controllerName = $this->request->getParam('controller');

To get all routing parameters as an array use getAttribute():

$parameters = $this->request->getAttribute('params');

All Route Elements are accessed through this interface.

In addition to Route Elements, you also often need access toPassed Arguments. These are both available on the request object aswell:

// Passed arguments
$passedArgs = $this->request->getParam('pass');

Will all provide you access to the passed arguments. Thereare several important/useful parameters that CakePHP uses internally, theseare also all found in the routing parameters:

plugin The plugin handling the request. Will be null when there is noplugin.
controller The controller handling the current request.
action The action handling the current request.
prefix The prefix for the current action. See Prefix Routing formore information.

Query String Parameters

Cake\Http\ServerRequest::getQuery($name)

Query string parameters can be read using the getQuery() method:

// URL is /posts/index?page=1&sort=title
$page = $this->request->getQuery('page');

You can either directly access the query property, or you can usegetQuery() method to read the URL query array in an error-free manner.Any keys that do not exist will return null:

$foo = $this->request->getQuery('value_that_does_not_exist');
// $foo === null
 
// You can also provide default values
$foo = $this->request->getQuery('does_not_exist', 'default val');

If you want to access all the query parameters you can usegetQueryParams():

$query = $this->request->getQueryParams();

Request Body Data

Cake\Http\ServerRequest::getData($name, $default = null)

All POST data can be accessed usingCake\Http\ServerRequest::getData(). Any form data thatcontains a data prefix will have that data prefix removed. For example:

// An input with a name attribute equal to 'MyModel[title]' is accessible at
$title = $this->request->getData('MyModel.title');

Any keys that do not exist will return null:

$foo = $this->request->getData('Value.that.does.not.exist');
// $foo == null

File Uploads

Uploaded files can be accessed through the request body data, using the Cake\Http\ServerRequest::getData()method described above. For example, a file from an input element with a name attribute of MyModel[attachment], canbe accessed like this:

$attachment = $this->request->getData('MyModel.attachment');

By default file uploads are represented in the request data as arrays, with a normalized structure that remains the sameeven for nested inputs/names, which is different from how PHP represents them in the $_FILES superglobal (refer tothe PHP manual for more information), ie the$attachment value would look something like this:

[
    'name' => 'attachment.txt',
    'type' => 'text/plain',
    'size' => 123,
    'tmp_name' => '/tmp/hfz6dbn.tmp'
    'error' => 0
]

Alternatively it’s possible to have CakePHP provide the uploads in the request data as objects that implement\Psr\Http\Message\UploadedFileInterface. In order toenable this behavior, set the configuration value App.uploadedFilesAsObjects to true, for example in yourconfig/app.php file:

return [
    // ...
    'App' => [
        // ...
        'uploadedFilesAsObjects' => true,
    ],
    // ...
];

In the above example, $attachment would then hold an object, in the current implementation it would by default be aninstance of \Zend\Diactoros\UploadedFile.

Furthermore uploaded files can be accessed as objects separately from the request data via theCake\Http\ServerRequest::getUploadedFile() andCake\Http\ServerRequest::getUploadedFiles() methods. These methods will always return objects,irrespectively of the App.uploadedFilesAsObjects configuration.

Cake\Http\ServerRequest::getUploadedFile($path)

Returns the uploaded file at a specific path. The path uses the same dot syntax as theCake\Http\ServerRequest::getData() method:

$attachment = $this->request->getUploadedFile('MyModel.attachment');

Unlike Cake\Http\ServerRequest::getData(), Cake\Http\ServerRequest::getUploadedFile() wouldonly return data when an actual file upload exists for the given path, if there is regular, non-file request body datapresent at the given path, then this method will return null, just like it would for any non-existent path.

Cake\Http\ServerRequest::getUploadedFiles()

Returns all uploaded files in a normalized array structure. For the above example with the file input name ofMyModel[attachment], the structure would look like:

[
    'MyModel' => [
        'attachment' => object(Zend\Diactoros\UploadedFile) {
            // ...
        }
    ]
]

Cake\Http\ServerRequest::withUploadedFiles(array $files)

This method sets the uploaded files of the request object, it accepts an array of objects that implement\Psr\Http\Message\UploadedFileInterface. It willreplace all possibly existing uploaded files:

$files = [
    'MyModel' => [
        'attachment' => new \Zend\Diactoros\UploadedFile(
            $streamOrFile,
            $size,
            $errorStatus,
            $clientFilename,
            $clientMediaType
        ),
        'anotherAttachment' => new \Zend\Diactoros\UploadedFile(
            '/tmp/hfz6dbn.tmp',
            123,
            \UPLOAD_ERR_OK,
            'attachment.txt',
            'text/plain'
        ),
    ],
];
 
$this->request = $this->request->withUploadedFiles($files);

Note

Uploaded files that have been added to the request via this method, will not be available in the request bodydata, ie you cannot retrieve them via Cake\Http\ServerRequest::getData()! If you need them in therequest data (too), then you have to set them via Cake\Http\ServerRequest::withData() orCake\Http\ServerRequest::withParsedBody().

PUT, PATCH or DELETE Data

Cake\Http\ServerRequest::input($callback[, $options])

When building REST services, you often accept request data on PUT andDELETE requests. Any application/x-www-form-urlencoded request body datawill automatically be parsed and set to $this->data for PUT andDELETE requests. If you are accepting JSON or XML data, see below for howyou can access those request bodies.

When accessing the input data, you can decode it with an optional function.This is useful when interacting with XML or JSON request body content.Additional parameters for the decoding function can be passed as arguments toinput():

$jsonData = $this->request->input('json_decode');

Environment Variables (from $_SERVER and $_ENV)

Cake\Http\ServerRequest::env($key, $value = null)

ServerRequest::env() is a wrapper for env() global function and acts asa getter/setter for environment variables without having to modify globals$_SERVER and $_ENV:

// Get the host
$host = $this->request->env('HTTP_HOST');
 
// Set a value, generally helpful in testing.
$this->request->env('REQUEST_METHOD', 'POST');

To access all the environment variables in a request use getServerParams():

$env = $this->request->getServerParams();

XML or JSON Data

Applications employing REST often exchange data innon-URL-encoded post bodies. You can read input data in any format usingHttp\ServerRequest::input(). By providing a decoding function,you can receive the content in a deserialized format:

// Get JSON encoded data submitted to a PUT/POST action
$jsonData = $this->request->input('json_decode');

Some deserializing methods require additional parameters when called, such asthe ‘as array’ parameter on json_decode. If you want XML converted into aDOMDocument object, Http\ServerRequest::input() supportspassing in additional parameters as well:

// Get XML encoded data submitted to a PUT/POST action
$data = $this->request->input('Cake\Utility\Xml::build', ['return' => 'domdocument']);

Path Information

The request object also provides useful information about the paths in yourapplication. The base and webroot attributes are useful forgenerating URLs, and determining whether or not your application is in asubdirectory. The attributes you can use are:

// Assume the current request URL is /subdir/articles/edit/1?page=1
 
// Holds /subdir/articles/edit/1?page=1
$here = $request->getRequestTarget();
 
// Holds /subdir
$base = $request->getAttribute('base');
 
// Holds /subdir/
$base = $request->getAttribute('webroot');

Checking Request Conditions

Cake\Http\ServerRequest::is($type, $args…)

The request object provides an easy way to inspect certain conditions in a givenrequest. By using the is() method you can check a number of commonconditions, as well as inspect other application specific request criteria:

$isPost = $this->request->is('post');

You can also extend the request detectors that are available, by usingCake\Http\ServerRequest::addDetector() to create new kinds ofdetectors. There are different types of detectors that you can create:

Environment value comparison - Compares a value fetched from env()for equality with the provided value.
Header value comparison - If the specified header exists with the specifiedvalue, or if the callable returns true.
Pattern value comparison - Pattern value comparison allows you to compare avalue fetched from env() to a regular expression.
Option based comparison - Option based comparisons use a list of options tocreate a regular expression. Subsequent calls to add an already definedoptions detector will merge the options.
Callback detectors - Callback detectors allow you to provide a ‘callback’ typeto handle the check. The callback will receive the request object as its onlyparameter.

Cake\Http\ServerRequest::addDetector($name, $options)

Some examples would be:

// Add an environment detector.
$this->request->addDetector(
    'post',
    ['env' => 'REQUEST_METHOD', 'value' => 'POST']
);
 
// Add a pattern value detector.
$this->request->addDetector(
    'iphone',
    ['env' => 'HTTP_USER_AGENT', 'pattern' => '/iPhone/i']
);
 
// Add an option detector
$this->request->addDetector('internalIp', [
    'env' => 'CLIENT_IP',
    'options' => ['192.168.0.101', '192.168.0.100']
]);
 
 
// Add a header detector with value comparison
$this->request->addDetector('fancy', [
    'env' => 'CLIENT_IP',
    'header' => ['X-Fancy' => 1]
]);
 
// Add a header detector with callable comparison
$this->request->addDetector('fancy', [
    'env' => 'CLIENT_IP',
    'header' => ['X-Fancy' => function ($value, $header) {
        return in_array($value, ['1', '0', 'yes', 'no'], true);
    }]
]);
 
// Add a callback detector. Must be a valid callable.
$this->request->addDetector(
    'awesome',
    function ($request) {
        return $request->getParam('awesome');
    }
);
 
// Add a detector that uses additional arguments.
$this->request->addDetector(
    'csv',
    [
        'accept' => ['text/csv'],
        'param' => '_ext',
        'value' => 'csv',
    ]
);

There are several built-in detectors that you can use:

is('get') Check to see whether the current request is a GET.
is('put') Check to see whether the current request is a PUT.
is('patch') Check to see whether the current request is a PATCH.
is('post') Check to see whether the current request is a POST.
is('delete') Check to see whether the current request is a DELETE.
is('head') Check to see whether the current request is HEAD.
is('options') Check to see whether the current request is OPTIONS.
is('ajax') Check to see whether the current request came withX-Requested-With = XMLHttpRequest.
is('ssl') Check to see whether the request is via SSL.
is('flash') Check to see whether the request has a User-Agent of Flash.
is('json') Check to see whether the request has ‘json’ extension andaccept ‘application/json’ mimetype.
is('xml') Check to see whether the request has ‘xml’ extension and accept‘application/xml’ or ‘text/xml’ mimetype.

ServerRequest also includes methods likeCake\Http\ServerRequest::domain(),Cake\Http\ServerRequest::subdomains() andCake\Http\ServerRequest::host() to make applications that usesubdomains simpler.

Session Data

To access the session for a given request use the getSession() method or use the session attribute:

$session = $this->request->getSession();
$session = $this->request->getAttribute('session');
 
$userName = $session->read('Auth.User.name');

For more information, see the Sessions documentation for howto use the session object.

Host and Domain Name

Cake\Http\ServerRequest::domain($tldLength = 1)

Returns the domain name your application is running on:

// Prints 'example.org'
echo $request->domain();

Cake\Http\ServerRequest::subdomains($tldLength = 1)

Returns the subdomains your application is running on as an array:

// Returns ['my', 'dev'] for 'my.dev.example.org'
$subdomains = $request->subdomains();

Cake\Http\ServerRequest::host()

Returns the host your application is on:

// Prints 'my.dev.example.org'
echo $request->host();

Reading the HTTP Method

Cake\Http\ServerRequest::getMethod()

Returns the HTTP method the request was made with:

// Output POST
echo $request->getMethod();

Restricting Which HTTP method an Action Accepts

Cake\Http\ServerRequest::allowMethod($methods)

Set allowed HTTP methods. If not matched, will throwMethodNotAllowedException. The 405 response will include the requiredAllow header with the passed methods:

public function delete()
{
    // Only accept POST and DELETE requests
    $this->request->allowMethod(['post', 'delete']);
    ...
}

Reading HTTP Headers

Allows you to access any of the HTTP_* headers that were usedfor the request. For example:

// Get the header as a string
$userAgent = $this->request->getHeaderLine('User-Agent');
 
// Get an array of all values.
$acceptHeader = $this->request->getHeader('Accept');
 
// Check if a header exists
$hasAcceptHeader = $this->request->hasHeader('Accept');

While some apache installs don’t make the Authorization header accessible,CakePHP will make it available through apache specific methods as required.

Cake\Http\ServerRequest::referer($local = true)

Returns the referring address for the request.

Cake\Http\ServerRequest::clientIp()

Returns the current visitor’s IP address.

Trusting Proxy Headers

If your application is behind a load balancer or running on a cloud service, youwill often get the load balancer host, port and scheme in your requests. Oftenload balancers will also send HTTP-X-Forwarded-* headers with the originalvalues. The forwarded headers will not be used by CakePHP out of the box. Tohave the request object use these headers set the trustProxy property totrue:

$this->request->trustProxy = true;
 
// These methods will now use the proxied headers.
$port = $this->request->port();
$host = $this->request->host();
$scheme = $this->request->scheme();
$clientIp = $this->request->clientIp();

Once proxies are trusted the clientIp() method will use the last IPaddress in the X-Forwarded-For header. If your application is behindmultiple proxies, you can use setTrustedProxies() to define the IP addressesof proxies in your control:

$request->setTrustedProxies(['127.1.1.1', '127.8.1.3']);

After proxies are trusted clientIp() will use the first IP address in theX-Forwarded-For header providing it is the only value that isn’t from a trustedproxy.

Checking Accept Headers

Cake\Http\ServerRequest::accepts($type = null)

Find out which content types the client accepts, or check whether it accepts aparticular type of content.

Get all types:

$accepts = $this->request->accepts();

Check for a single type:

$acceptsJson = $this->request->accepts('application/json');

Cake\Http\ServerRequest::acceptLanguage($language = null)

Get all the languages accepted by the client,or check whether a specific language is accepted.

Get the list of accepted languages:

$acceptsLanguages = $this->request->acceptLanguage();

Check whether a specific language is accepted:

$acceptsSpanish = $this->request->acceptLanguage('es-es');

Cookies

Request cookies can be read through a number of methods:

// Get the cookie value, or null if the cookie is missing.
$rememberMe = $this->request->getCookie('remember_me');
 
// Read the value, or get the default of 0
$rememberMe = $this->request->getCookie('remember_me', 0);
 
// Get all cookies as an hash
$cookies = $this->request->getCookieParams();
 
// Get a CookieCollection instance
$cookies = $this->request->getCookieCollection()

See the Cake\Http\Cookie\CookieCollection documentation for howto work with cookie collection.

Uploaded Files

Requests expose the uploaded file data in getData() orgetUploadedFiles() as UploadedFileInterface objects:

// Get a list of UploadedFile objects
$files = $request->getUploadedFiles();
 
// Read the file data.
$files[0]->getStream();
$files[0]->getSize();
$files[0]->getClientFileName();
 
// Move the file.
$files[0]->moveTo($targetPath);

Manipulating URIs

Requests contain a URI object, which contains methods for interacting with therequested URI:

// Get the URI
$uri = $request->getUri();
 
// Read data out of the URI.
$path = $uri->getPath();
$query = $uri->getQuery();
$host = $uri->getHost();

Response

class Cake\Http\Response

Cake\Http\Response is the default response class in CakePHP.It encapsulates a number of features and functionality for generating HTTPresponses in your application. It also assists in testing, as it can bemocked/stubbed allowing you to inspect headers that will be sent.Like Cake\Http\ServerRequest, Cake\Http\Responseconsolidates a number of methods previously found on Controller,RequestHandlerComponent and Dispatcher. The oldmethods are deprecated in favour of using Cake\Http\Response.

Response provides an interface to wrap the common response-relatedtasks such as:

Sending headers for redirects.
Sending content type headers.
Sending any header.
Sending the response body.

Dealing with Content Types

Cake\Http\Response::withType($contentType = null)

You can control the Content-Type of your application’s responses withCake\Http\Response::withType(). If your application needs to dealwith content types that are not built into Response, you can map them withtype() as well:

// Add a vCard type
$this->response->type(['vcf' => 'text/v-card']);
 
// Set the response Content-Type to vcard.
$this->response = $this->response->withType('vcf');

Usually, you’ll want to map additional content types in your controller’sbeforeFilter() callback, so you can leverage theautomatic view switching features of RequestHandlerComponent if youare using it.

Sending Files

Cake\Http\Response::withFile($path, $options = [])

There are times when you want to send files as responses for your requests.You can accomplish that by using Cake\Http\Response::withFile():

public function sendFile($id)
{
    $file = $this->Attachments->getFile($id);
    $response = $this->response->withFile($file['path']);
    // Return the response to prevent controller from trying to render
    // a view.
    return $response;
}

As shown in the above example, you must pass the file path to the method.CakePHP will send a proper content type header if it’s a known file type listedin Cake\Http\Response::$_mimeTypes. You can add new types prior to callingCake\Http\Response::withFile() by using theCake\Http\Response::withType() method.

If you want, you can also force a file to be downloaded instead of displayed inthe browser by specifying the options:

$response = $this->response->withFile(
    $file['path'],
    ['download' => true, 'name' => 'foo']
);

The supported options are:

name
The name allows you to specify an alternate file name to be sent tothe user.
download
A boolean value indicating whether headers should be set to forcedownload.

Sending a String as File

You can respond with a file that does not exist on the disk, such as a pdf or anics generated on the fly from a string:

public function sendIcs()
{
    $icsString = $this->Calendars->generateIcs();
    $response = $this->response;
 
    // Inject string content into response body
    $response = $response->withStringBody($icsString);
 
    $response = $response->withType('ics');
 
    // Optionally force file download
    $response = $response->withDownload('filename_for_download.ics');
 
    // Return response object to prevent controller from trying to render
    // a view.
    return $response;
}

Callbacks can also return the body as a string:

$path = '/some/file.png';
$this->response->body(function () use ($path) {
    return file_get_contents($path);
});

Setting Headers

Cake\Http\Response::withHeader($header, $value)

Setting headers is done with the Cake\Http\Response::withHeader()method. Like all of the PSR-7 interface methods, this method returns a _new_instance with the new header:

// Add/replace a header
$response = $response->withHeader('X-Extra', 'My header');
 
// Set multiple headers
$response = $response->withHeader('X-Extra', 'My header')
    ->withHeader('Location', 'http://example.com');
 
// Append a value to an existing header
$response = $response->withAddedHeader('Set-Cookie', 'remember_me=1');

Headers are not sent when set. Instead, they are held until the response isemitted by Cake\Http\Server.

You can now use the convenience methodCake\Http\Response::withLocation() to directly set or get theredirect location header.

Setting the Body

Cake\Http\Response::withStringBody($string)

To set a string as the response body, do the following:

// Set a string into the body
$response = $response->withStringBody('My Body');
 
// If you want a json response
$response = $response->withType('application/json')
    ->withStringBody(json_encode(['Foo' => 'bar']));

Cake\Http\Response::withBody($body)

To set the response body, use the withBody() method, which is provided by theZend\Diactoros\MessageTrait:

$response = $response->withBody($stream);

Be sure that $stream is a Psr\Http\Message\StreamInterface object.See below on how to create a new stream.

You can also stream responses from files using Zend\Diactoros\Stream streams:

// To stream from a file
use Zend\Diactoros\Stream;
 
$stream = new Stream('/path/to/file', 'rb');
$response = $response->withBody($stream);

You can also stream responses from a callback using the CallbackStream. Thisis useful when you have resources like images, CSV files or PDFs you need tostream to the client:

// Streaming from a callback
use Cake\Http\CallbackStream;
 
// Create an image.
$img = imagecreate(100, 100);
// ...
 
$stream = new CallbackStream(function () use ($img) {
    imagepng($img);
});
$response = $response->withBody($stream);

Setting the Character Set

Cake\Http\Response::withCharset($charset)

Sets the charset that will be used in the response:

$this->response = $this->response->withCharset('UTF-8');

Interacting with Browser Caching

Cake\Http\Response::withDisabledCache()

You sometimes need to force browsers not to cache the results of a controlleraction. Cake\Http\Response::withDisabledCache() is intended for justthat:

public function index()
{
    // Disable caching
    $this->response = $this->response->withDisabledCache();
}

Warning

Disabling caching from SSL domains while trying to sendfiles to Internet Explorer can result in errors.

Cake\Http\Response::withCache($since, $time = '+1 day')

You can also tell clients that you want them to cache responses. By usingCake\Http\Response::withCache():

public function index()
{
    // Enable caching
    $this->response = $this->response->withCache('-1 minute', '+5 days');
}

The above would tell clients to cache the resulting response for 5 days,hopefully speeding up your visitors’ experience.The withCache() method sets the Last-Modified value to the firstargument. Expires header and the max-age directive are set based on thesecond parameter. Cache-Control’s public directive is set as well.

Fine Tuning HTTP Cache

One of the best and easiest ways of speeding up your application is to use HTTPcache. Under this caching model, you are only required to help clients decide ifthey should use a cached copy of the response by setting a few headers such asmodified time and response entity tag.

Rather than forcing you to code the logic for caching and for invalidating(refreshing) it once the data has changed, HTTP uses two models, expiration andvalidation, which usually are much simpler to use.

Apart from using Cake\Http\Response::withCache(), you can also usemany other methods to fine-tune HTTP cache headers to take advantage of browseror reverse proxy caching.

The Cache Control Header

Cake\Http\Response::withSharable($public, $time = null)

Used under the expiration model, this header contains multiple indicators thatcan change the way browsers or proxies use the cached content. ACache-Control header can look like this:

Cache-Control: private, max-age=3600, must-revalidate

Response class helps you set this header with some utility methods that willproduce a final valid Cache-Control header. The first is thewithSharable() method, which indicates whether a response is to beconsidered sharable across different users or clients. This method actuallycontrols the public or private part of this header. Setting a responseas private indicates that all or part of it is intended for a single user. Totake advantage of shared caches, the control directive must be set as public.

The second parameter of this method is used to specify a max-age for thecache, which is the number of seconds after which the response is no longerconsidered fresh:

public function view()
{
    // ...
    // Set the Cache-Control as public for 3600 seconds
    $this->response = $this->response->withSharable(true, 3600);
}
 
public function my_data()
{
    // ...
    // Set the Cache-Control as private for 3600 seconds
    $this->response = $this->response->withSharable(false, 3600);
}

Response exposes separate methods for setting each of the directives inthe Cache-Control header.

The Expiration Header

Cake\Http\Response::withExpires($time)

You can set the Expires header to a date and time after which the responseis no longer considered fresh. This header can be set using thewithExpires() method:

public function view()
{
    $this->response = $this->response->withExpires('+5 days');
}

This method also accepts a DateTime instance or any string that canbe parsed by the DateTime class.

The Etag Header

Cake\Http\Response::withEtag($tag, $weak = false)

Cache validation in HTTP is often used when content is constantly changing, andasks the application to only generate the response contents if the cache is nolonger fresh. Under this model, the client continues to store pages in thecache, but it asks the application every timewhether the resource has changed, instead of using it directly.This is commonly used with static resources such as images and other assets.

The withEtag() method (called entity tag) is a stringthat uniquely identifies the requested resource, as a checksum does for a file,in order to determine whether it matches a cached resource.

To take advantage of this header, you must either call thecheckNotModified() method manually or include theRequest Handling in your controller:

public function index()
{
    $articles = $this->Articles->find('all');
 
    // Simple checksum of the article contents.
    // You should use a more efficient implementation
    // in a real world application.
    $checksum = md5(json_encode($articles));
 
    $response = $this->response->withEtag($checksum);
    if ($response->checkNotModified($this->request)) {
        return $response;
    }
 
    $this->response = $response;
    // ...
}

Note

Most proxy users should probably consider using the Last Modified Headerinstead of Etags for performance and compatibility reasons.

The Last Modified Header

Cake\Http\Response::withModified($time)

Also, under the HTTP cache validation model, you can set the Last-Modifiedheader to indicate the date and time at which the resource was modified for thelast time. Setting this header helps CakePHP tell caching clients whether theresponse was modified or not based on their cache.

To take advantage of this header, you must either call thecheckNotModified() method manually or include theRequest Handling in your controller:

public function view()
{
    $article = $this->Articles->find()->first();
    $response = $this->response->withModified($article->modified);
    if ($response->checkNotModified($this->request)) {
        return $response;
    }
    $this->response;
    // ...
}

The Vary Header

Cake\Http\Response::withVary($header)

In some cases, you might want to serve different content using the same URL.This is often the case if you have a multilingual page or respond with differentHTML depending on the browser. Under such circumstances you can use the Varyheader:

$response = $this->response->withVary('User-Agent');
$response = $this->response->withVary('Accept-Encoding', 'User-Agent');
$response = $this->response->withVary('Accept-Language');

Sending Not-Modified Responses

Cake\Http\Response::checkNotModified(Request $request)

Compares the cache headers for the request object with the cache header from theresponse and determines whether it can still be considered fresh. If so, deletesthe response content, and sends the 304 Not Modified header:

// In a controller action.
if ($this->response->checkNotModified($this->request)) {
    return $this->response;
}

Setting Cookies

Cookies can be added to response using either an array or a Cake\Http\Cookie\Cookieobject:

use Cake\Http\Cookie\Cookie;
use DateTime;
 
// Add a cookie
$this->response = $this->response->withCookie(Cookie::create(
    'remember_me',
    'yes',
    // All keys are optional
    [
        'expires' => new DateTime('+1 year'),
        'path' => '',
        'domain' => '',
        'secure' => false,
        'http' => false,
    ]
]);

See the Creating Cookies section for how to use the cookie object. Youcan use withExpiredCookie() to send an expired cookie in the response. Thiswill make the browser remove its local cookie:

$this->response = $this->response->withExpiredCookie('remember_me');

Setting Cross Origin Request Headers (CORS)

The cors() method is used to define HTTP Access Controlrelated headers with a fluent interface:

$this->response = $this->response->cors($this->request)
    ->allowOrigin(['*.cakephp.org'])
    ->allowMethods(['GET', 'POST'])
    ->allowHeaders(['X-CSRF-Token'])
    ->allowCredentials()
    ->exposeHeaders(['Link'])
    ->maxAge(300)
    ->build();

CORS related headers will only be applied to the response if the followingcriteria are met:

The request has an Origin header.
The request’s Origin value matches one of the allowed Origin values.

Common Mistakes with Immutable Responses

Response objects offer a number of methods that treatresponses as immutable objects. Immutable objects help prevent difficult totrack accidental side-effects, and reduce mistakes caused by method calls causedby refactoring that change ordering. While they offer a number of benefits,immutable objects can take some getting used to. Any method that starts withwith operates on the response in an immutable fashion, and will alwaysreturn a new instance. Forgetting to retain the modified instance is the mostfrequent mistake people make when working with immutable objects:

$this->response->withHeader('X-CakePHP', 'yes!');

In the above code, the response will be lacking the X-CakePHP header, as thereturn value of the withHeader() method was not retained. To correct theabove code you would write:

$this->response = $this->response->withHeader('X-CakePHP', 'yes!');

class Cake\Http\Cookie\CookieCollection

CookieCollection objects are accessible from the request and response objects.They let you interact with groups of cookies using immutable patterns, whichallow the immutability of the request and response to be preserved.

Creating Cookies

class Cake\Http\Cookie\Cookie

Cookie objects can be defined through constructor objects, or by using thefluent interface that follows immutable patterns:

use Cake\Http\Cookie\Cookie;
 
// All arguments in the constructor
$cookie = new Cookie(
    'remember_me', // name
    1, // value
    new DateTime('+1 year'), // expiration time, if applicable
    '/', // path, if applicable
    'example.com', // domain, if applicable
    false, // secure only?
    true // http only ?
);
 
// Using the builder methods
$cookie = (new Cookie('remember_me'))
    ->withValue('1')
    ->withExpiry(new DateTime('+1 year'))
    ->withPath('/')
    ->withDomain('example.com')
    ->withSecure(false)
    ->withHttpOnly(true);

Once you have created a cookie, you can add it to a new or existingCookieCollection:

use Cake\Http\Cookie\CookieCollection;
 
// Create a new collection
$cookies = new CookieCollection([$cookie]);
 
// Add to an existing collection
$cookies = $cookies->add($cookie);
 
// Remove a cookie by name
$cookies = $cookies->remove('remember_me');

Note

Remember that collections are immutable and adding cookies into, or removingcookies from a collection, creates a new collection object.

Cookie objects can be added to responses:

// Add one cookie
$response = $this->response->withCookie($cookie);
 
// Replace the entire cookie collection
$response = $this->response->withCookieCollection($cookies);

Cookies set to responses can be encrypted using theEncrypted Cookie Middleware.

Reading Cookies

Once you have a CookieCollection instance, you can access the cookies itcontains:

// Check if a cookie exists
$cookies->has('remember_me');
 
// Get the number of cookies in the collection
count($cookies);
 
// Get a cookie instance
$cookie = $cookies->get('remember_me');

Once you have a Cookie object you can interact with it’s state and modifyit. Keep in mind that cookies are immutable, so you’ll need to update thecollection if you modify a cookie:

// Get the value
$value = $cookie->getValue()
 
// Access data inside a JSON value
$id = $cookie->read('User.id');
 
// Check state
$cookie->isHttpOnly();
$cookie->isSecure();

Request & Response Objects

Request & Response Objects

Request

Request Parameters

Query String Parameters

Request Body Data

File Uploads

PUT, PATCH or DELETE Data

Environment Variables (from $_SERVER and $_ENV)

XML or JSON Data

Path Information

Checking Request Conditions

Session Data

Host and Domain Name

Reading the HTTP Method

Restricting Which HTTP method an Action Accepts

Reading HTTP Headers

Trusting Proxy Headers

Checking Accept Headers

Cookies

Uploaded Files

Manipulating URIs

Response

Dealing with Content Types

Sending Files

Sending a String as File

Setting Headers

Setting the Body

Setting the Character Set

Interacting with Browser Caching

Fine Tuning HTTP Cache

The Cache Control Header

The Expiration Header

The Etag Header

The Last Modified Header

The Vary Header

Sending Not-Modified Responses

Setting Cookies

Setting Cross Origin Request Headers (CORS)

Common Mistakes with Immutable Responses

Cookie Collections

Creating Cookies

Reading Cookies