The CakeRequest object in CakePHP 2.0

Work on CakePHP 2.0 is moving along, and I wanted to take some time to discuss and explain one of the sizeable refactorings that has been done for 2.0. In previous versions request parameters were just a bunch of arrays that were copied to the various places they were needed in the framework. Methods related to request features were spread across RequestHandler, Router, Dispatcher and Controller. There was no authoritative object on what information the request contained. In many other frameworks the request is represented by a single object. This seemed like and excellent solution for CakePHP that would allow us to both consolidate the existing code, and provide some useful new features.

Enter CakeRequest

CakeRequest is the default request object used in CakePHP 2.0. It centralizes the many features available in the classes previously mentioned into a single object. This object is then passed by reference to the various objects that use request data. This makes changes to that object reflect uniformly across all references. Some of the duties CakeRequest performs include:

• Process the GET, POST, and FILES arrays into the data structures you are familiar with.
• Provide environment introspection pertaining to the request. Things like the headers sent, the client’s IP address, and the subdomain/domain information about the application the server is running on.
• Provide access to request parameters both as array indices and object properties.

The request object is available in all the objects that used to have a params property. The params property still exists and contains the request object, but its been deprecated in favour of $this->request. I think this gives easier to read code than params does, and more accurately reflects what it does.

Getting at params with CakeRequest

As previously mentioned CakeRequest can be accessed in an array fashion, like the old params property was or, you can use object property access. Since both these interfaces existed on controllers in previous versions, both interfaces were moved to the request object.

Will both access the same values. The two ways of accessing values was done to ease the transition to using CakeRequest. In addition to the normal route parameters, properties like base, webroot, and here were also moved off the controller and into the request object. These properties were again things that had been spread about the framework, but belonged with the request object.

Checking the request

Detecting various request conditions used to require using RequestHandlerComponent. These methods have been moved to CakeRequest, and offer a new interface alongside a more backwards compatible usage:

Both method calls will return the same value. For the time being the methods are still available on RequestHandler, but are deprecated and still might be removed before the final release. You can also easily extend the request detectors that are available, by using CakeRequest::addDetector() to create new kinds of detectors. There are four different types of detectors that you can create:

• Environment value comparison – An environment value comparison, compares a value fetched from env() to a known value the environment value is equality checked against the provided value.
• Pattern value comparison – Pattern value comparison allows you to compare a value fetched from env() to a regular expression.
• Option based comparison – Option based comparisons use a list of options to create a regular expression. Subsequent calls to add an already defined options detector will merge the options.
• Callback detectors – Callback detectors allow you to provide a ‘callback’ type to handle the check. The callback will receive the request object as its only parameter.

Some examples would be:

CakeRequest also includes methods like domain(), subdomains() and host() to help applications with subdomains, have a slightly easier life.

CakeRequest and RequestHandlerComponent

Since many of the features CakeRequest offers used to be the realm of RequestHandlerComponent some rethinking was required to figure out how it still fits into the picture. I was never really happy with having to use a component that did many things on top of request introspection just to get the request introspection. For 2.0, RequestHandlerComponent acts as a sugar daddy. Providing a layer of sugar on top of the utility CakeRequest affords. Sugar like switching layout and views based on content types or ajax is the domain of RequestHandlerComponent. This separation of utility and sugar between the two classes lets you more easily pick and choose what you want and what you need. Although the work for CakeRequest is not 100% complete, as some deprecated code still needs to be excised, the transformation is mostly complete, and I’m rather happy with the way it turned out.