0% found this document useful (0 votes)

324 views1,107 pages

Cake PHP Cookbook

The CakePHP Cookbook Documentation (Release 2.x) provides comprehensive guidance on using the CakePHP framework, including installation, configuration, and development practices. It covers essential topics such as MVC architecture, controllers, views, models, plugins, and console usage, along with tutorials and migration guides. The documentation is intended for developers looking to build applications using CakePHP, with detailed explanations and examples.

Uploaded by

Vũ Long

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

324 views1,107 pages

Cake PHP Cookbook

Uploaded by

Vũ Long

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 1107

CakePHP Cookbook Documentation

Release 2.x

Cake Software Foundation

September 19, 2013

Contents

Getting Started Blog Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Blog Tutorial - Adding a layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installation Requirements . . . . . . . . . . . . . . . License . . . . . . . . . . . . . . . . . . Downloading CakePHP . . . . . . . . . . Permissions . . . . . . . . . . . . . . . . Setup . . . . . . . . . . . . . . . . . . . Development . . . . . . . . . . . . . . . Production . . . . . . . . . . . . . . . . . Advanced Installation and URL Rewriting Fire It Up . . . . . . . . . . . . . . . . .

1 1 8 29 29 29 30 30 30 30 31 32 39

. . . . . . . . .

CakePHP Overview 41 What is CakePHP? Why Use it? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Understanding Model-View-Controller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 Where to Get Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 Controllers The App Controller . . . . . Request parameters . . . . . Controller actions . . . . . . Request Life-cycle callbacks Controller Methods . . . . . Controller Attributes . . . . More on controllers . . . . . Views 47 47 48 48 49 50 57 59 129 i

. . . . . . .

View Templates . . . . . . . . Using view blocks . . . . . . . Layouts . . . . . . . . . . . . Elements . . . . . . . . . . . . Creating your own view classes View API . . . . . . . . . . . More about Views . . . . . . . 6

. . . . . . .

129 131 133 135 138 139 141

Models 241 Understanding Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241 More on models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243 Core Libraries General Purpose Behaviors . . . Components . . Helpers . . . . Utilities . . . . 369 369 570 598 648 738 849 849 849 850 851 851 852 853 853 854 855 855 856 857 857 859 860 862 862 863 864 871 871 874

. . . . .

Plugins Installing a Plugin . . . . . . . . . . Plugin conguration . . . . . . . . . Advanced bootstrapping . . . . . . Using a Plugin . . . . . . . . . . . . Creating Your Own Plugins . . . . . Plugin Controllers . . . . . . . . . . Plugin Models . . . . . . . . . . . . Plugin Views . . . . . . . . . . . . Plugin assets . . . . . . . . . . . . . Components, Helpers and Behaviors Expand Your Plugin . . . . . . . . . Plugin Tips . . . . . . . . . . . . .

. . . . . . . . . . . .

Console and Shells The CakePHP console . . . . . . . . . . Creating a shell . . . . . . . . . . . . . Shell tasks . . . . . . . . . . . . . . . . Invoking other shells from your shell . . Console output levels . . . . . . . . . . Styling output . . . . . . . . . . . . . . Conguring options and generating help Routing in shells / CLI . . . . . . . . . Shell API . . . . . . . . . . . . . . . . More topics . . . . . . . . . . . . . . .

. . . . . . . . . .

10 Development 887 Conguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 887 Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 900

Sessions . . . . . Exceptions . . . . Error Handling . Debugging . . . . Testing . . . . . . REST . . . . . . Dispatcher Filters Vendor packages

. . . . . . . .

917 922 929 931 934 957 960 964 965 965 965 965 966 967 967 974 985 992 998

11 Deployment Check your security . . . . . . . . . . . Set document root . . . . . . . . . . . . Update core.php . . . . . . . . . . . . . Improve your applications performance

. . . .

12 Tutorials & Examples Blog Tutorial . . . . . . . . . . . . . . . . . . . . . Blog Tutorial - Adding a layer . . . . . . . . . . . . Simple Authentication and Authorization Application Simple Acl controlled Application . . . . . . . . . . Simple Acl controlled Application - part 2 . . . . . . 13 Appendices 2.4 Migration Guide . . . 2.3 Migration Guide . . . 2.2 Migration Guide . . . 2.1 Migration Guide . . . 2.0 Migration Guide . . . Migration from 1.2 to 1.3 General Information . . . 14 Indices and tables Index

. . . . .

. . . . . . .

1003 . 1003 . 1009 . 1016 . 1022 . 1033 . 1066 . 1085 1089 1091

iii

CHAPTER 1

Getting Started

The CakePHP framework provides a robust base for your application. It can handle every aspect, from the users initial request all the way to the nal rendering of a web page. And since the framework follows the principles of MVC, it allows you to easily customize and extend most aspects of your application. The framework also provides a basic organizational structure, from lenames to database table names, keeping your entire application consistent and logical. This concept is simple but powerful. Follow the conventions and youll always know exactly where things are and how theyre organized. The best way to experience and learn CakePHP is to sit down and build something. To start off well build a simple blog application.

Blog Tutorial
Welcome to CakePHP. Youre probably checking out this tutorial because you want to learn more about how CakePHP works. Its our aim to increase productivity and make coding more enjoyable: we hope youll see this as you dive into the code. This tutorial will walk you through the creation of a simple blog application. Well be getting and installing Cake, creating and conguring a database, and creating enough application logic to list, add, edit, and delete blog posts. Heres what youll need: 1. A running web server. Were going to assume youre using Apache, though the instructions for using other servers should be very similar. We might have to play a little with the server conguration, but most folks can get Cake up and running without any conguration at all. Make sure you have PHP 5.2.8 or greater. 2. A database server. Were going to be using MySQL server in this tutorial. Youll need to know enough about SQL in order to create a database: Cake will be taking the reins from there. Since were using MySQL, also make sure that you have pdo_mysql enabled in PHP. 3. Basic PHP knowledge. The more object-oriented programming youve done, the better: but fear not if youre a procedural fan. 1

CakePHP Cookbook Documentation, Release 2.x

4. Finally, youll need a basic knowledge of the MVC programming pattern. A quick overview can be found in Understanding Model-View-Controller. Dont worry, its only a half a page or so. Lets get started!

Getting Cake
First, lets get a copy of fresh Cake code. To get a fresh download, visit the CakePHP project on GitHub: https://github.com/cakephp/cakephp/tags and download the latest release of 2.0 You can also clone the repository using git://github.com/cakephp/cakephp.git git (http://git-scm.com/). git clone

Regardless of how you downloaded it, place the code inside of your DocumentRoot. Once nished, your directory setup should look something like the following:
/path_to_document_root /app /lib /plugins /vendors .htaccess index.php README

Now might be a good time to learn a bit about how Cakes directory structure works: check out the CakePHP Folder Structure section.

Creating the Blog Database

Next, lets set up the underlying database for our blog. If you havent already done so, create an empty database for use in this tutorial, with a name of your choice. Right now, well just create a single table to store our posts. Well also throw in a few posts right now to use for testing purposes. Execute the following SQL statements into your database:
/* First, create our posts table: */ CREATE TABLE posts ( id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY, title VARCHAR(50), body TEXT, created DATETIME DEFAULT NULL, modified DATETIME DEFAULT NULL ); /* Then insert some posts for testing: */ INSERT INTO posts (title,body,created) VALUES (The title, This is the post body., NOW()); INSERT INTO posts (title,body,created) VALUES (A title once again, And the post body follows., NOW());

Chapter 1. Getting Started

CakePHP Cookbook Documentation, Release 2.x

INSERT INTO posts (title,body,created) VALUES (Title strikes back, This is really exciting! Not., NOW());

The choices on table and column names are not arbitrary. If you follow Cakes database naming conventions, and Cakes class naming conventions (both outlined in CakePHP Conventions), youll be able to take advantage of a lot of free functionality and avoid conguration. Cake is exible enough to accommodate even the worst legacy database schema, but adhering to convention will save you time. Check out CakePHP Conventions for more information, but sufce it to say that naming our table posts automatically hooks it to our Post model, and having elds called modied and created will be automagically managed by Cake.

Cake Database Conguration

Onward and upward: lets tell Cake where our database is and how to connect to it. For many, this is the rst and last time you congure anything. A copy of CakePHPs database conguration le is found in /app/Config/database.php.default. Make a copy of this le in the same directory, but name it database.php. The cong le should be pretty straightforward: just replace the values in the $default array with those that apply to your setup. A sample completed conguration array might look something like the following:
public $default = array( datasource => Database/Mysql, persistent => false, host => localhost, port => , login => cakeBlog, password => c4k3-rUl3Z, database => cake_blog_tutorial, schema => , prefix => , encoding => utf8 );

Once youve saved your new database.php le, you should be able to open your browser and see the Cake welcome page. It should also tell you that your database connection le was found, and that Cake can successfully connect to the database. Note: Remember that youll need to have PDO, and pdo_mysql enabled in your php.ini.

Optional Conguration
There are three other items that can be congured. Most developers complete these laundry-list items, but theyre not required for this tutorial. One is dening a custom string (or salt) for use in security hashes. The second is dening a custom number (or seed) for use in encryption. The third item is allowing CakePHP write access to its tmp folder. Blog Tutorial 3

CakePHP Cookbook Documentation, Release 2.x

The security salt is used for generating hashes. Change the default salt value by editing /app/Config/core.php line 187. It doesnt much matter what the new value is, as long as its not easily guessed:
/** * A random string used in security hashing methods. */ Configure::write(Security.salt, pl345e-P45s_7h3*S@l7!);

The cipher seed is used for encrypt/decrypt strings. Change the default seed value by editing /app/Config/core.php line 192. It doesnt much matter what the new value is, as long as its not easily guessed:
/** * A random numeric string (digits only) used to encrypt/decrypt strings. */ Configure::write(Security.cipherSeed, 7485712659625147843639846751);

The nal task is to make the app/tmp directory web-writable. The best way to do this is to nd out what user your webserver runs as (<?php echo whoami; ?>) and change the ownership of the app/tmp directory to that user. The nal command you run (in *nix) might look something like this:
$ chown -R www-data app/tmp

If for some reason CakePHP cant write to that directory, youll be informed by a warning while not in production mode.

A Note on mod_rewrite
Occasionally a new user will run into mod_rewrite issues. For example if the CakePHP welcome page looks a little funny (no images or css styles), it probably means mod_rewrite isnt functioning on your system. Please refer to one of the sections below about url rewriting for your webserver to get you up and running: URL Rewriting
Apache and mod_rewrite (and .htaccess)

While CakePHP is built to work with mod_rewrite out of the boxand usually doesweve noticed that a few users struggle with getting everything to play nicely on their systems. Here are a few things you might try to get it running correctly. First look at your httpd.conf (Make sure you are editing the system httpd.conf rather than a user- or site-specic httpd.conf). 1. Make sure that an .htaccess override is allowed and that AllowOverride is set to All for the correct DocumentRoot. You should see something similar to:
# Each directory to which Apache has access can be configured with respect # to which services and features are allowed and/or disabled in that # directory (and its subdirectories). #

Chapter 1. Getting Started

CakePHP Cookbook Documentation, Release 2.x

# First, we configure the "default" to be a very restrictive set of # features. # <Directory /> Options FollowSymLinks AllowOverride All # Order deny,allow # Deny from all </Directory>

2. Make sure you are loading up mod_rewrite correctly. You should see something like:
LoadModule rewrite_module libexec/apache2/mod_rewrite.so

In many systems these will be commented out (by being prepended with a #) by default, so you may just need to remove those leading # symbols. After you make changes, restart Apache to make sure the settings are active. Verify that you your .htaccess les are actually in the right directories. This can happen during copying because some operating systems treat les that start with . as hidden and therefore wont see them to copy. 3. Make sure your copy of CakePHP is from the downloads section of the site or our GIT repository, and has been unpacked correctly by checking for .htaccess les. Cake root directory (needs to be copied to your document, this redirects everything to your Cake app):
<IfModule mod_rewrite.c> RewriteEngine on RewriteRule ^ $ app/webroot/ RewriteRule </IfModule>

[L]

(.*) app/webroot/ $ 1 [L]

Cake app directory (will be copied to the top directory of your application by bake):
<IfModule mod_rewrite.c> RewriteEngine on RewriteRule ^$ webroot/ RewriteRule </IfModule> (.*) webroot/ $ 1

[L] [L]

Cake webroot directory (will be copied to your applications web root by bake):
<IfModule mod_rewrite.c> RewriteEngine On RewriteCond %{REQUEST_FILENAME} !-d RewriteCond %{REQUEST_FILENAME} !-f RewriteRule ^(.*) $ index.php [QSA,L] </IfModule>

Blog Tutorial

CakePHP Cookbook Documentation, Release 2.x

tion dependent). In this le, ensure that AllowOverride None is changed to AllowOverride All, so you have:
<Directory /> Options FollowSymLinks AllowOverride All </Directory> <Directory /var/www> Options Indexes FollowSymLinks MultiViews AllowOverride All Order Allow,Deny Allow from all </Directory>

If on Mac OSX, another solution is to use the tool virtualhostx to make a virtual host to point to your folder. For many hosting services (GoDaddy, 1and1), your web server is actually being served from a user directory that already uses mod_rewrite. If you are installing CakePHP into a user directory (http://example.com/~username/cakephp/), or any other URL structure that already utilizes mod_rewrite, youll need to add RewriteBase statements to the .htaccess les CakePHP uses (/.htaccess, /app/.htaccess, /app/webroot/.htaccess). This can be added to the same section with the RewriteEngine directive, so for example your webroot .htaccess le would look like:
<IfModule mod_rewrite.c> RewriteEngine On RewriteBase /path/to/cake/app RewriteCond %{REQUEST_FILENAME} !-d RewriteCond %{REQUEST_FILENAME} !-f RewriteRule ^(.*) $ index.php [QSA,L] </IfModule>

The details of those changes will depend on your setup, and can include additional things that are not Cake related. Please refer to Apaches online documentation for more information. 4. (Optional) To improve production setup, you should prevent invalid assets from being parsed by CakePHP. Modify your webroot .htaccess to something like:
<IfModule mod_rewrite.c> RewriteEngine On RewriteBase /path/to/cake/app RewriteCond %{REQUEST_FILENAME} !-d RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_URI} !^/(app/webroot/)?(img|css|js)/(.*) $ RewriteRule ^(.*) $ index.php [QSA,L] </IfModule>

The above will simply prevent incorrect assets from being sent to index.php and instead display your webservers 404 page. Additionally you can create a matching HTML 404 page, or use the default built-in CakePHP 404 by adding an ErrorDocument directive: 6 Chapter 1. Getting Started

CakePHP Cookbook Documentation, Release 2.x

ErrorDocument 404 /404-not-found

Pretty URLs on nginx

nginx is a popular server that uses less system resources than Apache. Its drawback is that it does not make use of .htaccess les like Apache, so it is necessary to create those rewritten URLs in the site-available conguration. Depending upon your setup, you will have to modify this, but at the very least, you will need PHP running as a FastCGI instance.
server { listen 80; server_name www.example.com; rewrite ^(.*) http://example.com $ 1 permanent; } server { listen 80; server_name example.com; # root directive should be global root /var/www/example.com/public/app/webroot/; index index.php; access_log /var/www/example.com/log/access.log; error_log /var/www/example.com/log/error.log; location / { try_files $uri $uri/ /index.php?$uri&$args; } location ~ \.php $ { try_files $uri =404; include /etc/nginx/fastcgi_params; fastcgi_pass 127.0.0.1:9000; fastcgi_index index.php; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; } }

URL Rewrites on IIS7 (Windows hosts)

IIS7 does not natively support .htaccess les. While there are add-ons that can add this support, you can also import htaccess rules into IIS to use CakePHPs native rewrites. To do this, follow these steps: 1. Use Microsofts Web Platform Installer (http://www.microsoft.com/web/downloads/platform.aspx) to install the URL Rewrite Module 2.0 (http://www.iis.net/downloads/microsoft/url-rewrite) or download it directly (32-bit (http://www.microsoft.com/en-us/download/details.aspx?id=5747) / 64-bit (http://www.microsoft.com/en-us/download/details.aspx?id=7435)). 2. Create a new le in your CakePHP root folder, called web.cong. Blog Tutorial 7

CakePHP Cookbook Documentation, Release 2.x

3. Using Notepad or any XML-safe editor and copy the following code into your new web.cong le...

<?xml version="1.0" encoding="UTF-8"?> <configuration> <system.webServer> <rewrite> <rules> <rule name="Rewrite requests to test.php" stopProcessing="true"> <match url="^test.php(.*)$" ignoreCase="false" /> <action type="Rewrite" url="app/webroot/test.php{R:1}" /> </rule> <rule name="Exclude direct access to app/webroot/*" stopProcessing="true"> <match url="^app/webroot/(.*)$" ignoreCase="false" /> <action type="None" /> </rule> <rule name="Rewrite routed access to assets (img, css, files, js, favicon)" <match url="^(img|css|files|js|favicon.ico)(.*)$" /> <action type="Rewrite" url="app/webroot/{R:1}{R:2}" appendQueryString=" </rule> <rule name="Rewrite requested file/folder to index.php" stopProcessing="tru <match url="^(.*)$" ignoreCase="false" /> <action type="Rewrite" url="index.php" appendQueryString="true" /> </rule> </rules> </rewrite> </system.webServer> </configuration>

Once the web.cong le is created with the correct IIS-friendly rewrite rules, CakePHPs links, css, js, and rerouting should work correctly.
I dont / cant use URL rewriting

If you dont want to or cant use URL rewriting on your webserver, refer to the core conguration. Now continue to Blog Tutorial - Adding a layer to start building your rst CakePHP application.

Blog Tutorial - Adding a layer

Create a Post Model
The Model class is the bread and butter of CakePHP applications. By creating a CakePHP model that will interact with our database, well have the foundation in place needed to do our view, add, edit, and delete operations later. CakePHPs model class les go in /app/Model, and the le well be creating will be saved to /app/Model/Post.php. The completed le should look like this:
class Post extends AppModel { }

Chapter 1. Getting Started

CakePHP Cookbook Documentation, Release 2.x

Naming conventions are very important in CakePHP. By naming our model Post, CakePHP can automatically infer that this model will be used in the PostsController, and will be tied to a database table called posts. Note: CakePHP will dynamically create a model object for you if it cannot nd a corresponding le in /app/Model. This also means that if you accidentally name your le wrong (i.e. post.php or posts.php), CakePHP will not recognize any of your settings and will use the defaults instead. For more on models, such as table prexes, callbacks, and validation, check out the Models chapter of the Manual.

Create a Posts Controller

Next, well create a controller for our posts. The controller is where all the business logic for post interaction will happen. In a nutshell, its the place where you play with the models and get post-related work done. Well place this new controller in a le called PostsController.php inside the /app/Controller directory. Heres what the basic controller should look like:
class PostsController extends AppController { public $helpers = array(Html, Form); }

Now, lets add an action to our controller. Actions often represent a single function or interface in an application. For example, when users request www.example.com/posts/index (which is also the same as www.example.com/posts/), they might expect to see a listing of posts. The code for that action would look something like this:
class PostsController extends AppController { public $helpers = array(Html, Form); public function index() { $this->set(posts, $this->Post->find(all)); } }

By dening function index() in our PostsController, users can now access the logic there by requesting www.example.com/posts/index. Similarly, if we were to dene a function called foobar(), users would be able to access that at www.example.com/posts/foobar. Warning: You may be tempted to name your controllers and actions a certain way to obtain a certain URL. Resist that temptation. Follow CakePHP conventions (plural controller names, etc.) and create readable, understandable action names. You can map URLs to your code using routes covered later on. The single instruction in the action uses set() to pass data from the controller to the view (which well create next). The line sets the view variable called posts equal to the return value of the find(all) method of the Post model. Our Post model is automatically available at $this->Post because weve followed Cakes naming conventions.

Blog Tutorial - Adding a layer

CakePHP Cookbook Documentation, Release 2.x

To learn more about Cakes controllers, check out the Controllers chapter.

Creating Post Views

Now that we have our data owing to our model, and our application logic and ow dened by our controller, lets create a view for the index action we created above. Cake views are just presentation-avored fragments that t inside an applications layout. For most applications theyre HTML mixed with PHP, but they may end up as XML, CSV, or even binary data. Layouts are presentation code that is wrapped around a view, and can be dened and switched between, but for now, lets just use the default. Remember in the last section how we assigned the posts variable to the view using the set() method? That would hand down data to the view that would look something like this:
// print_r($posts) output: Array ( [0] => Array ( [Post] => Array ( [id] => 1 [title] => The title [body] => This is the post body. [created] => 2008-02-13 18:34:55 [modified] => ) ) [1] => Array ( [Post] => Array ( [id] => 2 [title] => A title once again [body] => And the post body follows. [created] => 2008-02-13 18:34:56 [modified] => ) ) [2] => Array ( [Post] => Array ( [id] => 3 [title] => Title strikes back [body] => This is really exciting! Not. [created] => 2008-02-13 18:34:57 [modified] => )

Chapter 1. Getting Started

CakePHP Cookbook Documentation, Release 2.x

) )

Cakes view les are stored in /app/View inside a folder named after the controller they correspond to (well have to create a folder named Posts in this case). To format this post data in a nice table, our view code might look something like this
 <h1>Blog posts</h1> <table> <tr> <th>Id</th> <th>Title</th> <th>Created</th> </tr>  <?php foreach ($posts as $post): ?> <tr> <td><?php echo $post[Post][id]; ?></td> <td> <?php echo $this->Html->link($post[Post][title], array(controller => posts, action => view, $post[Post][id])); ?> </td> <td><?php echo $post[Post][created]; ?></td> </tr> <?php endforeach; ?> <?php unset($post); ?> </table>

Hopefully this should look somewhat simple. You might have noticed the use of an object called $this->Html. This is an instance of the CakePHP HtmlHelper class. CakePHP comes with a set of view helpers that make things like linking, form output, JavaScript and Ajax a snap. You can learn more about how to use them in Helpers, but whats important to note here is that the link() method will generate an HTML link with the given title (the rst parameter) and URL (the second parameter). When specifying URLs in Cake, it is recommended that you use the array format. This is explained in more detail in the section on Routes. Using the array format for URLs allows you to take advantage of CakePHPs reverse routing capabilities. You can also specify URLs relative to the base of the application in the form of /controller/action/param1/param2. At this point, you should be able to point your browser to http://www.example.com/posts/index. You should see your view, correctly formatted with the title and table listing of the posts. If you happened to have clicked on one of the links we created in this view (that link a posts title to a URL /posts/view/some_id), you were probably informed by CakePHP that the action hasnt yet been dened. If you were not so informed, either something has gone wrong, or you actually did dene it already, in which case you are very sneaky. Otherwise, well create it in the PostsController now:

Blog Tutorial - Adding a layer

CakePHP Cookbook Documentation, Release 2.x

class PostsController extends AppController { public $helpers = array(Html, Form); public function index() { $this->set(posts, $this->Post->find(all)); } public function view($id = null) { if (!$id) { throw new NotFoundException(__(Invalid post)); } $post = $this->Post->findById($id); if (!$post) { throw new NotFoundException(__(Invalid post)); } $this->set(post, $post); } }

The set() call should look familiar. Notice were using findById() rather than find(all) because we only really want a single posts information. Notice that our view action takes a parameter: the ID of the post wed like to see. This parameter is handed to the action through the requested URL. If a user requests /posts/view/3, then the value 3 is passed as $id. We also do a bit of error checking to ensure a user is actually accessing a record. If a user requests /posts/view, we will throw a NotFoundException and let the CakePHP ErrorHandler take over. We also perform a similar check to make sure the user has accessed a record that exists. Now lets create the view for our new view action and place it in /app/View/Posts/view.ctp
 <h1><?php echo h($post[Post][title]); ?></h1> <p><small>Created: <?php echo $post[Post][created]; ?></small></p> <p><?php echo h($post[Post][body]); ?></p>

Verify that this is working by trying the links at /posts/index or manually requesting a post by accessing /posts/view/1.

Adding Posts
Reading from the database and showing us the posts is a great start, but lets allow for the adding of new posts. First, start by creating an add() action in the PostsController:

Chapter 1. Getting Started

CakePHP Cookbook Documentation, Release 2.x

class PostsController extends AppController { public $helpers = array(Html, Form, Session); public $components = array(Session); public function index() { $this->set(posts, $this->Post->find(all)); } public function view($id) { if (!$id) { throw new NotFoundException(__(Invalid post)); } $post = $this->Post->findById($id); if (!$post) { throw new NotFoundException(__(Invalid post)); } $this->set(post, $post); } public function add() { if ($this->request->is(post)) { $this->Post->create(); if ($this->Post->save($this->request->data)) { $this->Session->setFlash(__(Your post has been saved.)); return $this->redirect(array(action => index)); } $this->Session->setFlash(__(Unable to add your post.)); } } }

Note: You need to include the SessionComponent - and SessionHelper - in any controller where you will use it. If necessary, include it in your AppController. Heres what the add() action does: if the HTTP method of the request was POST, try to save the data using the Post model. If for some reason it doesnt save, just render the view. This gives us a chance to show the user validation errors or other warnings. Every CakePHP request includes a CakeRequest object which is accessible using $this->request. The request object contains useful information regarding the request that was just received, and can be used to control the ow of your application. In this case, we use the CakeRequest::is() method to check that the request is a HTTP POST request. When a user uses a form to POST data to your application, that information is available in $this->request->data. You can use the pr() or debug() functions to print it out if you want to see what it looks like. We use the SessionComponents SessionComponent::setFlash() method to set a message to a session variable to be displayed on the page after redirection. In the layout we have SessionHelper::flash which displays the message and clears the corresponding session vari-

Blog Tutorial - Adding a layer

CakePHP Cookbook Documentation, Release 2.x

able. The controllers Controller::redirect function redirects to another URL. The param array(action => index) translates to URL /posts i.e the index action of posts controller. You can refer to Router::url() function on the API (http://api20.cakephp.org) to see the formats in which you can specify a URL for various Cake functions. Calling the save() method will check for validation errors and abort the save if any occur. Well discuss how those errors are handled in the following sections.

Data Validation
Cake goes a long way in taking the monotony out of form input validation. Everyone hates coding up endless forms and their validation routines. CakePHP makes it easier and faster. To take advantage of the validation features, youll need to use Cakes FormHelper in your views. The FormHelper is available by default to all views at $this->Form. Heres our add view:
 <h1>Add Post</h1> <?php echo $this->Form->create(Post); echo $this->Form->input(title); echo $this->Form->input(body, array(rows => 3)); echo $this->Form->end(Save Post); ?>

Here, we use the FormHelper to generate the opening tag for an HTML form. Heres the HTML that $this->Form->create() generates:
<form id="PostAddForm" method="post" action="/posts/add">

If create() is called with no parameters supplied, it assumes you are building a form that submits to the current controllers add() action (or edit() action when id is included in the form data), via POST. The $this->Form->input() method is used to create form elements of the same name. The rst parameter tells CakePHP which eld they correspond to, and the second parameter allows you to specify a wide array of options - in this case, the number of rows for the textarea. Theres a bit of introspection and automagic here: input() will output different form elements based on the model eld specied. The $this->Form->end() call generates a submit button and ends the form. If a string is supplied as the rst parameter to end(), the FormHelper outputs a submit button named accordingly along with the closing form tag. Again, refer to Helpers for more on helpers. Now lets go back and update our /app/View/Posts/index.ctp view to include a new Add Post link. Before the <table>, add the following line:
<?php echo $this->Html->link( Add Post, array(controller => posts, action => add) ); ?>

Chapter 1. Getting Started

CakePHP Cookbook Documentation, Release 2.x

You may be wondering: how do I tell CakePHP about my validation requirements? Validation rules are dened in the model. Lets look back at our Post model and make a few adjustments:
class Post extends AppModel { public $validate = array( title => array( rule => notEmpty ), body => array( rule => notEmpty ) ); }

The $validate array tells CakePHP how to validate your data when the save() method is called. Here, Ive specied that both the body and title elds must not be empty. CakePHPs validation engine is strong, with a number of pre-built rules (credit card numbers, email addresses, etc.) and exibility for adding your own validation rules. For more information on that setup, check the Data Validation. Now that you have your validation rules in place, use the app to try to add a post with an empty title or body to see how it works. Since weve used the FormHelper::input() method of the FormHelper to create our form elements, our validation error messages will be shown automatically.

Editing Posts
Post editing: here we go. Youre a CakePHP pro by now, so you should have picked up a pattern. Make the action, then the view. Heres what the edit() action of the PostsController would look like:
public function edit($id = null) { if (!$id) { throw new NotFoundException(__(Invalid post)); } $post = $this->Post->findById($id); if (!$post) { throw new NotFoundException(__(Invalid post)); } if ($this->request->is(post) || $this->request->is(put)) { $this->Post->id = $id; if ($this->Post->save($this->request->data)) { $this->Session->setFlash(__(Your post has been updated.)); return $this->redirect(array(action => index)); } $this->Session->setFlash(__(Unable to update your post.)); } if (!$this->request->data) { $this->request->data = $post; } }

Blog Tutorial - Adding a layer

CakePHP Cookbook Documentation, Release 2.x

This action rst ensures that the user has tried to access an existing record. If they havent passed in a passed in an $id parameter, or the post does not exist, we throw a NotFoundException for the CakePHP ErrorHandler to take care of. Next the action checks that the request is a POST request. If it is, then we use the POST data to update our Post record, or kick back and show the user validation errors. If there is no data set to $this->request->data, we simply set it to the previously retrieved post. The edit view might look something like this:
 <h1>Edit <?php echo echo echo echo echo ?> Post</h1> $this->Form->create(Post); $this->Form->input(title); $this->Form->input(body, array(rows => 3)); $this->Form->input(id, array(type => hidden)); $this->Form->end(Save Post);

This view outputs the edit form (with the values populated), along with any necessary validation error messages. One thing to note here: CakePHP will assume that you are editing a model if the id eld is present in the data array. If no id is present (look back at our add view), Cake will assume that you are inserting a new model when save() is called. You can now update your index view with links to edit specic posts:

<h1>Blog posts</h1> <p><?php echo $this->Html->link("Add Post", array(action => add)); ?></p> <table> <tr> <th>Id</th> <th>Title</th> <th>Action</th> <th>Created</th> </tr>

<?php foreach ($posts as $post): ?> <tr> <td><?php echo $post[Post][id]; ?></td> <td> <?php echo $this->Html->link($post[Post][title], array(action => view, </td> <td> <?php echo $this->Html->link(Edit, array(action => edit, $post[Post][i </td> <td>

Chapter 1. Getting Started

CakePHP Cookbook Documentation, Release 2.x

<?php echo $post[Post][created]; ?> </td> </tr> <?php endforeach; ?> </table>

Deleting Posts
Next, lets make a way for users to delete posts. Start with a delete() action in the PostsController:
public function delete($id) { if ($this->request->is(get)) { throw new MethodNotAllowedException(); } if ($this->Post->delete($id)) { $this->Session->setFlash(__(The post with id: %s has been deleted., h($id))); return $this->redirect(array(action => index)); } }

This logic deletes the post specied by $id, and uses $this->Session->setFlash() to show the user a conrmation message after redirecting them on to /posts. If the user attempts to do a delete using a GET request, we throw an Exception. Uncaught exceptions are captured by CakePHPs exception handler, and a nice error page is displayed. There are many built-in Exceptions that can be used to indicate the various HTTP errors your application might need to generate. Because were just executing some logic and redirecting, this action has no view. You might want to update your index view with links that allow users to delete posts, however:
 <h1>Blog posts</h1> <p><?php echo $this->Html->link(Add Post, array(action => add)); ?></p> <table> <tr> <th>Id</th> <th>Title</th> <th>Actions</th> <th>Created</th> </tr>  <?php foreach ($posts as $post): ?> <tr> <td><?php echo $post[Post][id]; ?></td> <td> <?php echo $this->Html->link($post[Post][title], array(action => view, </td> <td>

Blog Tutorial - Adding a layer

CakePHP Cookbook Documentation, Release 2.x

<?php echo $this->Form->postLink( Delete, array(action => delete, $post[Post][id]), array(confirm => Are you sure?)); ?> <?php echo $this->Html->link(Edit, array(action => edit, $post[Post][i </td> <td> <?php echo $post[Post][created]; ?> </td> </tr> <?php endforeach; ?> </table>

Using postLink() will create a link that uses Javascript to do a POST request deleting our post. Allowing content to be deleted using GET requests is dangerous, as web crawlers could accidentally delete all your content. Note: This view code also uses the FormHelper to prompt the user with a JavaScript conrmation dialog before they attempt to delete a post.

Routes
For some, CakePHPs default routing works well enough. Developers who are sensitive to user-friendliness and general search engine compatibility will appreciate the way that CakePHPs URLs map to specic actions. So well just make a quick change to routes in this tutorial. For more information on advanced routing techniques, see Routes Conguration. By default, CakePHP responds to a request for the root of your site (i.e. http://www.example.com) using its PagesController, rendering a view called home. Instead, well replace this with our PostsController by creating a routing rule. Cakes routing is found in /app/Config/routes.php. Youll want to comment out or remove the line that denes the default root route. It looks like this:
Router::connect(/, array(controller => pages, action => display, home));

This line connects the URL / with the default CakePHP home page. We want it to connect with our own controller, so replace that line with this one:
Router::connect(/, array(controller => posts, action => index));

This should connect users requesting / to the index() action of our PostsController. Note: CakePHP also makes use of reverse routing - if with the above route dened you pass array(controller => posts, action => index) to a function expecting an array, the resultant URL used will be /. Its therefore a good idea to always use arrays for URLs as this means your routes dene where a URL goes, and also ensures that links point to the same place too. 18 Chapter 1. Getting Started

CakePHP Cookbook Documentation, Release 2.x

Conclusion
Creating applications this way will win you peace, honor, love, and money beyond even your wildest fantasies. Simple, isnt it? Keep in mind that this tutorial was very basic. CakePHP has many more features to offer, and is exible in ways we didnt wish to cover here for simplicitys sake. Use the rest of this manual as a guide for building more feature-rich applications. Now that youve created a basic Cake application youre ready for the real thing. Start your own project, read the rest of the Cookbook and API (http://api20.cakephp.org). If you need help, there are many ways to get the help you need - please see the Where to Get Help page. Welcome to CakePHP! Suggested Follow-up Reading These are common tasks people learning CakePHP usually want to study next: 1. Layouts: Customizing your website layout 2. Elements: Including and reusing view snippets 3. Scaffolding: Prototyping before creating code 4. Code Generation with Bake: Generating basic CRUD code 5. Simple Authentication and Authorization Application: User authentication and authorization tutorial

Additional Reading
A Typical CakePHP Request Weve covered the basic ingredients in CakePHP, so lets look at how objects work together to complete a basic request. Continuing with our original request example, lets imagine that our friend Ricardo just clicked on the Buy A Custom Cake Now! link on a CakePHP applications landing page. Figure: 2. Typical Cake Request. Black = required element, Gray = optional element, Blue = callback 1. Ricardo clicks the link pointing to http://www.example.com/cakes/buy, and his browser makes a request to your web server. 2. The Router parses the URL in order to extract the parameters for this request: the controller, action, and any other arguments that will affect the business logic during this request. 3. Using routes, a request URL is mapped to a controller action (a method in a specic controller class). In this case, its the buy() method of the CakesController. The controllers beforeFilter() callback is called before any controller action logic is executed.

Blog Tutorial - Adding a layer

CakePHP Cookbook Documentation, Release 2.x

Figure 1.1: Flow diagram showing a typical CakePHP request

Chapter 1. Getting Started

CakePHP Cookbook Documentation, Release 2.x

4. The controller may use models to gain access to the applications data. In this example, the controller uses a model to fetch Ricardos last purchases from the database. Any applicable model callbacks, behaviors, and DataSources may apply during this operation. While model usage is not required, all CakePHP controllers initially require at least one model. 5. After the model has retrieved the data, it is returned to the controller. Model callbacks may apply. 6. The controller may use components to further rene the data or perform other operations (session manipulation, authentication, or sending emails, for example). 7. Once the controller has used models and components to prepare the data sufciently, that data is handed to the view using the controllers set() method. Controller callbacks may be applied before the data is sent. The view logic is performed, which may include the use of elements and/or helpers. By default, the view is rendered inside of a layout. 8. Additional controller callbacks (like afterFilter) may be applied. The complete, rendered view code is sent to Ricardos browser. CakePHP Conventions We are big fans of convention over conguration. While it takes a bit of time to learn CakePHPs conventions, you save time in the long run: by following convention, you get free functionality, and you free yourself from the maintenance nightmare of tracking cong les. Convention also makes for a very uniform system development, allowing other developers to jump in and help more easily. CakePHPs conventions have been distilled out of years of web development experience and best practices. While we suggest you use these conventions while developing with CakePHP, we should mention that many of these tenets are easily overridden something that is especially handy when working with legacy systems.
Controller Conventions

Controller classnames are plural, CamelCased, and end in Controller. PeopleController and LatestArticlesController are both examples of conventional controller names. The rst method you write for a controller might be the index() method. When a request species a controller but not an action, the default CakePHP behavior is to execute the index() method of that controller. For example, a request for http://www.example.com/apples/ maps to a call on the index() method of the ApplesController, whereas http://www.example.com/apples/view/ maps to a call on the view() method of the ApplesController. You can also change the visibility of controller methods in CakePHP by prexing controller method names with underscores. If a controller method has been prexed with an underscore, the method will not be accessible directly from the web but is available for internal use. For example:
class NewsController extends AppController { public function latest() { $this->_findNewArticles(); } protected function _findNewArticles() {

Blog Tutorial - Adding a layer

CakePHP Cookbook Documentation, Release 2.x

// Logic to find latest news articles } }

While the page http://www.example.com/news/latest/ would be accessible to the user as usual, someone trying to get to the page http://www.example.com/news/_ndNewArticles/ would get an error, because the method is preceded with an underscore. You can also use PHPs visibility keywords to indicate whether or not a method can be accessed from a url. Non-public methods cannot be accessed. URL Considerations for Controller Names As youve just seen, single word controllers map easily to a simple lower case URL path. For example, ApplesController (which would be dened in the le name ApplesController.php) is accessed from http://example.com/apples. Multiple word controllers can be any inected form which equals the controller name so: /redApples /RedApples /Red_apples /red_apples will all resolve to the index of the RedApples controller. However, the convention is that your urls are lowercase and underscored, therefore /red_apples/go_pick is the correct form to access the RedApplesController::go_pick action. For more information on CakePHP URLs and parameter handling, see Routes Conguration.
File and Classname Conventions

In general, lenames match the classnames, which are CamelCased. So if you have a class MyNiftyClass, then in Cake, the le should be named MyNiftyClass.php. Below are examples of how to name the le for each of the different types of classes you would typically use in a CakePHP application: The Controller class KissesAndHugsController would be found in a le named KissesAndHugsController.php The Component class MyHandyComponent would be found in a le named MyHandyComponent.php The Model class OptionValue would be found in a le named OptionValue.php The Behavior class EspeciallyFunkableBehavior would be found in a le named EspeciallyFunkableBehavior.php The View class SuperSimpleView would be found in a le named SuperSimpleView.php The Helper class BestEverHelper would be found in a le named BestEverHelper.php Each le would be located in the appropriate folder in your app folder.

Chapter 1. Getting Started

CakePHP Cookbook Documentation, Release 2.x

Model and Database Conventions

Model classnames are singular and CamelCased. Person, BigPerson, and ReallyBigPerson are all examples of conventional model names. Table names corresponding to CakePHP models are plural and underscored. The underlying tables for the above mentioned models would be people, big_people, and really_big_people, respectively. You can use the utility library Inflector to check the singular/plural of words. See the Inector for more information. Field names with two or more words are underscored like, rst_name. Foreign keys in hasMany, belongsTo or hasOne relationships are recognized by default as the (singular) name of the related table followed by _id. So if a Baker hasMany Cake, the cakes table will refer to the bakers table via a baker_id foreign key. For a multiple worded table like category_types, the foreign key would be category_type_id. Join tables, used in hasAndBelongsToMany (HABTM) relationships between models should be named after the model tables they will join in alphabetical order (apples_zebras rather than zebras_apples). All tables with which CakePHP models interact (with the exception of join tables), require a singular primary key to uniquely identify each row. If you wish to model a table which does not have a single-eld primary key, CakePHPs convention is that a single-eld primary key is added to the table. You have to add a single-eld primary key if you want to use that tables model. CakePHP does not support composite primary keys. If you want to directly manipulate your join table data, use direct query calls or add a primary key to act on it as a normal model. E.g.:
CREATE TABLE posts_tags ( id INT(10) NOT NULL AUTO_INCREMENT, post_id INT(10) NOT NULL, tag_id INT(10) NOT NULL, PRIMARY KEY(id));

Rather than using an auto-increment key as the primary key, you may also use char(36). Cake will then use a unique 36 character uuid (String::uuid) whenever you save a new record using the Model::save method.
View Conventions

View template les are named after the controller functions they display, in an underscored form. The getReady() function of the PeopleController class will look for a view template in /app/View/People/get_ready.ctp. The basic pattern is /app/View/Controller/underscored_function_name.ctp. By naming the pieces of your application using CakePHP conventions, you gain functionality without the hassle and maintenance tethers of conguration. Heres a nal example that ties the conventions Database table: people Model class: Person, found at /app/Model/Person.php Controller class: PeopleController, found at /app/Controller/PeopleController.php Blog Tutorial - Adding a layer 23

CakePHP Cookbook Documentation, Release 2.x

View template, found at /app/View/People/index.ctp Using these conventions, CakePHP knows that a request to http://example.com/people/ maps to a call on the index() function of the PeopleController, where the Person model is automatically available (and automatically tied to the people table in the database), and renders to a le. None of these relationships have been congured by any means other than by creating classes and les that youd need to create anyway. Now that youve been introduced to CakePHPs fundamentals, you might try a run through the Blog Tutorial to see how things t together. CakePHP Folder Structure After youve downloaded and extracted CakePHP, these are the les and folders you should see: app lib vendors plugins .htaccess index.php README Youll notice three main folders: The app folder will be where you work your magic: its where your applications les will be placed. The lib folder is where weve worked our magic. Make a personal commitment not to edit les in this folder. We cant help you if youve modied the core. Finally, the vendors folder is where youll place third-party PHP libraries you need to use with your CakePHP applications.
The App Folder

CakePHPs app folder is where you will do most of your application development. Lets look a little closer at the folders inside of app. Cong Holds the (few) conguration les CakePHP uses. Database connection details, bootstrapping, core conguration les and more should be stored here. Console Contains the console commands and console tasks for your application. This directory can also contain a Templates directory to customize the output of bake. For more information see Console and Shells. Controller Contains your applications controllers and their components. Lib Contains 1st party libraries that do not come from 3rd parties or external vendors. This allows you to separate your organizations internal libraries from vendor libraries.

Chapter 1. Getting Started

CakePHP Cookbook Documentation, Release 2.x

Locale Stores string les for internationalization. Model Contains your applications models, behaviors, and datasources. Plugin Contains plugin packages. Test This directory contains all the test cases, and test xtures for your application. The Test/Case directory should mirror your application and contain one or more test cases per class in your application. For more information on test cases and test xtures refer to the Testing documentation. tmp This is where CakePHP stores temporary data. The actual data it stores depends on how you have CakePHP congured, but this folder is usually used to store model descriptions, logs, and sometimes session information. Make sure that this folder exists and that it is writable, otherwise the performance of your application will be severely impacted. In debug mode, CakePHP will warn you if it is not the case. Vendor Any third-party classes or libraries should be placed here. Doing so makes them easy to access using the App::import(vendor, name) function. Keen observers will note that this seems redundant, as there is also a vendors folder at the top level of our directory structure. Well get into the differences between the two when we discuss managing multiple applications and more complex system setups. View Presentational les are placed here: elements, error pages, helpers, layouts, and view les. webroot In a production setup, this folder should serve as the document root for your application. Folders here also serve as holding places for CSS stylesheets, images, and JavaScript les. CakePHP Structure CakePHP features Controller, Model, and View classes, but it also features some additional classes and objects that make development in MVC a little quicker and more enjoyable. Components, Behaviors, and Helpers are classes that provide extensibility and reusability to quickly add functionality to the base MVC classes in your applications. Right now well stay at a higher level, so look for the details on how to use these tools later on.
Application Extensions

Controllers, helpers and models each have a parent class you can use to dene applicationwide changes. AppController (located at /app/Controller/AppController.php), AppHelper (located at /app/View/Helper/AppHelper.php) and AppModel (located at /app/Model/AppModel.php) are great places to put methods you want to share between all controllers, helpers or models. Although they arent classes or les, routes play a role in requests made to CakePHP. Route denitions tell CakePHP how to map URLs to controller actions. The default behavior assumes that the URL /controller/action/var1/var2 maps to Controller::action($var1, $var2), but you can use routes to customize URLs and how they are interpreted by your application. Some features in an application merit packaging as a whole. A plugin is a package of models, controllers and views that accomplishes a specic purpose that can span multiple applications. A user management system or a simplied blog might be a good t for CakePHP plugins. Blog Tutorial - Adding a layer 25

CakePHP Cookbook Documentation, Release 2.x

Controller Extensions (Components)

A Component is a class that aids in controller logic. If you have some logic you want to share between controllers (or applications), a component is usually a good t. As an example, the core EmailComponent class makes creating and sending emails a snap. Rather than writing a controller method in a single controller that performs this logic, you can package the logic so it can be shared. Controllers are also tted with callbacks. These callbacks are available for your use, just in case you need to insert some logic between CakePHPs core operations. Callbacks available include: beforeFilter(), executed before any controller action logic beforeRender(), executed after controller logic, but before the view is rendered afterFilter(), executed after all controller logic, including the view render. There may be no difference between afterRender() and afterFilter() unless youve manually made a call to render() in your controller action and have included some logic after that call.
Model Extensions (Behaviors)

Similarly, Behaviors work as ways to add common functionality between models. For example, if you store user data in a tree structure, you can specify your User model as behaving like a tree, and gain free functionality for removing, adding, and shifting nodes in your underlying tree structure. Models also are supported by another class called a DataSource. DataSources are an abstraction that enable models to manipulate different types of data consistently. While the main source of data in a CakePHP application is often a database, you might write additional DataSources that allow your models to represent RSS feeds, CSV les, LDAP entries, or iCal events. DataSources allow you to associate records from different sources: rather than being limited to SQL joins, DataSources allow you to tell your LDAP model that it is associated to many iCal events. Just like controllers, models are featured with callbacks as well: beforeFind() afterFind() beforeValidate() beforeSave() afterSave() beforeDelete() afterDelete() The names of these methods should be descriptive enough to let you know what they do. You can nd the details in the models chapter.

Chapter 1. Getting Started

CakePHP Cookbook Documentation, Release 2.x

View Extensions (Helpers)

A Helper is a class that aids in view logic. Much like a component used among controllers, helpers allow presentational logic to be accessed and shared between views. One of the core helpers, JsHelper, makes Ajax requests within views much easier and comes with support for jQuery (default), Prototype and Mootools. Most applications have pieces of view code that are used repeatedly. CakePHP facilitates view code reuse with layouts and elements. By default, every view rendered by a controller is placed inside a layout. Elements are used when small snippets of content need to be reused in multiple views.

Blog Tutorial - Adding a layer

CakePHP Cookbook Documentation, Release 2.x

Chapter 1. Getting Started

CHAPTER 2

Installation

CakePHP is fast and easy to install. The minimum requirements are a webserver and a copy of Cake, thats it! While this manual focuses primarily on setting up with Apache (because its the most common), you can congure Cake to run on a variety of web servers such as LightHTTPD or Microsoft IIS.

Requirements
HTTP Server. For example: Apache. mod_rewrite is preferred, but by no means required. PHP 5.2.8 or greater. Technically a database engine isnt required, but we imagine that most applications will utilize one. CakePHP supports a variety of database storage engines: MySQL (4 or greater) PostgreSQL Microsoft SQL Server SQLite Note: The built-in drivers all require PDO. You should make sure you have the correct PDO extensions installed.

License
CakePHP is licensed under the MIT license. This means that you are free to modify, distribute and republish the source code on the condition that the copyright notices are left intact. You are also free to incorporate CakePHP into any Commercial or closed source application.

CakePHP Cookbook Documentation, Release 2.x

Downloading CakePHP
There are two main ways to get a fresh copy of CakePHP. You can either download an archive copy (zip/tar.gz/tar.bz2) from the main website, or check out the code from the git repository. To download the latest major release of CakePHP. Visit the main website http://cakephp.org and follow the Download Now link. All current releases of CakePHP are hosted on Github (http://github.com/cakephp/cakephp). Github houses both CakePHP itself as well as many other plugins for CakePHP. The CakePHP releases are available at Github tags (https://github.com/cakephp/cakephp/tags). Alternatively you can get fresh off the press code, with all the bug-xes and up to the minute enhancements. These can be accessed from github by cloning the Github (http://github.com/cakephp/cakephp) repository:
git clone git://github.com/cakephp/cakephp.git

Permissions
CakePHP uses the app/tmp directory for a number of different operations. Model descriptions, cached views, and session information are just a few examples. As such, make sure the directory app/tmp and all its subdirectories in your cake installation are writable by the web server user.

Setup
Setting up CakePHP can be as simple as slapping it in your web servers document root, or as complex and exible as you wish. This section will cover the three main installation types for CakePHP: development, production, and advanced. Development: easy to get going, URLs for the application include the CakePHP installation directory name, and less secure. Production: Requires the ability to congure the web servers document root, clean URLs, very secure. Advanced: With some conguration, allows you to place key CakePHP directories in different parts of the lesystem, possibly sharing a single CakePHP core library folder amongst many CakePHP applications.

Development
A development installation is the fastest method to setup Cake. This example will help you install a CakePHP application and make it available at http://www.example.com/cake_2_0/. We assume for the purposes of this example that your document root is set to /var/www/html.

Chapter 2. Installation

CakePHP Cookbook Documentation, Release 2.x

Unpack the contents of the Cake archive into /var/www/html. You now have a folder in your document root named after the release youve downloaded (e.g. cake_2.0.0). Rename this folder to cake_2_0. Your development setup will look like this on the le system:
/var/www/html/ cake_2_0/ app/ lib/ plugins/ vendors/ .htaccess index.php README

If your web server is congured correctly, you should now nd your Cake application accessible at http://www.example.com/cake_2_0/.

Using one CakePHP checkout for multiple applications

If you are developing a number of applications, it often makes sense to have them share the same CakePHP core checkout. There are a few ways in which you can accomplish this. Often the easiest is to use PHPs include_path. To start off, clone CakePHP into a directory. For this example, well use /home/mark/projects:
git clone git://github.com/cakephp/cakephp.git /home/mark/projects/cakephp

This will clone CakePHP into your /home/mark/projects directory. If you dont want to use git, you can download a zipball and the remaining steps will be the same. Next youll have to locate and modify your php.ini. On *nix systems this is often in /etc/php.ini, but using php -i and looking for Loaded Conguration File. Once youve found the correct ini le, modify the include_path conguration to include /home/mark/projects/cakephp/lib. An example would look like:
include_path = .:/home/mark/projects/cakephp/lib:/usr/local/php/lib/php

After restarting your webserver, you should see the changes reected in phpinfo(). Note: If you are on windows, separate include paths with ; instead of : Having nished setting up your include_path your applications should be able to nd CakePHP automatically.

Production
A production installation is a more exible way to setup Cake. Using this method allows an entire domain to act as a single CakePHP application. This example will help you install Cake anywhere on your lesystem and make it available at http://www.example.com. Note that this installation may require the rights to change the DocumentRoot on Apache webservers.

Production

CakePHP Cookbook Documentation, Release 2.x

Unpack the contents of the Cake archive into a directory of your choosing. For the purposes of this example, we assume you choose to install Cake into /cake_install. Your production setup will look like this on the lesystem:
/cake_install/ app/ webroot/ (this directory is set as the DocumentRoot directive) lib/ plugins/ vendors/ .htaccess index.php README

Developers using Apache should set the DocumentRoot directive for the domain to:
DocumentRoot /cake_install/app/webroot

Advanced Installation and URL Rewriting

Advanced Installation
Installing CakePHP with PEAR installer CakePHP publishes a PEAR package that you can install using the pear installer. Installing with the pear installer can simplify sharing CakePHP libraries across multiple applications. To install CakePHP with pear youll need to do the following:
pear channel-discover pear.cakephp.org pear install cakephp/CakePHP

Note: On some systems installing libraries with pear will require sudo. After installing CakePHP with pear, if pear is congured correctly you should be able to use the cake command to create a new application. Since CakePHP will be located on PHPs include_path you wont need to make any other changes. Installing CakePHP with composer Composer is a dependency management tool for PHP 5.3+. It solves many of the problems the PEAR installer has, and simplies managing multiple versions of libraries. Since CakePHP publishes a PEAR package you can install CakePHP using composer (http://getcomposer.org). Before installing CakePHP youll need to setup a composer.json le. A composer.json le for a CakePHP applications would look like the following: 32 Chapter 2. Installation

CakePHP Cookbook Documentation, Release 2.x

{ "name": "example-app", "repositories": [ { "type": "pear", "url": "http://pear.cakephp.org" } ], "require": { "pear-cakephp/cakephp": ">=2.4.0" }, "config": { "vendor-dir": "Vendor/" } }

Save this JSON into composer.json in the root directory of your project. Next download the composer.phar le into your project. After youve downloaded composer, install CakePHP. In the same directory as your composer.json run the following:
$ php composer.phar install

Once composer has nished running you should have a directory structure that looks like:
example-app/ composer.phar composer.json Vendor/ bin/ autoload.php composer/ pear-pear.cakephp.org/

You are now ready to generate the rest of your application skeleton:
$ Vendor/bin/cake bake project <path to project>

By default bake will hard-code CAKE_CORE_INCLUDE_PATH. To make your application more portable you should modify webroot/index.php, changing CAKE_CORE_INCLUDE_PATH to be a relative path:
define( CAKE_CORE_INCLUDE_PATH, ROOT . DS . APP_DIR . /Vendor/pear-pear.cakephp.org/CakePHP );

If youre installing any other libraries with composer, youll need to setup the autoloader, and work around an issue in composers autoloader. In your Config/bootstrap.php le add the following:
// Load composer autoload. require APP . /Vendor/autoload.php; // Remove and re-prepend CakePHPs autoloader as composer thinks it is the most important.

Advanced Installation and URL Rewriting

CakePHP Cookbook Documentation, Release 2.x

// See https://github.com/composer/composer/commit/c80cb76b9b5082ecc3e5b53b1050f76bb27b127b spl_autoload_unregister(array(App, load)); spl_autoload_register(array(App, load), true, true);

You should now have a functioning CakePHP application with CakePHP installed via composer. Be sure to keep the composer.json and composer.lock le with the rest of your source code. Sharing CakePHP libraries with multiple applications There may be some situations where you wish to place CakePHPs directories on different places on the lesystem. This may be due to a shared host restriction, or maybe you just want a few of your apps to share the same Cake libraries. This section describes how to spread your CakePHP directories across a lesystem. First, realize that there are three main parts to a Cake application: 1. The core CakePHP libraries, in /lib/Cake. 2. Your application code, in /app. 3. The applications webroot, usually in /app/webroot. Each of these directories can be located anywhere on your le system, with the exception of the webroot, which needs to be accessible by your web server. You can even move the webroot folder out of the app folder as long as you tell Cake where youve put it. To congure your Cake installation, youll need to make some changes to the following les. /app/webroot/index.php /app/webroot/test.php (if you use the Testing feature.) There are three constants that youll need to edit: ROOT, APP_DIR, and CAKE_CORE_INCLUDE_PATH. ROOT should be set to the path of the directory that contains your app folder. APP_DIR should be set to the (base)name of your app folder. CAKE_CORE_INCLUDE_PATH should be set to the path of your CakePHP libraries folder. Lets run through an example so you can see what an advanced installation might look like in practice. Imagine that I wanted to set up CakePHP to work as follows: The CakePHP core libraries will be placed in /usr/lib/cake. My applications webroot directory will be /var/www/mysite/. My applications app directory will be /home/me/myapp. Given this type of setup, I would need to edit my webroot/index.php le (which will end up at /var/www/mysite/index.php, in this example) to look like the following:
// /app/webroot/index.php (partial, comments removed) if (!defined(ROOT)) { define(ROOT, DS . home . DS . me); }

Chapter 2. Installation

CakePHP Cookbook Documentation, Release 2.x

if (!defined(APP_DIR)) { define (APP_DIR, myapp); } if (!defined(CAKE_CORE_INCLUDE_PATH)) { define(CAKE_CORE_INCLUDE_PATH, DS . usr . DS . lib); }

It is recommended to use the DS constant rather than slashes to delimit le paths. This prevents any missing le errors you might get as a result of using the wrong delimiter, and it makes your code more portable. Apache and mod_rewrite (and .htaccess) This section was moved to URL rewriting.

URL Rewriting
Apache and mod_rewrite (and .htaccess) While CakePHP is built to work with mod_rewrite out of the boxand usually doesweve noticed that a few users struggle with getting everything to play nicely on their systems. Here are a few things you might try to get it running correctly. First look at your httpd.conf (Make sure you are editing the system httpd.conf rather than a user- or site-specic httpd.conf). 1. Make sure that an .htaccess override is allowed and that AllowOverride is set to All for the correct DocumentRoot. You should see something similar to:
# Each directory to which Apache has access can be configured with respect # to which services and features are allowed and/or disabled in that # directory (and its subdirectories). # # First, we configure the "default" to be a very restrictive set of # features. # <Directory /> Options FollowSymLinks AllowOverride All # Order deny,allow # Deny from all </Directory>

2. Make sure you are loading up mod_rewrite correctly. You should see something like:
LoadModule rewrite_module libexec/apache2/mod_rewrite.so

Advanced Installation and URL Rewriting

CakePHP Cookbook Documentation, Release 2.x

Verify that you your .htaccess les are actually in the right directories. This can happen during copying because some operating systems treat les that start with . as hidden and therefore wont see them to copy. 3. Make sure your copy of CakePHP is from the downloads section of the site or our GIT repository, and has been unpacked correctly by checking for .htaccess les. Cake root directory (needs to be copied to your document, this redirects everything to your Cake app):
<IfModule mod_rewrite.c> RewriteEngine on RewriteRule ^ $ app/webroot/ RewriteRule </IfModule>

[L]

(.*) app/webroot/ $ 1 [L]

Cake app directory (will be copied to the top directory of your application by bake):
<IfModule mod_rewrite.c> RewriteEngine on RewriteRule ^$ webroot/ RewriteRule </IfModule> (.*) webroot/ $ 1

[L] [L]

If your CakePHP site still has problems with mod_rewrite you might want to try and modify settings for virtualhosts. If on ubuntu, edit the le /etc/apache2/sites-available/default (location is distribution dependent). In this le, ensure that AllowOverride None is changed to AllowOverride All, so you have:
<Directory /> Options FollowSymLinks AllowOverride All </Directory> <Directory /var/www> Options Indexes FollowSymLinks MultiViews AllowOverride All Order Allow,Deny Allow from all </Directory>

CakePHP Cookbook Documentation, Release 2.x

mod_rewrite, youll need to add RewriteBase statements to the .htaccess les CakePHP uses (/.htaccess, /app/.htaccess, /app/webroot/.htaccess). This can be added to the same section with the RewriteEngine directive, so for example your webroot .htaccess le would look like:
<IfModule mod_rewrite.c> RewriteEngine On RewriteBase /path/to/cake/app RewriteCond %{REQUEST_FILENAME} !-d RewriteCond %{REQUEST_FILENAME} !-f RewriteRule ^(.*) $ index.php [QSA,L] </IfModule>

Pretty URLs on nginx nginx is a popular server that uses less system resources than Apache. Its drawback is that it does not make use of .htaccess les like Apache, so it is necessary to create those rewritten URLs in the site-available conguration. Depending upon your setup, you will have to modify this, but at the very least, you will need PHP running as a FastCGI instance.
server { listen 80; server_name www.example.com; rewrite ^(.*) http://example.com $ 1 permanent; } server { listen 80; server_name example.com;

Advanced Installation and URL Rewriting

CakePHP Cookbook Documentation, Release 2.x

# root directive should be global root /var/www/example.com/public/app/webroot/; index index.php; access_log /var/www/example.com/log/access.log; error_log /var/www/example.com/log/error.log; location / { try_files $uri $uri/ /index.php?$uri&$args; } location ~ \.php $ { try_files $uri =404; include /etc/nginx/fastcgi_params; fastcgi_pass 127.0.0.1:9000; fastcgi_index index.php; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; } }

URL Rewrites on IIS7 (Windows hosts) IIS7 does not natively support .htaccess les. While there are add-ons that can add this support, you can also import htaccess rules into IIS to use CakePHPs native rewrites. To do this, follow these steps: 1. Use Microsofts Web Platform Installer (http://www.microsoft.com/web/downloads/platform.aspx) to install the URL Rewrite Module 2.0 (http://www.iis.net/downloads/microsoft/url-rewrite) or download it directly (32-bit (http://www.microsoft.com/en-us/download/details.aspx?id=5747) / 64-bit (http://www.microsoft.com/en-us/download/details.aspx?id=7435)). 2. Create a new le in your CakePHP root folder, called web.cong. 3. Using Notepad or any XML-safe editor and copy the following code into your new web.cong le...

Chapter 2. Installation

CakePHP Cookbook Documentation, Release 2.x

Once the web.cong le is created with the correct IIS-friendly rewrite rules, CakePHPs links, css, js, and rerouting should work correctly. I dont / cant use URL rewriting If you dont want to or cant use URL rewriting on your webserver, refer to the core conguration.

Fire It Up
Alright, lets see CakePHP in action. Depending on which setup you used, you should point your browser to http://example.com/ or http://example.com/cake_install/. At this point, youll be presented with CakePHPs default home, and a message that tells you the status of your current database connection. Congratulations! You are ready to create your rst CakePHP application. Not working? If youre getting timezone related error from PHP uncomment one line in app/Config/core.php:
/** * Uncomment this line and correct your server timezone to fix * any date & time related errors. */ date_default_timezone_set(UTC);

Fire It Up

CakePHP Cookbook Documentation, Release 2.x

Chapter 2. Installation

CHAPTER 3

CakePHP Overview

Welcome to the Cookbook, the manual for the CakePHP web application framework that makes developing a piece of cake! This manual assumes that you have a general understanding of PHP and a basic understanding of objectoriented programming (OOP). Different functionality within the framework makes use of different technologies such as SQL, JavaScript, and XML and this manual does not attempt to explain those technologies, only how they are used in context.

What is CakePHP? Why Use it?

CakePHP (http://www.cakephp.org/) is a free (http://en.wikipedia.org/wiki/MIT_License), open-source (http://en.wikipedia.org/wiki/Open_source), rapid development (http://en.wikipedia.org/wiki/Rapid_application_development) framework (http://en.wikipedia.org/wiki/Application_framework) for PHP (http://www.php.net/). Its a foundational structure for programmers to create web applications. Our primary goal is to enable you to work in a structured and rapid mannerwithout loss of exibility. CakePHP takes the monotony out of web development. We provide you with all the tools you need to get started coding what you really need to get done: the logic specic to your application. Instead of reinventing the wheel every time you sit down to a new project, check out a copy of CakePHP and get started with the real guts of your application. CakePHP has an active developer team (https://github.com/cakephp?tab=members) and community, bringing great value to the project. In addition to keeping you from wheel-reinventing, using CakePHP means your applications core is well tested and is being constantly improved. Heres a quick list of features youll enjoy when using CakePHP: Active, friendly community (http://cakephp.org/feeds) Flexible licensing (http://en.wikipedia.org/wiki/MIT_License) Compatible with versions PHP 5.2.8 and greater.

CakePHP Cookbook Documentation, Release 2.x

Integrated CRUD (http://en.wikipedia.org/wiki/Create,_read,_update_and_delete) for database interaction. Application scaffolding (http://en.wikipedia.org/wiki/Scaffold_(programming)). Code generation. MVC (http://en.wikipedia.org/wiki/Model-view-controller) architecture. Request dispatcher with clean, custom URLs and routes. Built-in validation (http://en.wikipedia.org/wiki/Data_validation). Fast and exible templating (http://en.wikipedia.org/wiki/Web_template_system) (PHP syntax, with helpers). View Helpers for AJAX, JavaScript, HTML Forms and more. Email, Cookie, Security, Session, and Request Handling Components. Flexible ACL (http://en.wikipedia.org/wiki/Access_control_list). Data Sanitization. Flexible Caching (http://en.wikipedia.org/wiki/Web_cache). Localization. Works from any web site directory, with little to no Apache (http://httpd.apache.org/) conguration involved.

Understanding Model-View-Controller
CakePHP follows the MVC (http://en.wikipedia.org/wiki/Model-view-controller) software design pattern. Programming using MVC separates your application into three main parts:

The Model layer

The Model layer represents the part of your application that implements the business logic. It is responsible for retrieving data and converting it into meaningful concepts for your application. This includes processing, validating, associating or other tasks related to handling data. At a rst glance, Model objects can be looked at as the rst layer of interaction with any database you might be using for your application. But in general they stand for the major concepts around which you implement your application. In the case of a social network, the Model layer would take care of tasks such as Saving the user data, saving friends associations, storing and retrieving user photos, nding new friends for suggestions, etc. While the model objects can be thought as Friend, User, Comment, or Photo.

Chapter 3. CakePHP Overview

CakePHP Cookbook Documentation, Release 2.x

The View layer

The View renders a presentation of modeled data. Being separated from the Model objects, it is responsible for using the information it has available to produce any presentational interface your application might need. For example, as the Model layer returns a set of data, the view would use it to render a HTML page containing it. Or a XML formatted result for others to consume. The View layer is not only limited to HTML or text representation of the data, it can be used to deliver a wide variety of formats depending on your needs, such as videos, music, documents and any other format you can think of.

The Controller layer

The Controller layer handles requests from users. Its responsible for rendering back a response with the aid of both the Model and the View Layer. Controllers can be seen as managers taking care that all needed resources for completing a task are delegated to the correct workers. It waits for petitions from clients, checks their validity according to authentication or authorization rules, delegates data fetching or processing to the model, and selects the correct type of presentational data that the client is accepting, to nally delegate this rendering process to the View layer.

CakePHP request cycle

Figure: 1: A typical MVC Request in CakePHP The typical CakePHP request cycle starts with a user requesting a page or resource in your application. This request is rst processed by a dispatcher which will select the correct controller object to handle it. Once the request arrives at the controller, it will communicate with the Model layer to process any data fetching or saving operation that might be needed. After this communication is over, the controller will

Understanding Model-View-Controller

CakePHP Cookbook Documentation, Release 2.x

proceed at delegating to the correct view object the task of generating an output resulting from the data provided by the model. Finally, when this output is generated, it is immediately rendered to the user Almost every request to your application will follow this basic pattern. Well add some details later on which are specic to CakePHP, so keep this in mind as we proceed.

Benets
Why use MVC? Because it is a tried and true software design pattern that turns an application into a maintainable, modular, rapidly developed package. Crafting application tasks into separate models, views, and controllers makes your application very light on its feet. New features are easily added, and new faces on old features are a snap. The modular and separate design also allows developers and designers to work simultaneously, including the ability to rapidly prototype (http://en.wikipedia.org/wiki/Software_prototyping). Separation also allows developers to make changes in one part of the application without affecting the others. If youve never built an application this way, it takes some time getting used to, but were condent that once youve built your rst application using CakePHP, you wont want to do it any other way. To get started on your rst CakePHP application, try the blog tutorial now

Where to Get Help

The Ofcial CakePHP website
http://www.cakephp.org The Ofcial CakePHP website is always a great place to visit. It features links to oft-used developer tools, screencasts, donation opportunities, and downloads.

The Cookbook
http://book.cakephp.org This manual should probably be the rst place you go to get answers. As with many other open source projects, we get new folks regularly. Try your best to answer your questions on your own rst. Answers may come slower, but will remain longer and youll also be lightening our support load. Both the manual and the API have an online component.

The Bakery
http://bakery.cakephp.org The CakePHP Bakery is a clearing house for all things CakePHP. Check it out for tutorials, case studies, and code examples. Once youre acquainted with CakePHP, log on and share your knowledge with the community and gain instant fame and fortune. 44 Chapter 3. CakePHP Overview

CakePHP Cookbook Documentation, Release 2.x

The API
http://api20.cakephp.org/ Straight to the point and straight from the core developers, the CakePHP API (Application Programming Interface) is the most comprehensive documentation around for all the nitty gritty details of the internal workings of the framework. Its a straight forward code reference, so bring your propeller hat.

The Test Cases

If you ever feel the information provided in the API is not sufcient, check out the code of the test cases provided with CakePHP. They can serve as practical examples for function and data member usage for a class.:
lib/Cake/Test/Case

The IRC channel

IRC Channels on irc.freenode.net: #cakephp General Discussion #cakephp-docs Documentation #cakephp-bakery Bakery If youre stumped, give us a holler in the CakePHP IRC channel. Someone from the development team (https://github.com/cakephp?tab=members) is usually there, especially during the daylight hours for North and South America users. Wed love to hear from you, whether you need some help, want to nd users in your area, or would like to donate your brand new sports car.

The Google Group

http://groups.google.com/group/cake-php CakePHP also has a very active Google Group. It can be a great resource for nding archived answers, frequently asked questions, and getting answers to immediate problems.

CakePHP Questions
http://ask.cakephp.org/ Simply register/login and ask a question. Wait until youve got some answers and pick the correct answer. You can view, comment and vote on previously asked and solved questions as well.

Where to Get Help

CakePHP Cookbook Documentation, Release 2.x

Chapter 3. CakePHP Overview

CHAPTER 4

Controllers

Controllers are the C in MVC. After routing has been applied and the correct controller has been found, your controllers action is called. Your controller should handle interpreting the request data, making sure the correct models are called, and the right response or view is rendered. Controllers can be thought of as middle man between the Model and View. You want to keep your controllers thin, and your models fat. This will help you more easily reuse your code and makes your code easier to test. Commonly, controllers are used to manage the logic around a single model. For example, if you were building a site for an on-line bakery, you might have a RecipesController and an IngredientsController managing your recipes and their ingredients. In CakePHP, controllers are named after the primary model they handle. Its totally possible to have controllers work with more than one model as well. Your applications controllers extend AppController class, which in turn extends the core Controller class. The AppController class can be dened in /app/Controller/AppController.php and it should contain methods that are shared between all of your applications controllers. Controllers provide a number of methods which are called actions. Actions are methods on a controller that handle requests. By default all public methods on a controller are an action, and accessible from a url. Actions are responsible for interpreting the request and creating the response. Usually responses are in the form of a rendered view, but there are other ways to create responses as well.

The App Controller

As stated in the introduction, the AppController class is the parent class to all of your applications controllers. AppController itself extends the Controller class included in the CakePHP core library. As such, AppController is dened in /app/Controller/AppController.php like so:
class AppController extends Controller { }

Controller attributes and methods created in your AppController will be available to all of your applications controllers. It is the ideal place to create code that is common to all of your controllers. Components (which youll learn about later) are best used for code that is used in many (but not necessarily all) controllers. 47

CakePHP Cookbook Documentation, Release 2.x

While normal object-oriented inheritance rules apply, CakePHP does a bit of extra work when it comes to special controller attributes. The list of components and helpers used by a controller are treated specially. In these cases, AppController value arrays are merged with child controller class arrays. The values in the child class will always override those in AppController. Note: CakePHP merges the following variables from the AppController to your applications controllers: $components $helpers $uses Remember to add the default Html and Form helpers, if you dene var $helpers in your AppController Please also remember to call AppControllers callbacks within child controller callbacks for best results:
public function beforeFilter() { parent::beforeFilter(); }

Request parameters
When a request is made to a CakePHP application, CakePHPs Router and Dispatcher classes use Routes Conguration to nd and create the correct controller. The request data is encapsulated into a request object. CakePHP puts all of the important request information into the $this->request property. See the section on CakeRequest for more information on the CakePHP request object.

Controller actions
Controller actions are responsible for converting the request parameters into a response for the browser/user making the request. CakePHP uses conventions to automate this process and remove some boiler-plate code you would otherwise need to write. By convention CakePHP renders a view with an inected version of the action name. Returning to our online bakery example, our RecipesController might contain the view(), share(), and search() actions. The controller would be found in /app/Controller/RecipesController.php and contain:
# /app/Controller/RecipesController.php class RecipesController extends AppController { public function view($id) { //action logic goes here.. } public function share($customerId, $recipeId) { //action logic goes here.. }

Chapter 4. Controllers

CakePHP Cookbook Documentation, Release 2.x

public function search($query) { //action logic goes here.. } }

The view les for these actions would be app/View/Recipes/view.ctp, app/View/Recipes/share.ctp, and app/View/Recipes/search.ctp. The conventional view le name is the lower cased and underscored version of the action name. Controller actions generally use set() to create a context that View uses to render the view. Because of the conventions that CakePHP uses, you dont need to create and render the view manually. Instead once a controller action has completed, CakePHP will handle rendering and delivering the View. If for some reason youd like to skip the default behavior. Both of the following techniques will by-pass the default view rendering behavior. If you return a string, or an object that can be converted to a string from your controller action, it will be used as the response body. You can return a CakeResponse object with the completely created response. When controller methods are used with requestAction() you will often want to return data that isnt a string. If you have controller methods that are used for normal web requests + requestAction you should check the request type before returning:
class RecipesController extends AppController { public function popular() { $popular = $this->Recipe->popular(); if (!empty($this->request->params[requested])) { return $popular; } $this->set(popular, $popular); } }

The above controller action is an example of how a method can be used with requestAction() and normal requests. Returning an array data to a non-requestAction request will cause errors and should be avoided. See the section on Controller::requestAction() for more tips on using requestAction() In order for you to use a controller effectively in your own application, well cover some of the core attributes and methods provided by CakePHPs controllers.

Request Life-cycle callbacks

class Controller CakePHP controllers come tted with callbacks you can use to insert logic around the request life-cycle: Controller::beforeFilter() This function is executed before every action in the controller. Its a handy place to check for an active session or inspect user permissions. Request Life-cycle callbacks 49

CakePHP Cookbook Documentation, Release 2.x

Note: The beforeFilter() method will be called for missing actions, and scaffolded actions. Controller::beforeRender() Called after controller action logic, but before the view is rendered. This callback is not used often, but may be needed if you are calling render() manually before the end of a given action. Controller::afterFilter() Called after every controller action, and after rendering is complete. This is the last controller method to run. In addition to controller life-cycle callbacks, Components also provide a similar set of callbacks.

Controller Methods
For a complete list of controller methods and their descriptions visit the CakePHP API. Check out http://api20.cakephp.org/class/controller.

Interacting with Views

Controllers interact with the view in a number of ways. First they are able to pass data to the views, using set(). You can also decide which view class to use, and which view le should be rendered from the controller. Controller::set(string $var, mixed $value) The set() method is the main way to send data from your controller to your view. Once youve used set(), the variable can be accessed in your view:
// First you pass data from the controller: $this->set(color, pink); // Then, in the view, you can utilize the data: ?> You have selected <?php echo $color; ?> icing for the cake.

The set() method also takes an associative array as its rst parameter. This can often be a quick way to assign a set of information to the view. Changed in version 1.3: Array keys will no longer be inected before they are assigned to the view (underscored_key does not become underscoredKey anymore, etc.):
$data = array( color => pink, type => sugar, base_price => 23.95 ); // make $color, $type, and $base_price

Chapter 4. Controllers

CakePHP Cookbook Documentation, Release 2.x

// available to the view: $this->set($data);

The attribute $pageTitle no longer exists, use set() to set the title:
$this->set(title_for_layout, This is the page title);

Controller::render(string $view, string $layout) The render() method is automatically called at the end of each requested controller action. This method performs all the view logic (using the data youve given in using the set() method), places the view inside its layout and serves it back to the end user. The default view le used by render is determined by convention. If the search() action of the RecipesController is requested, the view le in /app/View/Recipes/search.ctp will be rendered:
class RecipesController extends AppController { // ... public function search() { // Render the view in /View/Recipes/search.ctp $this->render(); } // ... }

Although CakePHP will automatically call it (unless youve set $this->autoRender to false) after every actions logic, you can use it to specify an alternate view le by specifying an action name in the controller using $action. If $view starts with / it is assumed to be a view or element le relative to the /app/View folder. This allows direct rendering of elements, very useful in ajax calls.
// Render the element in /View/Elements/ajaxreturn.ctp $this->render(/Elements/ajaxreturn);

The $layout parameter allows you to specify the layout the view is rendered in. Rendering a specic view In your controller you may want to render a different view than what would conventionally be done. You can do this by calling render() directly. Once you have called render() CakePHP will not try to re-render the view:
class PostsController extends AppController { public function my_action() { $this->render(custom_file); } }

This would render app/View/Posts/custom_file.ctp app/View/Posts/my_action.ctp

instead

Controller Methods

CakePHP Cookbook Documentation, Release 2.x

You can also render views inside plugins using the following syntax: $this->render(PluginName.PluginController/custom_file). For example:
class PostsController extends AppController { public function my_action() { $this->render(Users.UserDetails/custom_file); } }

This would render app/Plugin/Users/View/UserDetails/custom_file.ctp

Flow Control
Controller::redirect(mixed $url, integer $status, boolean $exit) The ow control method youll use most often is redirect(). This method takes its rst parameter in the form of a CakePHP-relative URL. When a user has successfully placed an order, you might wish to redirect them to a receipt screen.:

public function place_order() { // Logic for finalizing order goes here if ($success) { return $this->redirect(array(controller => orders, action => thanks)); } return $this->redirect(array(controller => orders, action => confirm)); }

You can also use a relative or absolute URL as the $url argument:
$this->redirect(/orders/thanks)); $this->redirect(http://www.example.com);

You can also pass data to the action:

$this->redirect(array(action => edit, $id));

The second parameter of redirect() allows you to dene an HTTP status code to accompany the redirect. You may want to use 301 (moved permanently) or 303 (see other), depending on the nature of the redirect. The method will issue an exit() after the redirect unless you set the third parameter to false. If you need to redirect to the referer page you can use:
$this->redirect($this->referer());

The method also supports name based parameters. If you want to redirect to a URL like: http://www.example.com/orders/confirm/product:pizza/quantity:5 you can use:

$this->redirect(array(controller => orders, action => confirm, product => p

An example using query strings and hash would look like:

Chapter 4. Controllers

CakePHP Cookbook Documentation, Release 2.x

$this->redirect(array( controller => orders, action => confirm, ? => array(product => pizza

The generated url would be: http://www.example.com/orders/confirm?product=pizza&quantity Controller::flash(string $message, string|array $url, integer $pause, string $layout) Like redirect(), the flash() method is used to direct a user to a new page after an operation. The flash() method is different in that it shows a message before passing the user on to another URL. The rst parameter should hold the message to be displayed, and the second parameter is a CakePHPrelative URL. CakePHP will display the $message for $pause seconds before forwarding the user on. If theres a particular template youd like your ashed message to use, you may specify the name of that layout in the $layout parameter. For in-page ash messages, be sure to check out SessionComponents setFlash() method.

Callbacks
In addition to the Request Life-cycle callbacks. CakePHP also supports callbacks related to scaffolding. Controller::beforeScaffold($method) $method name of method called example index, edit, etc. Controller::afterScaffoldSave($method) $method name of method called either edit or update. Controller::afterScaffoldSaveError($method) $method name of method called either edit or update. Controller::scaffoldError($method) $method name of method called example index, edit, etc.

Other Useful Methods

Controller::constructClasses() This method loads the models required by the controller. This loading process is done by CakePHP normally, but this method is handy to have when accessing controllers from a different perspective. If you need CakePHP in a command-line script or some other outside use, constructClasses() may come in handy. Controller::referer(mixed $default = null, boolean $local = false) Returns the referring URL for the current request. Parameter $default can be used to supply a default URL to use if HTTP_REFERER cannot be read from headers. So, instead of doing this:
class UserController extends AppController { public function delete($id) { // delete code goes here, and then... if ($this->referer() != /) {

Controller Methods

CakePHP Cookbook Documentation, Release 2.x

return $this->redirect($this->referer()); } return $this->redirect(array(action => index)); } }

you can do this:

class UserController extends AppController { public function delete($id) { // delete code goes here, and then... return $this->redirect($this->referer(array(action => index))); } }

If $default is not set, the function defaults to the root of your domain - /. Parameter $local if set to true, restricts referring URLs to local server. Controller::disableCache() Used to tell the users browser not to cache the results of the current request. This is different than view caching, covered in a later chapter. The headers sent to this effect are:
Expires: Mon, 26 Jul 1997 05:00:00 GMT Last-Modified: [current datetime] GMT Cache-Control: no-store, no-cache, must-revalidate Cache-Control: post-check=0, pre-check=0 Pragma: no-cache

Controller::postConditions(array $data, mixed $op, string $bool, boolean $exclusive) Use this method to turn a set of POSTed model data (from HtmlHelper-compatible inputs) into a set of nd conditions for a model. This function offers a quick shortcut on building search logic. For example, an administrative user may want to be able to search orders in order to know which items need to be shipped. You can use CakePHPs FormHelper and HtmlHelper to create a quick form based on the Order model. Then a controller action can use the data posted from that form to craft nd conditions:
public function index() { $conditions = $this->postConditions($this->request->data); $orders = $this->Order->find(all, compact(conditions)); $this->set(orders, $orders); }

If $this->request->data[Order][destination] equals Old Towne Bakery, postConditions converts that condition to an array compatible for use in a Model->nd() method. In this case, array(Order.destination => Old Towne Bakery). If you want to use a different SQL operator between terms, supply them using the second parameter:
/* Contents of $this->request->data array(

Chapter 4. Controllers

CakePHP Cookbook Documentation, Release 2.x

Order => array( num_items => 4, referrer => Ye Olde ) ) */ // Lets get orders that have at least 4 items and contain Ye Olde $conditions = $this->postConditions( $this->request->data, array( num_items => >=, referrer => LIKE ) ); $orders = $this->Order->find(all, compact(conditions));

The third parameter allows you to tell CakePHP what SQL boolean operator to use between the nd conditions. Strings like AND, OR and XOR are all valid values. Finally, if the last parameter is set to true, and the $op parameter is an array, elds not included in $op will not be included in the returned conditions. Controller::paginate() This method is used for paginating results fetched by your models. You can specify page sizes, model nd conditions and more. See the pagination section for more details on how to use paginate. Controller::requestAction(string $url, array $options) This function calls a controllers action from any location and returns data from the action. The $url passed is a CakePHP-relative URL (/controllername/actionname/params). To pass extra data to the receiving controller action add to the $options array. Note: You can use requestAction() to retrieve a fully rendered view by passing return in the options: requestAction($url, array(return));. It is important to note that making a requestAction using return from a controller method can cause script and css tags to not work correctly. Warning: If used without caching requestAction can lead to poor performance. It is rarely appropriate to use in a controller or model. requestAction is best used in conjunction with (cached) elements as a way to fetch data for an element before rendering. Lets use the example of putting a latest comments element in the layout. First we need to create a controller function that will return the data:

// Controller/CommentsController.php class CommentsController extends AppController { public function latest() { if (empty($this->request->params[requested])) { throw new ForbiddenException(); } return $this->Comment->find(all, array(order => Comment.created DESC, l

Controller Methods

CakePHP Cookbook Documentation, Release 2.x

} }

You should always include checks to make sure your requestAction methods are actually originating from requestAction. Failing to do so will allow requestAction methods to be directly accessible from a URL, which is generally undesirable. If we now create a simple element to call that function:
// View/Elements/latest_comments.ctp $comments = $this->requestAction(/comments/latest); foreach ($comments as $comment) { echo $comment[Comment][title]; }

We can then place that element anywhere to get the output using:
echo $this->element(latest_comments);

Written in this way, whenever the element is rendered, a request will be made to the controller to get the data, the data will be processed, and returned. However in accordance with the warning above its best to make use of element caching to prevent needless processing. By modifying the call to element to look like this:
echo $this->element(latest_comments, array(), array(cache => true));

The requestAction call will not be made while the cached element view le exists and is valid. In addition, requestAction now takes array based cake style urls:
echo $this->requestAction( array(controller => articles, action => featured), array(return) );

This allows the requestAction call to bypass the usage of Router::url which can increase performance. The url based arrays are the same as the ones that HtmlHelper::link() uses with one difference - if you are using named or passed parameters, you must put them in a second array and wrap them with the correct key. This is because requestAction merges the named args array (requestActions 2nd parameter) with the Controller::params member array and does not explicitly place the named args array into the key named; Additional members in the $option array will also be made available in the requested actions Controller::params array:
echo $this->requestAction(/articles/featured/limit:3); echo $this->requestAction(/articles/view/5);

As an array in the requestAction would then be:

echo $this->requestAction( array(controller => articles, action => featured), array(named => array(limit => 3)) );

Chapter 4. Controllers

CakePHP Cookbook Documentation, Release 2.x

echo $this->requestAction( array(controller => articles, action => view), array(pass => array(5)) );

Note: Unlike other places where array urls are analogous to string urls, requestAction treats them differently. When using an array url in conjunction with requestAction() you must specify all parameters that you will need in the requested action. This includes parameters like $this->request->data. In addition to passing all required parameters, named and pass parameters must be done in the second array as seen above. Controller::loadModel(string $modelClass, mixed $id) The loadModel function comes handy when you need to use a model which is not the controllers default model or its associated model:

$this->loadModel(Article); $recentArticles = $this->Article->find(all, array(limit => 5, order => Article. $this->loadModel(User, 2); $user = $this->User->read();

Controller Attributes
For a complete list of controller attributes and their descriptions visit the CakePHP API. Check out http://api20.cakephp.org/class/controller. property Controller::$name The $name attribute should be set to the name of the controller. Usually this is just the plural form of the primary model the controller uses. This property can be omitted, but saves CakePHP from inecting it:
// $name controller attribute usage example class RecipesController extends AppController { public $name = Recipes; }

$components, $helpers and $uses

The next most often used controller attributes tell CakePHP what helpers, components, and models youll be using in conjunction with the current controller. Using these attributes make MVC classes given by $components and $uses available to the controller as class variables ($this->ModelName, for example) and those given by $helpers to the view as an object reference variable ($this->{$helpername}).

Controller Attributes

CakePHP Cookbook Documentation, Release 2.x

Note: Each controller has some of these classes available by default, so you may not need to congure your controller at all. property Controller::$uses Controllers have access to their primary model available by default. Our RecipesController will have the Recipe model class available at $this->Recipe, and our ProductsController also features the Product model at $this->Product. However, when allowing a controller to access additional models through the $uses variable, the name of the current controllers model must also be included. This is illustrated in the example below. If you do not wish to use a Model in your controller, set public $uses = array(). This will allow you to use a controller without a need for a corresponding Model le. However, the models dened in the AppController will still be loaded. You can also use false to not load any models at all. Even those dened in the AppController. Changed in version 2.1: Uses now has a new default value, it also handles false differently. property Controller::$helpers The Html, Form, and Session Helpers are available by default, as is the SessionComponent. But if you choose to dene your own $helpers array in AppController, make sure to include Html and Form if you want them still available by default in your Controllers. To learn more about these classes, be sure to check out their respective sections later in this manual. Lets look at how to tell a CakePHP controller that you plan to use additional MVC classes:
class RecipesController extends AppController { public $uses = array(Recipe, User); public $helpers = array(Js); public $components = array(RequestHandler); }

Each of these variables are merged with their inherited values, therefore it is not necessary (for example) to redeclare the Form helper, or anything that is declared in your App controller. property Controller::$components The components array allows you to set which Components a controller will use. Like $helpers and $uses components in your controllers are merged with those in AppController. As with $helpers you can pass settings into components. See Conguring Components for more information.

Other Attributes
While you can check out the details for all controller attributes in the API, there are other controller attributes that merit their own sections in the manual.

Chapter 4. Controllers

CakePHP Cookbook Documentation, Release 2.x

More on controllers
Request and Response objects
New in CakePHP 2.0 are request and response objects. In previous versions these objects were represented through arrays, and the related methods were spread across RequestHandlerComponent, Router, Dispatcher and Controller. There was no authoritative object on what information the request contained. For 2.0, CakeRequest and CakeResponse are used for this purpose.

CakeRequest
CakeRequest is the default request object used in CakePHP. It centralizes a number of features for interrogating and interacting with request data. On each request one CakeRequest is created and then passed by reference to the various layers of an application that use request data. By default CakeRequest is assigned to $this->request, and is available in Controllers, Views and Helpers. You can also access it in Components by using the controller reference. 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 clients 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. Accessing request parameters CakeRequest exposes several interfaces for accessing request parameters. The rst is as object properties, the second is array indexes, and the third is through $this->request->params:
$this->request->controller; $this->request[controller]; $this->request->params[controller];

All of the above will both access the same value. Multiple ways of accessing the parameters was done to ease migration for existing applications. All Route elements are accessed through this interface. In addition to Route elements you also often need access to Passed arguments and Named parameters. These are both available on the request object as well:
// Passed arguments $this->request->pass; $this->request[pass]; $this->request->params[pass]; // named parameters $this->request->named; $this->request[named]; $this->request->params[named];

More on controllers

CakePHP Cookbook Documentation, Release 2.x

Will all provide you access to the passed arguments and named parameters. There are several important/useful parameters that CakePHP uses internally, these are also all found in the request parameters: plugin The plugin handling the request, will be null for no plugin. controller The controller handling the current request. action The action handling the current request. prefix The prex for the current action. See Prex Routing for more information. bare Present when the request came from requestAction() and included the bare option. Bare requests do not have layouts rendered. requested Present and set to true when the action came from requestAction. Accessing Querystring parameters Querystring parameters can be read from using CakeRequest::$query:
// url is /posts/index?page=1&sort=title $this->request->query[page]; // You can also access it via array access $this->request[url][page]; // BC accessor, will be deprecated in future versions

You can either directly access the query property, or you can use CakeRequest::query() to read the url query array in an error free manner. Any keys that do not exist will return null:
$foo = $this->request->query(value_that_does_not_exist); // $foo === null

Accessing POST data All POST data can be accessed using CakeRequest::$data. Any form data that contains a data prex, will have that data prex removed. For example:
// An input with a name attribute equal to data[MyModel][title] is accessible at $this->request->data[MyModel][title];

You can either directly access the data property, or you can use CakeRequest::data() to read the data array in an error free manner. Any keys that do not exist will return null:
$foo = $this->request->data(Value.that.does.not.exist); // $foo == null

Accessing PUT or POST data New in version 2.2. When building REST services you often accept request data on PUT and DELETE requests. As of 2.2 any application/x-www-form-urlencoded request body data will automatically

Chapter 4. Controllers

CakePHP Cookbook Documentation, Release 2.x

be parsed and set to $this->data for PUT and DELETE requests. If you are accepting JSON or XML data, see below for how you can access those request bodies. Accessing XML or JSON data Applications employing REST often exchange data in non URL encoded post bodies. You can read input data in any format using CakeRequest::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 $data = $this->request->input(json_decode);

Since some deserializing methods require additional parameters when being called, such as the as array parameter on json_decode or if you want XML converted into a DOMDocument object, CakeRequest::input() supports passing in additional parameters as well:
// Get Xml encoded data submitted to a PUT/POST action $data = $this->request->input(Xml::build, array(return => domdocument));

Accessing path information CakeRequest also provides useful information about the paths in your application. CakeRequest::$base and CakeRequest::$webroot are useful for generating urls, and determining whether or not your application is in a subdirectory. Inspecting 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:
$this->request->is(post); $this->request->isPost();

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 nal 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 dened 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. More on controllers 61

CakePHP Cookbook Documentation, Release 2.x

Some examples would be:

// Add an environment detector. $this->request->addDetector(post, array(env => REQUEST_METHOD, value => POST));

// Add a pattern value detector. $this->request->addDetector(iphone, array(env => HTTP_USER_AGENT, pattern => /iPho // Add an option detector $this->request->addDetector(internalIp, array( env => CLIENT_IP, options => array(192.168.0.101, 192.168.0.100) )); // Add a callback detector. Can either be an anonymous function or a regular callable. $this->request->addDetector(awesome, array(callback => function ($request) { return isset($request->awesome); }));

CakeRequest also includes methods like CakeRequest::domain(), CakeRequest::subdomains() and CakeRequest::host() to help applications with subdomains, have a slightly easier life. There are several built-in detectors that you can use: is(get) Check to see if the current request is a GET. is(put) Check to see if the current request is a PUT. is(post) Check to see if the current request is a POST. is(delete) Check to see if the current request is a DELETE. is(head) Check to see if the current request is HEAD. is(options) Check to see if the current request is OPTIONS. is(ajax) Check to see of the current request came with X-Requested-with = XmlHttpRequest. is(ssl) Check to see if the request is via SSL is(flash) Check to see if the request has a User-Agent of Flash is(mobile) Check to see if the request came from a common list of mobile agents. CakeRequest and RequestHandlerComponent Since many of the features CakeRequest offers used to be the realm of RequestHandlerComponent some rethinking was required to gure out how it still ts into the picture. 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.

Chapter 4. Controllers

CakePHP Cookbook Documentation, Release 2.x

Interacting with other aspects of the request You can use CakeRequest to introspect a variety of things about the request. Beyond the detectors, you can also nd out other information from various properties and methods. $this->request->webroot contains the webroot directory. $this->request->base contains the base path. $this->request->here contains the full address to the current request $this->request->query contains the query string parameters. CakeRequest API class CakeRequest CakeRequest encapsulates request parameter handling, and introspection. CakeRequest::domain($tldLength = 1) Returns the domain name your application is running on. CakeRequest::subdomains($tldLength = 1) Returns the subdomains your application is running on as an array. CakeRequest::host() Returns the host your application is on. CakeRequest::method() Returns the HTTP method the request was made with. CakeRequest::onlyAllow($methods) Set allowed HTTP methods, if not matched will throw MethodNotAllowedException The 405 response will include the required Allow header with the passed methods New in version 2.3. CakeRequest::referer($local = false) Returns the referring address for the request. CakeRequest::clientIp($safe = true) Returns the current visitors IP address. CakeRequest::header($name) Allows you to access any of the HTTP_* headers that were used for the request:
$this->request->header(User-Agent);

Would return the user agent used for the request. CakeRequest::input($callback[, $options ]) Retrieve the input data for a request, and optionally pass it through a decoding function. Additional parameters for the decoding function can be passed as arguments to input(). CakeRequest::data($name) Provides dot notation access to request data. Allows for reading and modication of request data, calls can be chained together as well:

More on controllers

CakePHP Cookbook Documentation, Release 2.x

// Modify some request data, so you can prepopulate some form fields. $this->request->data(Post.title, New post) ->data(Comment.1.author, Mark); // You can also read out data. $value = $this->request->data(Post.title);

CakeRequest::query($name) Provides dot notation access to url query data:

// url is /posts/index?page=1&sort=title $value = $this->request->query(page);

New in version 2.3. CakeRequest::is($type) Check whether or not a Request matches a certain criteria. Uses the built-in detection rules as well as any additional rules dened with CakeRequest::addDetector(). CakeRequest::addDetector($name, $options) Add a detector to be used with is(). See Inspecting the request for more information. CakeRequest::accepts($type = null) Find out which content types the client accepts or check if they accept a particular type of content. Get all types:
$this->request->accepts();

Check for a single type:

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

static CakeRequest::acceptLanguage($language = null) Get either all the languages accepted by the client, or check if a specic language is accepted. Get the list of accepted languages:
CakeRequest::acceptLanguage();

Check if a specic language is accepted:

CakeRequest::acceptLanguage(es-es);

CakeRequest::param($name) Safely read values in $request->params. This removes the need to call isset() or empty() before using param values. New in version 2.4. property CakeRequest::$data An array of POST data. You can use CakeRequest::data() to read this property in a way that suppresses notice errors. property CakeRequest::$query An array of query string parameters.

Chapter 4. Controllers

CakePHP Cookbook Documentation, Release 2.x

property CakeRequest::$params An array of route elements and request parameters. property CakeRequest::$here Returns the current request uri. property CakeRequest::$base The base path to the application, usually / unless your application is in a subdirectory. property CakeRequest::$webroot The current webroot.

CakeResponse
CakeResponse is the default response class in CakePHP. It encapsulates a number of features and functionality for generating HTTP responses in your application. It also assists in testing, as it can be mocked/stubbed allowing you to inspect headers that will be sent. Like CakeRequest, CakeResponse consolidates a number of methods previously found on Controller, RequestHandlerComponent and Dispatcher. The old methods are deprecated in favour of using CakeResponse. CakeResponse provides an interface to wrap the common response related tasks such as: Sending headers for redirects. Sending content type headers. Sending any header. Sending the response body. Changing the response class CakePHP uses CakeResponse by default. CakeResponse is a exible and transparent to use class. But if you need to replace it with an application specic class, you can override and replace CakeResponse with your own class. By replacing the CakeResponse used in index.php. This will make all the controllers in your application use CustomResponse instead of CakeResponse. You can also replace the response instance used by setting $this->response in your controllers. Overriding the response object is handy during testing, as it allows you to stub out the methods that interact with header(). See the section on CakeResponse and testing for more information. Dealing with content types You can control the Content-Type of your applications responses with using CakeResponse::type(). If your application needs to deal with content types that are not built into CakeResponse, you can map those types with type() as well:
// Add a vCard type $this->response->type(array(vcf => text/v-card));

More on controllers

CakePHP Cookbook Documentation, Release 2.x

// Set the response Content-Type to vcard. $this->response->type(vcf);

Usually youll want to map additional content types in your controllers beforeFilter callback, so you can leverage the automatic view switching features of RequestHandlerComponent if you are using it. Sending les There are times when you want to send les as responses for your requests. Prior to version 2.3 you could use Media Views to accomplish that. As of 2.3 MediaView is deprecated and you can use CakeResponse::file() to send a le as response:
public function sendFile($id) { $file = $this->Attachment->getFile($id); $this->response->file($file[path]); //Return reponse object to prevent controller from trying to render a view return $this->response; }

As shown in above example as expected you have to pass the le path to the method. Cake will send proper content type header if its a known le type listed in CakeReponse::$_mimeTypes. You can add new types prior to calling CakeResponse::file() by using the CakeResponse::type() method. If you want you can also force a le to be downloaded instead of being displayed in the browser by specifying the options:
$this->response->file($file[path], array(download => true, name => foo));

Sending a string as le To send a le as response which does not exist on disk, for instance when you generate pdf or ics on the y and want to serve the generated string as le you can do that by using:
public function sendIcs() { $icsString = $this->Calendar->generateIcs(); $this->response->body($icsString); $this->response->type(ics); //Optionally force file download $this->response->download(filename_for_download.ics) //Return response object to prevent controller from trying to render a view return $this->response; }

Setting headers Setting headers is done with the CakeResponse::header() method. It can be called with a few different parameter congurations: 66 Chapter 4. Controllers

CakePHP Cookbook Documentation, Release 2.x

// Set a single header $this->response->header(Location, http://example.com);

// Set multiple headers $this->response->header(array(Location => http://example.com, X-Extra => My header) $this->response->header(array(WWW-Authenticate: Negotiate, Content-type: application/pdf

Setting the same header multiple times will result in overwriting the previous values, just like regular header calls. Headers are not sent when CakeResponse::header() is called either. They are just buffered until the response is actually sent. New in version 2.4. You can now use the convenience method CakeResponse::location() to directly set or get the redirect location header. Interacting with browser caching You sometimes need to force browsers to not cache the results of a controller action. CakeResponse::disableCache() is intended for just that:
public function index() { // do something. $this->response->disableCache(); }

Warning: Using disableCache() with downloads from SSL domains while trying to send les to Internet Explorer can result in errors. You can also tell clients that you want them to cache responses. By using CakeResponse::cache():
public function index() { //do something $this->response->cache(-1 minute, +5 days); }

The above would tell clients to cache the resulting response for 5 days, hopefully speeding up your visitors experience. cache() sets the Last-Modied value to the rst argument. Expires, and Max-age are set based on the second parameter. Cache-Control is set to public as well. Fine tuning HTTP cache One of the best and easiest ways of speeding up your application is using HTTP cache. Under this caching model you are only required to help clients decide if they should use a cached copy of the response by setting a few headers such as modied time, response entity tag and others. Opposed to having to code the logic for caching and for invalidating (refreshing) it once the data has changed, HTTP uses two models, expiration and validation which usually are a lot simpler than having to manage the cache yourself. Apart from using CakeResponse::cache() you can also use many other methods to ne tune HTTP cache headers to take advantage of browser or reverse proxy caching.

More on controllers

CakePHP Cookbook Documentation, Release 2.x

The Cache Control header

New in version 2.1. Used under the expiration model, this header contains multiple indicators which can change the way browsers or proxies use the cached content. A Cache-Control header can look like this:
Cache-Control: private, max-age=3600, must-revalidate

CakeResponse class helps you set this header with some utility methods that will produce a nal valid Cache-Control header. First of them is CakeResponse::sharable() method, which indicates whether a response in to be considered sharable across different users or clients or users. This method actually controls the public or private part of this header. Setting a response as private indicates that all or part of it is intended for a single user. To take advantage of shared caches it is needed to set the control directive as public Second parameter of this method is used to specify a max-age for the cache, which is the number of seconds after which the response is no longer considered fresh.:
public function view() { ... // set the Cache-Control as public for 3600 seconds $this->response->sharable(true, 3600); } public function my_data() { ... // set the Cache-Control as private for 3600 seconds $this->response->sharable(false, 3600); }

CakeResponse exposes separate methods for setting each of the components in the Cache-Control header.
The Expiration header

New in version 2.1. Also under the cache expiration model, you can set the Expires header, which according to the HTTP specication is the date/time after which the response is no longer considered fresh. This header can be set using the CakeResponse::expires() method:
public function view() { $this->response->expires(+5 days); }

This method also accepts a DateTime or any string that can be parsed by the DateTime class.
The Etag header

New in version 2.1. Cache validation in HTTP is often used when content is constantly changing, and asks the application to only generate the response contents if the cache is no longer fresh. Under this model, the client continues to store pages in the cache, but instead of using it directly, it asks the application every time whether the resources changed or not. This is commonly used with static resources such as images and other assets. 68 Chapter 4. Controllers

CakePHP Cookbook Documentation, Release 2.x

The Etag header (called entity tag) is string that uniquely identies the requested resource. It is very much like the checksum of a le, caching will compare checksums to tell whether they match or not. To actually get advantage of using this header you have to either call manually CakeResponse::checkNotModified() method or have the RequestHandlerComponent included in your controller:
public function index() { $articles = $this->Article->find(all); $this->response->etag($this->Article->generateHash($articles)); if ($this->response->checkNotModified($this->request)) { return $this->response; } ... }

The Last Modied header

New in version 2.1. Also under the HTTP cache validation model, you can set the Last-Modied header to indicate the date and time at which the resource was modied for the last time. Setting this header helps CakePHP respond to caching clients whether the response was modied or not based on the client cache. To actually get advantage of using this header you have to either call manually CakeResponse::checkNotModified() method or have the RequestHandlerComponent included in your controller:
public function view() { $article = $this->Article->find(first); $this->response->modified($article[Article][modified]); if ($this->response->checkNotModified($this->request)) { return $this->response; } ... }

The Vary header

In some cases you might want to serve different contents using the same url. This is often the case when you have a multilingual page or respond with different HTML according to the browser that is requesting the resource. For such circumstances, you use the Vary header:
$this->response->vary(User-Agent); $this->response->vary(Accept-Encoding, User-Agent); $this->response->vary(Accept-Language);

CakeResponse and testing Probably one of the biggest wins from CakeResponse comes from how it makes testing controllers and components easier. Instead of methods spread across several objects, you only have a single object to mock More on controllers 69

CakePHP Cookbook Documentation, Release 2.x

as controllers and components delegate to CakeResponse. This helps you get closer to a unit test and makes testing controllers easier:
public function testSomething() { $this->controller->response = $this->getMock(CakeResponse); $this->controller->response->expects($this->once())->method(header); // ... }

Additionally you can more easily run tests from the command line, as you can use mocks to avoid the headers sent errors that can come up from trying to set headers in CLI. CakeResponse API class CakeResponse CakeResponse provides a number of useful methods for interacting with the response you are sending to a client. CakeResponse::header($header = null, $value = null) Allows you to directly set one or many headers to be sent with the response. CakeResponse::location($url = null) Allows you to directly set the redirect location header to be sent with the response. // Set the redirect location $this->response->location(http://example.com); // Get the current redirect location header $location = $this->response->location(); New in version 2.4. CakeResponse::charset($charset = null) Sets the charset that will be used in the response. CakeResponse::type($contentType = null) Sets the content type for the response. You can either use a known content type alias or the full content type name. CakeResponse::cache($since, $time = +1 day) Allows you to set caching headers in the response. CakeResponse::disableCache() Sets the headers to disable client caching for the response. CakeResponse::sharable($public = null, $time = null) Sets the Cache-Control header to be either public or private and optionally sets a max-age directive of the resource New in version 2.1. CakeResponse::expires($time = null) Allows to set the Expires header to a specic date. New in version 2.1. CakeResponse::etag($tag = null, $weak = false) Sets the Etag header to uniquely identify a response resource. New in version 2.1. CakeResponse::modified($time = null) Sets the Last-Modied header to a specic date and time in the correct format. New in version 2.1. 70 Chapter 4. Controllers

CakePHP Cookbook Documentation, Release 2.x

CakeResponse::checkNotModified(CakeRequest $request) Compares the cache headers for the request object with the cache header from the response and determines if it can still be considered fresh. In that case deletes any response contents and sends the 304 Not Modied header. New in version 2.1. CakeResponse::compress() Turns on gzip compression for the request. CakeResponse::download($lename) Allows you to send the response as an attachment and set the lename. CakeResponse::statusCode($code = null) Allows you to set the status code for the response. CakeResponse::body($content = null) Set the content body for the response. CakeResponse::send() Once you are done creating a response, calling send() will send all the set headers as well as the body. This is done automatically at the end of each request by Dispatcher CakeResponse::file($path, $options = array()) Allows you to set a le for display or download New in version 2.3.

Scaffolding
Application scaffolding is a technique that allows a developer to dene and create a basic application that can create, retrieve, update and delete objects. Scaffolding in CakePHP also allows developers to dene how objects are related to each other, and to create and break those links. All thats needed to create a scaffold is a model and its controller. Once you set the $scaffold variable in the controller, youre up and running. CakePHPs scaffolding is pretty cool. It allows you to get a basic CRUD application up and going in minutes. Its so cool that youll want to use it in production apps. Now, we think its cool too, but please realize that scaffolding is... well... just scaffolding. Its a loose structure you throw up real quick during the beginning of a project in order to get started. It isnt meant to be completely exible, its meant as a temporary way to get up and going. If you nd yourself really wanting to customize your logic and your views, its time to pull your scaffolding down in order to write some code. CakePHPs Bake console, covered in the next section, is a great next step: it generates all the code that would produce the same result as the most current scaffold. Scaffolding is a great way of getting the early parts of developing a web application started. Early database schemas are subject to change, which is perfectly normal in the early part of the design process. This has a downside: a web developer hates creating forms that never will see real use. To reduce the strain on the developer, scaffolding has been included in CakePHP. Scaffolding analyzes your database tables and creates standard lists with add, delete and edit buttons, standard forms for editing and standard views for inspecting a single item in the database. To add scaffolding to your application, in the controller, add the $scaffold variable:

More on controllers

CakePHP Cookbook Documentation, Release 2.x

class CategoriesController extends AppController { public $scaffold; }

Assuming youve created even the most basic Category model class le (in /app/Model/Category.php), youre ready to go. Visit http://example.com/categories to see your new scaffold. Note: Creating methods in controllers that are scaffolded can cause unwanted results. For example, if you create an index() method in a scaffolded controller, your index method will be rendered rather than the scaffolding functionality. Scaffolding is knowledgeable about model associations, so if your Category model belongsTo a User, youll see related User IDs in the Category listings. While scaffolding knows about model associations, you will not see any related records in the scaffold views until you manually add the association code to the model. For example, if Group hasMany User and User belongsTo Group, you have to manually add the following code in your User and Group models. Before you add the following code, the view displays an empty select input for Group in the New User form. After you add the following code, the view displays a select input populated with IDs or names from the Group table in the New User form:
// In Group.php public $hasMany = User; // In User.php public $belongsTo = Group;

If youd rather see something besides an ID (like the users rst name), you can set the $displayField variable in the model. Lets set the $displayField variable in our User class so that users related to categories will be shown by rst name rather than just an ID in scaffolding. This feature makes scaffolding more readable in many instances:
class User extends AppModel { public $displayField = first_name; }

Creating a simple admin interface with scaffolding If you have enabled admin routing in your app/Cong/core.php, with Configure::write(Routing.prefixes, array(admin)); you can use scaffolding to generate an admin interface. Once you have enabled admin routing assign your admin prex to the scaffolding variable:
public $scaffold = admin;

You will now be able to access admin scaffolded actions:

http://example.com/admin/controller/index http://example.com/admin/controller/view http://example.com/admin/controller/edit http://example.com/admin/controller/add http://example.com/admin/controller/delete

Chapter 4. Controllers

CakePHP Cookbook Documentation, Release 2.x

This is an easy way to create a simple backend interface quickly. Keep in mind that you cannot have both admin and non-admin methods scaffolded at the same time. As with normal scaffolding you can override individual methods and replace them with your own:
public function admin_view($id = null) { // custom code here }

Once you have replaced a scaffolded action you will need to create a view le for the action as well. Customizing Scaffold Views If youre looking for something a little different in your scaffolded views, you can create templates. We still dont recommend using this technique for production applications, but such a customization may be useful during prototyping iterations. Custom scaffolding views for a specic controller (PostsController in this example) should be placed like so:
/app/View/Posts/scaffold.index.ctp /app/View/Posts/scaffold.form.ctp /app/View/Posts/scaffold.view.ctp

Custom scaffolding views for all controllers should be placed like so:
/app/View/Scaffolds/index.ctp /app/View/Scaffolds/form.ctp /app/View/Scaffolds/view.ctp

The Pages Controller

CakePHP ships with a default controller PagesController.php. This is a simple and optional controller for serving up static content. The home page you see after installation is generated using this controller. If you make the view le app/View/Pages/about_us.ctp you can access it using the url http://example.com/pages/about_us. You are free to modify the Pages Controller to meet your needs. When you bake an app using CakePHPs console utility the Pages Controller is created in your app/Controller/ folder. You can also copy the le from lib/Cake/Console/Templates/skel/Controller/PagesController.php. Changed in version 2.1: With CakePHP 2.0 the Pages Controller was part of lib/Cake. Since 2.1 the Pages Controller is no longer part of the core but ships in the app folder. Warning: Do not directly modify ANY le under the lib/Cake folder to avoid issues when updating the core in future.

More on controllers

CakePHP Cookbook Documentation, Release 2.x

Components
Components are packages of logic that are shared between controllers. If you nd yourself wanting to copy and paste things between controllers, you might consider wrapping some functionality in a component. CakePHP also comes with a fantastic set of core components you can use to aid in: Pagination class PaginatorComponent(ComponentCollection $collection, array $settings = array()) One of the main obstacles of creating exible and user-friendly web applications is designing an intuitive UI. Many applications tend to grow in size and complexity quickly, and designers and programmers alike nd they are unable to cope with displaying hundreds or thousands of records. Refactoring takes time, and performance and user satisfaction can suffer. Displaying a reasonable number of records per page has always been a critical part of every application and used to cause many headaches for developers. CakePHP eases the burden on the developer by providing a quick, easy way to paginate data. Pagination in CakePHP is offered by a Component in the controller, to make building paginated queries easier. In the View PaginatorHelper is used to make the generation of pagination links & buttons simple.
Query Setup

In the controller, we start by dening the query conditions pagination will use by default in the $paginate controller variable. These conditions, serve as the basis of your pagination queries. They are augmented by the sort, direction limit, and page parameters passed in from the url. It is important to note here that the order key must be dened in an array structure like below:
class PostsController extends AppController { public $components = array(Paginator); public $paginate = array( limit => 25, order => array( Post.title => asc ) ); }

You can also include other find() options, such as fields:

class PostsController extends AppController { public $components = array(Paginator); public $paginate = array( fields => array(Post.id, Post.created),

Chapter 4. Controllers

CakePHP Cookbook Documentation, Release 2.x

limit => 25, order => array( Post.title => asc ) ); }

Other keys that can be included in the $paginate array are similar to the parameters of the Model->find(all) method, that is: conditions, fields, order, limit, page, contain, joins, and recursive. In addition to the aforementioned keys, any additional keys will also be passed directly to the model nd methods. This makes it very simple to use behaviors like ContainableBehavior with pagination:
class RecipesController extends AppController { public $components = array(Paginator); public $paginate = array( limit => 25, contain => array(Article) ); }

In addition to dening general pagination values, you can dene more than one set of pagination defaults in the controller, you just name the keys of the array after the model you wish to congure:
class PostsController extends AppController { public $paginate = array( Post => array (...), Author => array (...) ); }

The values of the Post and Author keys could contain all the properties that a model/key less $paginate array could. Once the $paginate variable has been dened, we can use the PaginatorComponents paginate() method from our controller action. This will return find() results from the model. It also sets some additional paging parameters, which are added to the request object. The additional information is set to $this->request->params[paging], and is used by PaginatorHelper for creating links. PaginatorComponent::paginate() also adds PaginatorHelper to the list of helpers in your controller, if it has not been added already.:
public function list_recipes() { $this->Paginator->settings = $this->paginate; // similar to findAll(), but fetches paged results $data = $this->Paginator->paginate(Recipe); $this->set(data, $data); }

You can lter the records by passing conditions as second parameter to the paginate() function.: More on controllers 75

CakePHP Cookbook Documentation, Release 2.x

$data = $this->Paginator->paginate(Recipe, array(Recipe.title LIKE => a%));

Or you can also set conditions and other pagination settings array inside your action.:
public function list_recipes() { $this->Paginator->settings = array( conditions => array(Recipe.title LIKE => a%), limit => 10 ); $data = $this->Paginator->paginate(Recipe); $this->set(compact(data)); );

Custom Query Pagination

If youre not able to use the standard nd options to create the query you need to display your data, there are a few options. You can use a custom nd type. You can also implement the paginate() and paginateCount() methods on your model, or include them in a behavior attached to your model. Behaviors implementing paginate and/or paginateCount should implement the method signatures dened below with the normal additional rst parameter of $model:

// paginate and paginateCount implemented on a behavior. public function paginate(Model $model, $conditions, $fields, $order, $limit, $page = 1, $re // method content }

public function paginateCount(Model $model, $conditions = null, $recursive = 0, $extra = ar // method body }

Its seldom youll need to implement paginate() and paginateCount(). You should make sure you cant achieve your goal with the core model methods, or a custom nder. To paginate with a custom nd type, you should set the 0th element, or the findType key as of 2.3:
public $paginate = array( popular );

Since the 0th index is difcult to manage, in 2.3 the findType option was added:
public $paginate = array( findType => popular );

The paginate() method should implement the following method signature. method/logic override it in the model you wish to get the data from:

To use your own

/** * Overridden paginate method - group by week, away_team_id and home_team_id */ public function paginate($conditions, $fields, $order, $limit, $page = 1, $recursive = null $recursive = -1;

Chapter 4. Controllers

CakePHP Cookbook Documentation, Release 2.x

$group = $fields = array(week, away_team_id, home_team_id); return $this->find(all, compact(conditions, fields, order, limit, page, re }

You also need to override the core paginateCount(), this method expects the same arguments as Model::find(count). The example below uses some Postgres-specifc features, so please adjust accordingly depending on what database you are using:

/** * Overridden paginateCount method */ public function paginateCount($conditions = null, $recursive = 0, $extra = array()) { $sql = "SELECT DISTINCT ON(week, home_team_id, away_team_id) week, home_team_id, away_t $this->recursive = $recursive; $results = $this->query($sql); return count($results); }

The observant reader will have noticed that the paginate method weve dened wasnt actually necessary All you have to do is add the keyword in controllers $paginate class variable:
/** * Add GROUP BY clause */ public $paginate = array( MyModel => array( limit => 20, order => array(week => desc), group => array(week, home_team_id, away_team_id) ) ); /** * Or on-the-fly from within the action */ public function index() { $this->Paginator->settings = array( MyModel => array( limit => 20, order => array(week => desc), group => array(week, home_team_id, away_team_id) ) ); }

In CakePHP 2.0, you no longer need to implement paginateCount() when using group clauses. The core find(count) will correctly count the total number of rows.
Control which elds used for ordering

By default sorting can be done with any column on a model. This is sometimes undesirable as it can allow users to sort on un-indexed columns, or virtual elds that can be expensive to calculate. You can use the 3rd parameter of PaginatorComponent::paginate() to restrict the columns sorting will be done on: More on controllers 77

CakePHP Cookbook Documentation, Release 2.x

$this->Paginator->paginate(Post, array(), array(title, slug));

This would allow sorting on the title and slug columns only. A user that sets sort to any other value will be ignored.
Limit the maximum number of rows that can be fetched

The number of results that are fetched is exposed to the user as the limit parameter. It is generally undesirable to allow users to fetch all rows in a paginated set. By default CakePHP limits the maximum number of rows that can be fetched to 100. If this default is not appropriate for your application, you can adjust it as part of the pagination options:
public $paginate = array( // other keys here. maxLimit => 10 );

If the requests limit param is greater than this value, it will be reduced to the maxLimit value.
Pagination with GET parameters

In previous versions of CakePHP you could only generate pagination links using named parameters. But if pages were requested with GET parameters they would still work. For 2.0, we decided to make how you generate pagination parameters more controlled and consistent. You can choose to use either querystring or named parameters in the component. Incoming requests will accept only the chosen type, and the PaginatorHelper will generate links with the chosen type of parameter:
public $paginate = array( paramType => querystring );

The above would enable querystring parameter parsing and generation. $settings property on the PaginatorComponent:
$this->Paginator->settings[paramType] = querystring;

You can also modify the

By default all of the typical paging parameters will be converted into GET arguments. Note: You can run into a situation where assigning a value to a nonexistent property will throw errors:
$this->paginate[limit] = 10;

will throw the error Notice: Indirect modication of overloaded property $paginate has no effect. Assigning an initial value to the property solves the issue:
$this->paginate = array(); $this->paginate[limit] = 10; //or $this->paginate = array(limit => 10);

Chapter 4. Controllers

CakePHP Cookbook Documentation, Release 2.x

Or just declare the property in the controller class:

class PostsController { public $paginate = array(); }

Or use $this->Paginator->settings = array(limit => 10); Make sure you have added the Paginator component to your $components array if you want to modify the $settings property of the PaginatorComponent. Either of these approaches will solve the notice errors.

Out of range page requests

As of 2.3 the PaginatorComponent will throw a NotFoundException when trying to access a non-existent page, i.e. page number requested is greater than total page count. So you could either let the normal error page be rendered or use a try catch block and take appropriate action when a NotFoundException is caught:
public function index() { try { $this->Paginator->paginate(); } catch (NotFoundException $e) { //Do something here like redirecting to first or last page. //$this->request->params[paging] will give you required info. } }

AJAX Pagination

Its very easy to incorporate Ajax functionality into pagination. Using the JsHelper and RequestHandlerComponent you can easily add Ajax pagination to your application. See Ajax Pagination for more information.
Pagination in the view

Check the PaginatorHelper documentation for how to create links for pagination navigation. Sessions class SessionComponent(ComponentCollection $collection, array $settings = array()) The CakePHP SessionComponent provides a way to persist client data between page requests. It acts as a wrapper for $_SESSION as well as providing convenience methods for several $_SESSION related functions.

More on controllers

CakePHP Cookbook Documentation, Release 2.x

Sessions can be congured in a number of ways in CakePHP. For more information, you should see the Session conguration documentation.
Interacting with Session data

The Session component is used to interact with session information. It includes basic CRUD functions as well as features for creating feedback messages to users. It should be noted that Array structures can be created in the Session by using dot notation. User.username would reference the following:
array(User => array( username => [email protected] ));

Dots are used to indicate nested arrays. This notation is used for all Session component methods wherever a name/key is used. SessionComponent::write($name, $value) Write to the Session puts $value into $name. $name can be a dot separated array. For example:
$this->Session->write(Person.eyeColor, Green);

This writes the value Green to the session under Person => eyeColor. SessionComponent::read($name) Returns the value at $name in the Session. If $name is null the entire session will be returned. E.g:
$green = $this->Session->read(Person.eyeColor);

Retrieve the value Green from the session. Reading data that does not exist will return null. SessionComponent::check($name) Used to check if a Session variable has been set. Returns true on existence and false on non-existence. SessionComponent::delete($name) Clear the session data at $name. E.g:
$this->Session->delete(Person.eyeColor);

Our session data no longer has the value Green, or the index eyeColor set. However, Person is still in the Session. To delete the entire Person information from the session use:
$this->Session->delete(Person);

SessionComponent::destroy() The destroy method will delete the session cookie and all session data stored in the temporary le system. It will then destroy the PHP session and then create a fresh session:
$this->Session->destroy();

Chapter 4. Controllers

CakePHP Cookbook Documentation, Release 2.x

Creating notication messages

SessionComponent::setFlash(string $message, string $element = default, array $params = array(), string $key = ash) Return type void Often in web applications, you will need to display a one-time notication message to the user after processing a form or acknowledging data. In CakePHP, these are referred to as ash messages. You can set ash message with the SessionComponent and display them with the SessionHelper::flash(). To set a message, use setFlash:
// In the controller. $this->Session->setFlash(Your stuff has been saved.);

This will create a one-time message that can be displayed to the user, using the SessionHelper:
// In the view. echo $this->Session->flash(); // The above will output. <div id="flashMessage" class="message"> Your stuff has been saved. </div>

You can use the additional parameters of setFlash() to create different kinds of ash messages. For example, error and positive notications may look differently. CakePHP gives you a way to do that. Using the $key parameter you can store multiple messages, which can be output separately:
// set a bad message. $this->Session->setFlash(Something bad., default, array(), bad); // set a good message. $this->Session->setFlash(Something good., default, array(), good);

In the view, these messages can be output and styled differently:

// in a view. echo $this->Session->flash(good); echo $this->Session->flash(bad);

The $element parameter allows you to control which element (located in /app/View/Elements) should be used to render the message in. In the element the message is available as $message. First we set the ash in our controller:
$this->Session->setFlash(Something custom!, flash_custom);

Then we create the le app/View/Elements/flash_custom.ctp and build our custom ash element:
<div id="myCustomFlash"><?php echo h($message); ?></div>

$params allows you to pass additional view variables to the rendered layout. Parameters can be passed affecting the rendered div, for example adding class in the $params array will apply a class More on controllers 81

CakePHP Cookbook Documentation, Release 2.x

to the div output using $this->Session->flash() in your layout or view.:

$this->Session->setFlash(Example message text, default, array(class => example_

The output from using $this->Session->flash() with the above example would be:
<div id="flashMessage" class="example_class">Example message text</div>

To use an element from a plugin just specify the plugin in the $params:
// Will use /app/Plugin/Comment/View/Elements/flash_no_spam.ctp $this->Session->setFlash(Message!, flash_no_spam, array(plugin => Comment));

Note: By default CakePHP does not HTML escape ash messages. If you are using any request or user data in your ash messages you should escape it with h when formatting your messages.

Authentication class AuthComponent(ComponentCollection $collection, array $settings = array()) Identifying, authenticating and authorizing users is a common part of almost every web application. In CakePHP AuthComponent provides a pluggable way to do these tasks. AuthComponent allows you to combine authentication objects, and authorization objects to create exible ways of identifying and checking user authorization.
Authentication

Authentication is the process of identifying users by provided credentials and ensuring that users are who they say they are. Generally this is done through a username and password, that are checked against a known list of users. In CakePHP, there are several built in ways of authenticating users stored in your application. FormAuthenticate allows you to authenticate users based on form POST data. Usually this is a login form that users enter information into. BasicAuthenticate allows you to authenticate users using Basic HTTP authentication. DigestAuthenticate allows you to authenticate users using Digest HTTP authentication. By default AuthComponent uses FormAuthenticate. Choosing an Authentication type Generally youll want to offer form based authentication. It is the easiest for users using a web-browser to use. If you are building an API or webservice, you may want to consider basic authentication or digest authentication. The key differences between digest and basic authentication are mostly related to how passwords are handled. In basic authentication, the username and password are transmitted as plain-text to the server. This makes basic authentication un-suitable for applications without SSL, as you would end up exposing sensitive passwords. Digest authentication uses a digest hash of the username, password, and a few other details. This makes digest authentication more appropriate for applications without SSL encryption.

Chapter 4. Controllers

CakePHP Cookbook Documentation, Release 2.x

You can also use authentication systems like openid as well, however openid is not part of CakePHP core. Conguring Authentication handlers You congure authentication handlers using $this->Auth->authenticate. You can congure one or many handlers for authentication. Using multiple handlers allows you to support different ways of logging users in. When logging users in, authentication handlers are checked in the order they are declared. Once one handler is able to identify the user, no other handlers will be checked. Conversely you can halt all authentication by throwing an exception. You will need to catch any thrown exceptions, and handle them as needed. You can congure authentication handlers in your controllers beforeFilter or, in the $components array. You can pass conguration information into each authentication object, using an array:
// Basic setup $this->Auth->authenticate = array(Form); // Pass settings in $this->Auth->authenticate = array( Basic => array(userModel => Member), Form => array(userModel => Member) );

In the second example youll notice that we had to declare the userModel key twice. To help you keep your code DRY, you can use the all key. This special key allows you to set settings that are passed to every attached object. The all key is also exposed as AuthComponent::ALL:
// Pass settings in using all $this->Auth->authenticate = array( AuthComponent::ALL => array(userModel => Member), Basic, Form );

In the above example, both Form and Basic will get the settings dened for the all key. Any settings passed to a specic authentication object will override the matching key in the all key. The core authentication objects support the following conguration keys. fields The elds to use to identify a user by. userModel The model name of the User, defaults to User. scope Additional conditions to use when looking up and authenticating users, array(User.is_active => 1). contain Containable options for when the user record is loaded. New in version 2.2. passwordHasher Password hasher class. Defaults to Simple. New in version 2.4. To congure different elds for user in $components array:
// Pass settings in $components array public $components = array( Auth => array( authenticate => array( Form => array(

i.e.

More on controllers

CakePHP Cookbook Documentation, Release 2.x

fields => array(username => email) ) ) ) );

Do not put other Auth conguration keys (like authError, loginAction etc) within the authenticate or Form element. They should be at the same level as the authenticate key. The setup above with other Auth conguration should look like:
// Pass settings in $components array public $components = array( Auth => array( loginAction => array( controller => users, action => login, plugin => users ), authError => Did you really think you are allowed to see that?, authenticate => array( Form => array( fields => array(username => email) ) ) ) );

In addition to the common conguration, Basic authentication supports the following keys: realm The realm being authenticated. Defaults to env(SERVER_NAME). In addition to the common conguration Digest authentication supports the following keys: realm The realm authentication is for, Defaults to the servername. nonce A nonce used for authentication. Defaults to uniqid(). qop Defaults to auth, no other values are supported at this time. opaque A string that must md5($settings[realm]) be returned unchanged by clients. Defaults to

Identifying users and logging them in In the past AuthComponent auto-magically logged users in. This was confusing for many people, and made using AuthComponent a bit difcult at times. For 2.0, youll need to manually call $this->Auth->login() to log a user in. When authenticating users, attached authentication objects are checked in the order they are attached. Once one of the objects can identify the user, no other objects are checked. A sample login function for working with a login form could look like:
public function login() { if ($this->request->is(post)) { if ($this->Auth->login()) { return $this->redirect($this->Auth->redirectUrl());

Chapter 4. Controllers

CakePHP Cookbook Documentation, Release 2.x

// Prior to 2.3 use return $this->redirect($this->Auth->redirect()); } else { $this->Session->setFlash(__(Username or password is incorrect), default, ar } } }

The above code (without any data passed to the login method), will attempt to log a user in using the POST data, and if successful redirect the user to either the last page they were visiting, or AuthComponent::$loginRedirect. If the login is unsuccessful, a ash message is set. Warning: In 2.x $this->Auth->login($this->request->data) will log the user in with whatever data is posted, whereas in 1.3 $this->Auth->login($this->data) would try to identify the user rst and only log in when successful.

Using Digest and Basic Authentication for logging in Because basic and digest authentication dont require an initial POST or a form so if using only basic / digest authenticators you dont require a login action in your controller. Also you can set AuthComponent::$sessionKey to false to ensure AuthComponent doesnt try to read user info from session. Stateless authentication will re-verify the users credentials on each request, this creates a small amount of additional overhead, but allows clients that to login in without using cookies. Note: Prior to 2.4 you still need the login action as you are redirected to login when an unauthenticated user tries to access a protected page even when using only basic or digest auth. Also setting AuthComponent::$sessionKey to false will cause an error prior to 2.4.

Creating Custom Authentication objects Because authentication objects are pluggable, you can create custom authentication objects in your application or plugins. If for example you wanted to create an OpenID authentication object. In app/Controller/Component/Auth/OpenidAuthenticate.php you could put the following:
App::uses(BaseAuthenticate, Controller/Component/Auth); class OpenidAuthenticate extends BaseAuthenticate { public function authenticate(CakeRequest $request, CakeResponse $response) { // Do things for OpenID here. // Return an array of user if they could authenticate the user, // return false if not } }

Authentication objects should return false if they cannot identify the user. And an array of user information if they can. Its not required that you extend BaseAuthenticate, only that your authentication object implements an authenticate() method. The BaseAuthenticate class provides a number of helpful methods that are commonly used. You can also implement a getUser() method if your authentication object needs to support stateless or cookie-less authentication. See the sections on basic and digest authentication below for more information. More on controllers 85

CakePHP Cookbook Documentation, Release 2.x

Using custom authentication objects Once youve created your custom authentication object, you can use them by including them in AuthComponents authenticate array:
$this->Auth->authenticate = array( Openid, // app authentication object. AuthBag.Combo, // plugin authentication object. );

Creating stateless authentication systems Authentication objects can implement a getUser() method that can be used to support user login systems that dont rely on cookies. A typical getUser method looks at the request/environment and uses the information there to conrm the identity of the user. HTTP Basic authentication for example uses $_SERVER[PHP_AUTH_USER] and $_SERVER[PHP_AUTH_PW] for the username and password elds. On each request, these values are used to re-identify the user and ensure they are valid user. As with authentication objects authenticate() method the getUser() method should return an array of user information on success or false on failure.:
public function getUser($request) { $username = env(PHP_AUTH_USER); $pass = env(PHP_AUTH_PW); if (empty($username) || empty($pass)) { return false; } return $this->_findUser($username, $pass); }

The above is how you could implement getUser method for HTTP basic authentication. The _findUser() method is part of BaseAuthenticate and identies a user based on a username and password. Handling unauthenticated requests When an unauthenticated user tries to access a protected page rst the unauthenticated() method of the last authenticator in the chain is called. The authenticate object can handle sending response or redirection as appropriate and return true to indicate no further action is necessary. Due to this the order in which you specify the authenticate object in AuthComponent::$authenticate property matters. If authenticator returns null, AuthComponent redirects user to login action. If its an ajax request and AuthComponent::$ajaxLogin is specied that element is rendered else a 403 http status code is returned. Note: Prior to 2.4 the authenticate objects do not provide an unauthenticated() method.

Displaying auth related ash messages In order to display the session error messages that Auth generates, you need to add the following code to your layout. Add the following two lines to the app/View/Layouts/default.ctp le in the body section preferable before the content_for_layout line.:

Chapter 4. Controllers

CakePHP Cookbook Documentation, Release 2.x

echo $this->Session->flash(); echo $this->Session->flash(auth);

You can customize the error messages, and ash settings AuthComponent uses. Using $this->Auth->flash you can congure the parameters AuthComponent uses for setting ash messages. The available keys are element - The element to use, defaults to default. key - The key to use, defaults to auth params - The array of additional params to use, defaults to array() In addition to the ash message settings you can customize other error messages AuthComponent uses. In your controllers beforeFilter, or component settings you can use authError to customize the error used for when authorization fails:

$this->Auth->authError = "This error shows up with the user tries to access a part of the w

Changed in version 2.4: Sometimes, you want to display the authorization error only after the user has already logged-in. You can suppress this message by setting its value to boolean false In your controllers beforeFilter(), or component settings:
if (!$this->Auth->loggedIn()) { $this->Auth->authError = false; }

Hashing passwords AuthComponent no longer automatically hashes every password it can nd. This was removed because it made a number of common tasks like validation difcult. You should never store plain text passwords, and before saving a user record you should always hash the password. As of 2.4 the generation and checking of password hashes has been delegated to password hasher classes. Authenticating objects use a new setting passwordHasher which species the password hasher class to use. It can be a string specifying class name or an array with key className stating the class name and any extra keys will be passed to password hasher constructor as cong. The default hasher class Simple can be used for sha1, sha256, md5 hashing. By default the hash type set in Security class will be used. You can use specic hash type like this:
public $components = array( Auth => array( authenticate => array( Form => array( passwordHasher => array( className => Simple, hashType => sha256 ) ) ) ) );

When creating new user records you can hash a password in the beforeSave callback of your model using appropriate password hasher class: More on controllers 87

CakePHP Cookbook Documentation, Release 2.x

App::uses(SimplePasswordHasher, Controller/Component/Auth);

class User extends AppModel { public function beforeSave($options = array()) { if (!$this->id) { $passwordHasher = new SimplePasswordHasher(); $this->data[User][password] = $passwordHasher->hash($this->data[User][pa } return true; } }

You dont need to hash passwords before calling $this->Auth->login(). The various authentication objects will hash passwords individually. Using bcrypt for passwords In CakePHP 2.3 the BlowfishAuthenticate class was introduced to allow using bcrypt (https://en.wikipedia.org/wiki/Bcrypt) a.k.a Blowsh for hash passwords. Bcrypt hashes are much harder to brute force than passwords stored with sha1. But BlowfishAuthenticate has been deprecated in 2.4 and instead BlowfishPasswordHasher has been added. A blowsh password hasher can be used with any authentication class. All you have to do with specify passwordHasher setting for the authenticating object:
public $components = array( Auth => array( authenticate => array( Form => array( passwordHasher => Blowfish ) ) ) );

Hashing passwords for digest authentication Because Digest authentication requires a password hashed in the format dened by the RFC, in order to correctly hash a password for use with Digest authentication you should use the special password hashing function on DigestAuthenticate. If you are going to be combining digest authentication with any other authentication strategies, its also recommended that you store the digest password in a separate column, from the normal password hash:

class User extends AppModel { public function beforeSave($options = array()) { // make a password for digest auth. $this->data[User][digest_hash] = DigestAuthenticate::password( $this->data[User][username], $this->data[User][password], env(SERVER_N ); return true; } }

Passwords for digest authentication need a bit more information than other password hashes, based on the RFC for digest authentication. 88 Chapter 4. Controllers

CakePHP Cookbook Documentation, Release 2.x

Note: The third parameter of DigestAuthenticate::password() must match the realm cong value dened when DigestAuthentication was congured in AuthComponent::$authenticate. This defaults to env(SCRIPT_NAME). You may wish to use a static string if you want consistent hashes in multiple environments.

Creating custom password hasher classes Custom password hasher classes need to extend the AbstractPasswordHasher class and need to implement the abstract methods hash() and check(). In app/Controller/Component/Auth/CustomPasswordHasher.php you could put the following:
App::uses(CustomPasswordHasher, Controller/Component/Auth); class CustomPasswordHasher extends AbstractPasswordHasher { public function hash($password) { // stuff here } public function check($password, $hashedPassword) { // stuff here } }

Manually logging users in Sometimes the need arises where you need to manually log a user in, such as just after they registered for your application. You can do this by calling $this->Auth->login() with the user data you want to login:

public function register() { if ($this->User->save($this->request->data)) { $id = $this->User->id; $this->request->data[User] = array_merge($this->request->data[User], array(id $this->Auth->login($this->request->data[User]); return $this->redirect(/users/home); } }

Warning: Be sure to manually add the new User id to the array passed to the login method. Otherwise you wont have the user id available.

Accessing the logged in user Once a user is logged in, you will often need some particular information about the current user. You can access the currently logged in user using AuthComponent::user(). This method is static, and can be used globally after the AuthComponent has been loaded. You can access it both as an instance method or as a static method:
// Use anywhere AuthComponent::user(id)

More on controllers

CakePHP Cookbook Documentation, Release 2.x

// From inside a controller $this->Auth->user(id);

Logging users out Eventually youll want a quick way to de-authenticate someone, and redirect them to where they need to go. This method is also useful if you want to provide a Log me out link inside a members area of your application:
public function logout() { return $this->redirect($this->Auth->logout()); }

Logging out users that logged in with Digest or Basic auth is difcult to accomplish for all clients. Most browsers will retain credentials for the duration they are still open. Some clients can be forced to logout by sending a 401 status code. Changing the authentication realm is another solution that works for some clients.
Authorization

Authorization is the process of ensuring that an identied/authenticated user is allowed to access the resources they are requesting. If enabled AuthComponent can automatically check authorization handlers and ensure that logged in users are allowed to access the resources they are requesting. There are several built-in authorization handlers, and you can create custom ones for your application, or as part of a plugin. ActionsAuthorize Uses the AclComponent to check for permissions on an action level. CrudAuthorize Uses the AclComponent and action -> CRUD mappings to check permissions for resources. ControllerAuthorize Calls isAuthorized() on the active controller, and uses the return of that to authorize a user. This is often the most simple way to authorize users. Conguring Authorization handlers You congure authorization handlers using $this->Auth->authorize. You can congure one or many handlers for authorization. Using multiple handlers allows you to support different ways of checking authorization. When authorization handlers are checked, they will be called in the order they are declared. Handlers should return false, if they are unable to check authorization, or the check has failed. Handlers should return true if they were able to check authorization successfully. Handlers will be called in sequence until one passes. If all checks fail, the user will be redirected to the page they came from. Additionally you can halt all authorization by throwing an exception. You will need to catch any thrown exceptions, and handle them. You can congure authorization handlers in your controllers beforeFilter or, in the $components array. You can pass conguration information into each authorization object, using an array:
// Basic setup $this->Auth->authorize = array(Controller); // Pass settings in $this->Auth->authorize = array( Actions => array(actionPath => controllers/),

Chapter 4. Controllers

CakePHP Cookbook Documentation, Release 2.x

Controller );

Much like Auth->authenticate, Auth->authorize, helps you keep your code DRY, by using the all key. This special key allows you to set settings that are passed to every attached object. The all key is also exposed as AuthComponent::ALL:
// Pass settings in using all $this->Auth->authorize = array( AuthComponent::ALL => array(actionPath => controllers/), Actions, Controller );

In the above example, both the Actions and Controller will get the settings dened for the all key. Any settings passed to a specic authorization object will override the matching key in the all key. The core authorize objects support the following conguration keys. actionPath Used by ActionsAuthorize to locate controller action ACOs in the ACO tree. actionMap Action -> CRUD mappings. Used by CrudAuthorize and authorization objects that want to map actions to CRUD roles. userModel The name of the ARO/Model node user information can be found under. Used with ActionsAuthorize. Creating Custom Authorize objects Because authorize objects are pluggable, you can create custom authorize objects in your application or plugins. If for example you wanted to create an LDAP authorize object. In app/Controller/Component/Auth/LdapAuthorize.php you could put the following:
App::uses(BaseAuthorize, Controller/Component/Auth); class LdapAuthorize extends BaseAuthorize { public function authorize($user, CakeRequest $request) { // Do things for ldap here. } }

Authorize objects should return false if the user is denied access, or if the object is unable to perform a check. If the object is able to verify the users access, true should be returned. Its not required that you extend BaseAuthorize, only that your authorize object implements an authorize() method. The BaseAuthorize class provides a number of helpful methods that are commonly used. Using custom authorize objects Once youve created your custom authorize object, you can use them by including them in your AuthComponents authorize array:
$this->Auth->authorize = array( Ldap, // app authorize object. AuthBag.Combo, // plugin authorize object. );

More on controllers

CakePHP Cookbook Documentation, Release 2.x

Using no authorization If youd like to not use any of the built-in authorization objects, and want to handle things entirely outside of AuthComponent you can set $this->Auth->authorize = false;. By default AuthComponent starts off with authorize = false. If you dont use an authorization scheme, make sure to check authorization yourself in your controllers beforeFilter, or with another component. Making actions public There are often times controller actions that you wish to remain entirely public, or that dont require users to be logged in. AuthComponent is pessimistic, and defaults to denying access. You can mark actions as public actions by using AuthComponent::allow(). By marking actions as public, AuthComponent, will not check for a logged in user, nor will authorize objects be checked:
// Allow all actions. CakePHP 2.0 $this->Auth->allow(*); // Allow all actions. CakePHP 2.1 $this->Auth->allow(); // Allow only the view and index actions. $this->Auth->allow(view, index); // Allow only the view and index actions. $this->Auth->allow(array(view, index));

Warning: If youre using scaffolding, allow all will not identify and allow the scaffolded methods. You have to specify their action names. You can provide as many action names as you need to allow(). You can also supply an array containing all the action names. Making actions require authorization By default all actions require authorization. However, after making actions public, you want to revoke the public access. You can do so using AuthComponent::deny():
// remove one action $this->Auth->deny(add); // remove all the actions. $this->Auth->deny(); // remove a group of actions. $this->Auth->deny(add, edit); $this->Auth->deny(array(add, edit));

You can provide as many action names as you need to deny(). You can also supply an array containing all the action names. Using ControllerAuthorize ControllerAuthorize allows you to handle authorization checks in a controller callback. This is ideal when you have very simple authorization, or you need to use a combination of models + components to do your authorization, and dont want to create a custom authorize object. 92 Chapter 4. Controllers

CakePHP Cookbook Documentation, Release 2.x

The callback is always called isAuthorized() and it should return a boolean as to whether or not the user is allowed to access resources in the request. The callback is passed the active user, so it can be checked:
class AppController extends Controller { public $components = array( Auth => array(authorize => Controller), ); public function isAuthorized($user = null) { // Any registered user can access public functions if (empty($this->request->params[admin])) { return true; } // Only admins can access admin functions if (isset($this->request->params[admin])) { return (bool)($user[role] === admin); } // Default deny return false; } }

The above callback would provide a very simple authorization system where, only users with role = admin could access actions that were in the admin prex. Using ActionsAuthorize ActionsAuthorize integrates with the AclComponent, and provides a ne grained per action ACL check on each request. ActionsAuthorize is often paired with DbAcl to give dynamic and exible permission systems that can be edited by admin users through the application. It can however, be combined with other Acl implementations such as IniAcl and custom application Acl backends. Using CrudAuthorize CrudAuthorize integrates with AclComponent, and provides the ability to map requests to CRUD operations. Provides the ability to authorize using CRUD mappings. These mapped results are then checked in the AclComponent as specic permissions. For example, taking /posts/index as the current request. The default mapping for index, is a read permission check. The Acl check would then be for the posts controller with the read permission. This allows you to create permission systems that focus more on what is being done to resources, rather than the specic actions being visited. Mapping actions when using CrudAuthorize When using CrudAuthorize or any other authorize objects that use action mappings, it might be necessary to map additional methods. You can map actions -> CRUD permissions using mapAction(). Calling this on AuthComponent will delegate to all the of the congured authorize objects, so you can be sure the settings were applied every where:
$this->Auth->mapActions(array( create => array(register), view => array(show, display) ));

More on controllers

CakePHP Cookbook Documentation, Release 2.x

The keys for mapActions should be the CRUD permissions you want to set, while the values should be an array of all the actions that are mapped to the CRUD permission.
AuthComponent API

AuthComponent is the primary interface to the built-in authorization and authentication mechanics in CakePHP. property AuthComponent::$ajaxLogin The name of an optional view element to render when an Ajax request is made with an invalid or expired session. property AuthComponent::$allowedActions Controller actions for which user validation is not required. property AuthComponent::$authenticate Set to an array of Authentication objects you want to use when logging users in. There are several core authentication objects, see the section on Authentication. property AuthComponent::$authError Error to display when user attempts to access an object or action to which they do not have access. Changed in version 2.4: You can suppress authError message from being displayed by setting this value to boolean false. property AuthComponent::$authorize Set to an array of Authorization objects you want to use when authorizing users on each request, see the section on Authorization. property AuthComponent::$components Other components utilized by AuthComponent property AuthComponent::$flash Settings to use when Auth needs to do a ash message with SessionComponent::setFlash(). Available keys are: element - The element to use, defaults to default. key - The key to use, defaults to auth params - The array of additional params to use, defaults to array() property AuthComponent::$loginAction A URL (dened as a string or array) to the controller action that handles logins. Defaults to /users/login property AuthComponent::$loginRedirect The URL (dened as a string or array) to the controller action users should be redirected to after logging in. This value will be ignored if the user has an Auth.redirect value in their session. property AuthComponent::$logoutRedirect The default action to redirect to after the user is logged out. While AuthComponent does not handle post-logout redirection, a redirect URL will be returned from AuthComponent::logout(). Defaults to AuthComponent::$loginAction.

Chapter 4. Controllers

CakePHP Cookbook Documentation, Release 2.x

property AuthComponent::$unauthorizedRedirect Controls handling of unauthorized access. By default unauthorized user is redirected to the referrer url or AuthComponent::$loginAction or /. If set to false a ForbiddenException exception is thrown instead of redirecting. property AuthComponent::$request Request object property AuthComponent::$response Response object property AuthComponent::$sessionKey The session key name where the record of the current user is stored. If unspecied, it will be Auth.User. AuthComponent::allow($action[, $action, ... ]) Set one or more actions as public actions, this means that no authorization checks will be performed for the specied actions. The special value of * will mark all the current controllers actions as public. Best used in your controllers beforeFilter method. AuthComponent::constructAuthenticate() Loads the congured authentication objects. AuthComponent::constructAuthorize() Loads the authorization objects congured. AuthComponent::deny($action[, $action, ... ]) Toggle one more more actions previously declared as public actions, as non-public methods. These methods will now require authorization. Best used inside your controllers beforeFilter method. AuthComponent::flash($message) Set a ash message. Uses the Session component, and values from AuthComponent::$flash. AuthComponent::identify($request, $response) Parameters $request (CakeRequest) The request to use. $response (CakeResponse) The response to use, headers can be sent if authentication fails. This method is used by AuthComponent to identify a user based on the information contained in the current request. AuthComponent::initialize($Controller) Initializes AuthComponent for use in the controller. AuthComponent::isAuthorized($user = null, $request = null) Uses the congured Authorization adapters to check whether or not a user is authorized. Each adapter will be checked in sequence, if any of them return true, then the user will be authorized for the request. AuthComponent::loggedIn() Returns true if the current client is a logged in user, or false if they are not. AuthComponent::login($user) More on controllers 95

CakePHP Cookbook Documentation, Release 2.x

Parameters $user (array) Array of logged in user data. Takes an array of user data to login with. Allows for manual logging of users. Calling user() will populate the session value with the provided information. If no user is provided, AuthComponent will try to identify a user using the current request information. See AuthComponent::identify() AuthComponent::logout() Returns A string url to redirect the logged out user to. Logs out the current user. AuthComponent::mapActions($map = array()) Maps action names to CRUD operations. Used for controller-based authentication. Make sure to congure the authorize property before calling this method. As it delegates $map to all the attached authorize objects. static AuthComponent::password($pass) Deprecated since version 2.4. AuthComponent::redirect($url = null) Deprecated since version 2.3. AuthComponent::redirectUrl($url = null) If no parameter is passed, gets the authentication redirect URL. Pass a url in to set the destination a user should be redirected to upon logging in. Will fallback to AuthComponent::$loginRedirect if there is no stored redirect value. New in version 2.3. AuthComponent::shutdown($Controller) Component shutdown. If user is logged in, wipe out redirect. AuthComponent::startup($Controller) Main execution method. Handles redirecting of invalid users, and processing of login form data. static AuthComponent::user($key = null) Parameters $key (string) The user data key you want to fetch. If null, all user data will be returned. Can also be called as an instance method. Get data concerning the currently logged in user, you can use a property key to fetch specic data about the user:
$id = $this->Auth->user(id);

If the current user is not logged in or the key doesnt exist, null will be returned. Security class SecurityComponent(ComponentCollection $collection, array $settings = array()) 96 Chapter 4. Controllers

CakePHP Cookbook Documentation, Release 2.x

The Security Component creates an easy way to integrate tighter security in your application. It provides methods for various tasks like: Restricting which HTTP methods your application accepts. CSRF protection. Form tampering protection Requiring that SSL be used. Limiting cross controller communication. Like all components it is congured through several congurable parameters. All of these properties can be set directly or through setter methods of the same name in your controllers beforeFilter. By using the Security Component you automatically get CSRF (http://en.wikipedia.org/wiki/Crosssite_request_forgery) and form tampering protection. Hidden token elds will automatically be inserted into forms and checked by the Security component. Among other things, a form submission will not be accepted after a certain period of inactivity, which is controlled by the csrfExpires time. If you are using Security components form protection features and other components that process form data in their startup() callbacks, be sure to place Security Component before those components in your $components array. Note: When using the Security Component you must use the FormHelper to create your forms. In addition, you must not override any of the elds name attributes. The Security Component looks for certain indicators that are created and managed by the FormHelper (especially those created in create() and end()). Dynamically altering the elds that are submitted in a POST request (e.g. disabling, deleting or creating new elds via JavaScript) is likely to trigger a black-holing of the request. See the $validatePost or $disabledFields conguration parameters.

Handling blackhole callbacks

If an action is restricted by the Security Component it is black-holed as an invalid request which will result in a 400 error by default. You can congure this behavior by setting the $this->Security->blackHoleCallback property to a callback function in the controller. SecurityComponent::blackHole(object $controller, string $error) Black-hole an invalid request with a 400 error or a custom callback. With no callback, the request will be exited. If a controller callback is set to SecurityComponent::blackHoleCallback, it will be called and passed any error information. property SecurityComponent::$blackHoleCallback A Controller callback that will handle and requests that are blackholed. A blackhole callback can be any public method on a controllers. The callback should expect an parameter indicating the type of error:
public function beforeFilter() { $this->Security->blackHoleCallback = blackhole; }

More on controllers

CakePHP Cookbook Documentation, Release 2.x

public function blackhole($type) { // handle errors. }

The $type parameter can have the following values: auth Indicates a form validation error, or a controller/action mismatch error. csrf Indicates a CSRF error. get Indicates an HTTP method restriction failure. post Indicates an HTTP method restriction failure. put Indicates an HTTP method restriction failure. delete Indicates an HTTP method restriction failure. secure Indicates an SSL method restriction failure.
Restricting HTTP methods

SecurityComponent::requirePost() Sets the actions that require a POST request. Takes any number of arguments. Can be called with no arguments to force all actions to require a POST. SecurityComponent::requireGet() Sets the actions that require a GET request. Takes any number of arguments. Can be called with no arguments to force all actions to require a GET. SecurityComponent::requirePut() Sets the actions that require a PUT request. Takes any number of arguments. Can be called with no arguments to force all actions to require a PUT. SecurityComponent::requireDelete() Sets the actions that require a DELETE request. Takes any number of arguments. Can be called with no arguments to force all actions to require a DELETE.
Restrict actions to SSL

SecurityComponent::requireSecure() Sets the actions that require a SSL-secured request. Takes any number of arguments. Can be called with no arguments to force all actions to require a SSL-secured. SecurityComponent::requireAuth() Sets the actions that require a valid Security Component generated token. Takes any number of arguments. Can be called with no arguments to force all actions to require a valid authentication.

Chapter 4. Controllers

CakePHP Cookbook Documentation, Release 2.x

Restricting cross controller communication

property SecurityComponent::$allowedControllers A List of Controller from which the actions of the current controller are allowed to receive requests from. This can be used to control cross controller requests. property SecurityComponent::$allowedActions Actions from which actions of the current controller are allowed to receive requests. This can be used to control cross controller requests.
Form tampering prevention

By default SecurityComponent prevents users from tampering with forms. It does this by working with FormHelper and tracking which les are in a form. It also keeps track of the values of hidden input elements. All of this data is combined and turned into a hash. When a form is submitted, SecurityComponent will use the POST data to build the same structure and compare the hash. property SecurityComponent::$unlockedFields Set to a list of form elds to exclude from POST validation. Fields can be unlocked either in the Component, or with FormHelper::unlockField(). Fields that have been unlocked are not required to be part of the POST and hidden unlocked elds do not have their values checked. property SecurityComponent::$validatePost Set to false to completely skip the validation of POST requests, essentially turning off form validation.
CSRF conguration

property SecurityComponent::$csrfCheck Whether to use CSRF protected forms. Set to false to disable CSRF protection on forms. property SecurityComponent::$csrfExpires The duration from when a CSRF token is created that it will expire on. Each form/page request will generate a new token that can only be submitted once unless it expires. Can be any value compatible with strtotime(). The default is +30 minutes. property SecurityComponent::$csrfUseOnce Controls whether or not CSRF tokens are use and burn. Set to false to not generate new tokens on each request. One token will be reused until it expires. This reduces the chances of users getting invalid requests because of token consumption. It has the side effect of making CSRF less secure, as tokens are reusable.
Usage

Using the security component is generally done in the controller beforeFilter(). You would specify the security restrictions you want and the Security Component will enforce them on its startup:

More on controllers

CakePHP Cookbook Documentation, Release 2.x

class WidgetController extends AppController { public $components = array(Security); public function beforeFilter() { $this->Security->requirePost(delete); } }

In this example the delete action can only be successfully triggered if it receives a POST request:
class WidgetController extends AppController { public $components = array(Security); public function beforeFilter() { if (isset($this->request->params[admin])) { $this->Security->requireSecure(); } } }

This example would force all actions that had admin routing to require secure SSL requests:
class WidgetController extends AppController { public $components = array(Security); public function beforeFilter() { if (isset($this->params[admin])) { $this->Security->blackHoleCallback = forceSSL; $this->Security->requireSecure(); } } public function forceSSL() { return $this->redirect(https:// . env(SERVER_NAME) . $this->here); } }

This example would force all actions that had admin routing to require secure SSL requests. When the request is black holed, it will call the nominated forceSSL() callback which will redirect non-secure requests to secure requests automatically.
CSRF protection

CSRF or Cross Site Request Forgery is a common vulnerability in web applications. It allows an attacker to capture and replay a previous request, and sometimes submit data requests using image tags or resources on other domains. Double submission and replay attacks are handled by the SecurityComponents CSRF features. They work by adding a special token to each form request. This token once used cannot be used again. If an attempt is 100 Chapter 4. Controllers

CakePHP Cookbook Documentation, Release 2.x

made to re-use an expired token the request will be blackholed. Using CSRF protection Simply by adding the SecurityComponent to your components array, you can benet from the CSRF protection it provides. By default CSRF tokens are valid for 30 minutes and expire on use. You can control how long tokens last by setting csrfExpires on the component.:
public $components = array( Security => array( csrfExpires => +1 hour ) );

You can also set this property in your controllers beforeFilter:

public function beforeFilter() { $this->Security->csrfExpires = +1 hour; // ... }

The csrfExpires property can be any value that is compatible with strtotime() (http://php.net/manual/en/function.strtotime.php). By default the FormHelper will add a data[_Token][key] containing the CSRF token to every form when the component is enabled. Handling missing or expired tokens Missing or expired tokens are handled similar to other security violations. The SecurityComponents blackHoleCallback will be called with a csrf parameter. This helps you lter out CSRF token failures, from other warnings. Using per-session tokens instead of one-time use tokens By default a new CSRF token is generated for each request, and each token can only be used once. If a token is used twice, it will be blackholed. Sometimes, this behaviour is not desirable, as it can create issues with single page applications. You can toggle on longer, multi-use tokens by setting csrfUseOnce to false. This can be done in the components array, or in the beforeFilter of your controller:
public $components = array( Security => array( csrfUseOnce => false ) );

This will tell the component that you want to re-use a CSRF token until it expires - which is controlled by the csrfExpires value. If you are having issues with expired tokens, this is a good balance between security and ease of use. Disabling the CSRF protection There may be cases where you want to disable CSRF protection on your forms for some reason. If you do want to disable this feature, you can set $this->Security->csrfCheck = false; in your beforeFilter or use the components array. By default CSRF protection is enabled, and congured to use one-use tokens.

More on controllers

101

CakePHP Cookbook Documentation, Release 2.x

Disabling Security Component For Specic Actions

There may be cases where you want to disable all security checks for an action (ex. ajax request). You may unlock these actions by listing them in $this->Security->unlockedActions in your beforeFilter. New in version 2.3. Request Handling class RequestHandlerComponent(ComponentCollection $collection, array $settings = array()) The Request Handler component is used in CakePHP to obtain additional information about the HTTP requests that are made to your applications. You can use it to inform your controllers about Ajax as well as gain additional insight into content types that the client accepts and automatically changes to the appropriate layout when le extensions are enabled. By default RequestHandler will automatically detect Ajax requests based on the HTTP-XRequested-With header that many javascript libraries use. When used in conjunction with Router::parseExtensions() RequestHandler will automatically switch the layout and view les to those that match the requested type. Furthermore, if a helper with the same name as the requested extension exists, it will be added to the Controllers Helper array. Lastly, if XML/JSON data is POSTed to your Controllers, it will be parsed into an array which is assigned to $this->request->data, and can then be saved as model data. In order to make use of RequestHandler it must be included in your $components array:
class WidgetController extends AppController { public $components = array(RequestHandler); // Rest of controller }

Obtaining Request Information

Request Handler has several methods that provide information about the client and its request. RequestHandlerComponent::accepts($type = null) $type can be a string, or an array, or null. If a string, accepts will return true if the client accepts the content type. If an array is specied, accepts return true if any one of the content types is accepted by the client. If null returns an array of the content-types that the client accepts. For example:
class PostsController extends AppController { public $components = array(RequestHandler); public function beforeFilter() { if ($this->RequestHandler->accepts(html)) { // Execute code only if client accepts an HTML (text/html) response } elseif ($this->RequestHandler->accepts(xml)) {

102

Chapter 4. Controllers

CakePHP Cookbook Documentation, Release 2.x

// Execute XML-only code } if ($this->RequestHandler->accepts(array(xml, rss, atom))) { // Executes if the client accepts any of the above: XML, RSS or Atom } } }

Other request type detection methods include: RequestHandlerComponent::isXml() Returns true if the current request accepts XML as a response. RequestHandlerComponent::isRss() Returns true if the current request accepts RSS as a response. RequestHandlerComponent::isAtom() Returns true if the current call accepts an Atom response, false otherwise. RequestHandlerComponent::isMobile() Returns true if user agent string matches a mobile web browser, or if the client accepts WAP content. The supported Mobile User Agent strings are: Android AvantGo BlackBerry DoCoMo Fennec iPad iPhone iPod J2ME MIDP NetFront Nokia Opera Mini Opera Mobi PalmOS PalmSource portalmmm Plucker ReqwirelessWeb More on controllers 103

CakePHP Cookbook Documentation, Release 2.x

SonyEricsson Symbian UP.Browser webOS Windows CE Windows Phone OS Xiino RequestHandlerComponent::isWap() Returns true if the client accepts WAP content. All of the above request detection methods can be used in a similar fashion to lter functionality intended for specic content types. For example when responding to Ajax requests, you often will want to disable browser caching, and change the debug level. However, you want to allow caching for non-ajax requests. The following would accomplish that:
if ($this->request->is(ajax)) { $this->disableCache(); } // Continue Controller action

Obtaining Additional Client Information

RequestHandlerComponent::getAjaxVersion() Gets Prototype version if call is Ajax, otherwise empty string. The Prototype library sets a special Prototype version HTTP header.
Automatically decoding request data

RequestHandlerComponent::addInputType($type, $handler) Parameters $type (string) The content type alias this attached decoder is for. e.g. json or xml $handler (array) The handler information for the type. Add a request data decoder. The handler should contain a callback, and any additional arguments for the callback. The callback should return an array of data contained in the request input. For example adding a CSV handler in your controllers beforeFilter could look like:
$parser = function ($data) { $rows = str_getcsv($data, "\n"); foreach ($rows as &$row) { $row = str_getcsv($row, ,); }

104

Chapter 4. Controllers

CakePHP Cookbook Documentation, Release 2.x

return $rows; }; $this->RequestHandler->addInputType(csv, array($parser));

The above example requires PHP 5.3, however you can use any callable (http://php.net/callback) for the handling function. You can also pass additional arguments to the callback, this is useful for callbacks like json_decode:
$this->RequestHandler->addInputType(json, array(json_decode, true));

The above will make $this->request->data an array of the JSON input data, without the additional true youd get a set of StdClass objects.
Responding To Requests

In addition to request detection RequestHandler also provides easy access to altering the output and content type mappings for your application. RequestHandlerComponent::setContent($name, $type = null) Parameters $name (string) The name or le extension of the Content-type ie. html, css, json, xml. $type (mixed) The mime-type(s) that the Content-type maps to. setContent adds/sets the Content-types for the given name. Allows content-types to be mapped to friendly aliases and or extensions. This allows RequestHandler to automatically respond to requests of each type in its startup method. If you are using Router::parseExtension, you should use the le extension as the name of the Content-type. Furthermore, these content types are used by prefers() and accepts(). setContent is best used in the beforeFilter() of your controllers, as this will best leverage the automagicness of content-type aliases. The default mappings are: javascript text/javascript js text/javascript json application/json css text/css html text/html, */* text text/plain txt text/plain csv application/vnd.ms-excel, text/plain form application/x-www-form-urlencoded

More on controllers

105

CakePHP Cookbook Documentation, Release 2.x

le multipart/form-data xhtml application/xhtml+xml, application/xhtml, text/xhtml xhtml-mobile application/vnd.wap.xhtml+xml xml application/xml, text/xml rss application/rss+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 pdf application/pdf zip application/x-zip tar application/x-tar RequestHandlerComponent::prefers($type = null) Determines which content-types the client prefers. If no parameter is given the most likely content type is returned. If $type is an array the rst type the client accepts will be returned. Preference is determined primarily by the le extension parsed by Router if one has been provided, and secondly by the list of content-types in HTTP_ACCEPT. RequestHandlerComponent::renderAs($controller, $type) Parameters $controller (Controller) Controller Reference $type (string) friendly content type name to render content for ex. xml, rss. Change the render mode of a controller to the specied type. Will also append the appropriate helper to the controllers helper array if available and not already in the array. RequestHandlerComponent::respondAs($type, $options) Parameters $type (string) Friendly content type name ex. xml, rss or a full content type like application/x-shockwave $options (array) If $type is a friendly type name that has more than one content association, $index is used to select the content type. Sets the response header based on content-type map names. RequestHandlerComponent::responseType() Returns the current response type Content-type header or null if one has yet to be set.

106

Chapter 4. Controllers

CakePHP Cookbook Documentation, Release 2.x

Taking advantage of HTTP cache validation

New in version 2.1. The HTTP cache validation model is one of the processes used for cache gateways, also known as reverse proxies, to determine if they can serve a stored copy of a response to the client. Under this model, you mostly save bandwidth, but when used correctly you can also save some CPU processing, reducing this way response times. Enabling the RequestHandlerComponent in your controller automatically activates a check done before rendering the view. This check compares the response object against the original request to determine whether the response was not modied since the last time the client asked for it. If response is evaluated as not modied, then the view rendering process is stopped, saving processing time an no content is returned to the client, saving bandwidth. The response status code is then set to 304 Not Modied. You can opt-out this automatic checking by setting the checkHttpCache setting to false:
public $components = array( RequestHandler => array( checkHttpCache => false ));

Using custom ViewClasses

New in version 2.3. When using JsonView/XmlView you might want to override the default serialization with a custom View class, or add View classes for other types. You can map existing and new types to your custom classes. RequestHandlerComponent::viewClassMap($type, $viewClass) Parameters $type (string|array) The type string or map array with format array(json => MyJson) $viewClass (string) The viewClass to be used for the type without View appended You can also set this automatically by using the viewClassMap setting:
public $components = array( RequestHandler => array( viewClassMap => array( json => ApiKit.MyJson, xml => ApiKit.MyXml, csv => ApiKit.Csv ) ));

More on controllers

107

CakePHP Cookbook Documentation, Release 2.x

Cookie class CookieComponent(ComponentCollection $collection, array $settings = array()) The CookieComponent is a wrapper around the native PHP setcookie method. It also includes a host of delicious icing to make coding cookies in your controllers very convenient. Before attempting to use the CookieComponent, you must make sure that Cookie is listed in your controllers $components array.
Controller Setup

There are a number of controller variables that allow you to congure the way cookies are created and managed. Dening these special variables in the beforeFilter() method of your controller allows you to dene how the CookieComponent works. Cookie variable string $name string $key dedescription fault Cake- The name of the cookie. Cookie null This string is used to encrypt the value written to the cookie. This string should be random and difcult to guess. When using rijndael encryption this value must be longer than 32 bytes. string The domain name allowed to access the cookie. e.g. Use .yourdomain.com to $domain allow access from all your subdomains. int or 5 The time when your cookie will expire. Integers are Interpreted as seconds and a string Days value of 0 is equivalent to a session cookie: i.e. the cookie expires when the $time browser is closed. If a string is set, this will be interpreted with PHP function strtotime(). You can set this directly within the write() method. string / The server path on which the cookie will be applied. If $path is set to /foo/, the $path cookie will only be available within the /foo/ directory and all sub-directories such as /foo/bar/ of your domain. The default value is the entire domain. You can set this directly within the write() method. boolean false Indicates that the cookie should only be transmitted over a secure HTTPS $secure connection. When set to true, the cookie will only be set if a secure connection exists. You can set this directly within the write() method. boolean false Set to true to make HTTP only cookies. Cookies that are HTTP only are not $httpOnly accessible in Javascript. The following snippet of controller code shows how to include the CookieComponent and set up the controller variables needed to write a cookie named baker_id for the domain example.com which needs a secure connection, is available on the path /bakers/preferences/, expires in one hour and is HTTP only:
public $components = array(Cookie); public function beforeFilter() { parent::beforeFilter(); $this->Cookie->name = baker_id; $this->Cookie->time = 3600; // or 1 hour $this->Cookie->path = /bakers/preferences/; $this->Cookie->domain = example.com; $this->Cookie->secure = true; // i.e. only sent if using secure HTTPS

108

Chapter 4. Controllers

CakePHP Cookbook Documentation, Release 2.x

$this->Cookie->key = qSI232qs&sXOw!adre@34SAv!@(XSL#$%)asGb$@11~_+!@#HKis~#^; $this->Cookie->httpOnly = true; }

Next, lets look at how to use the different methods of the Cookie Component.
Using the Component

The CookieComponent offers a number of methods for working with Cookies. CookieComponent::write(mixed $key, mixed $value = null, boolean $encrypt = true, mixed $expires = null) The write() method is the heart of cookie component, $key is the cookie variable name you want, and the $value is the information to be stored:
$this->Cookie->write(name, Larry);

You can also group your variables by supplying dot notation in the key parameter:
$this->Cookie->write(User.name, Larry); $this->Cookie->write(User.role, Lead);

If you want to write more than one value to the cookie at a time, you can pass an array:
$this->Cookie->write(User, array(name => Larry, role => Lead) );

All values in the cookie are encrypted by default. If you want to store the values as plain-text, set the third parameter of the write() method to false. The encryption performed on cookie values is fairly uncomplicated encryption system. It uses Security.salt and a predened Congure class var Security.cipherSeed to encrypt values. To make your cookies more secure you should change Security.cipherSeed in app/Cong/core.php to ensure a better encryption.:
$this->Cookie->write(name, Larry, false);

The last parameter to write is $expires the number of seconds before your cookie will expire. For convenience, this parameter can also be passed as a string that the php strtotime() function understands:
// Both cookies expire in one hour. $this->Cookie->write(first_name, Larry, false, 3600); $this->Cookie->write(last_name, Masters, false, 1 hour);

CookieComponent::read(mixed $key = null) This method is used to read the value of a cookie variable with the name specied by $key.:
// Outputs Larry echo $this->Cookie->read(name); // You can also use the dot notation for read echo $this->Cookie->read(User.name);

More on controllers

109

CakePHP Cookbook Documentation, Release 2.x

// To get the variables which you had grouped // using the dot notation as an array use something like $this->Cookie->read(User); // this outputs something like array(name => Larry, role => Lead)

CookieComponent::check($key) Parameters $key (string) The key to check. Used to check if a key/path exists and has not-null value. CookieComponent::check() was added in 2.3 CookieComponent::delete(mixed $key) Deletes a cookie variable of the name in $key. Works with dot notation:
// Delete a variable $this->Cookie->delete(bar); // Delete the cookie variable bar, but not all under foo $this->Cookie->delete(foo.bar);

New in version 2.3:

CookieComponent::destroy() Destroys the current cookie. CookieComponent::type($type) Allows you to change the encryption scheme. By default the cipher scheme is used. However, you should use the rijndael scheme for improved security. Changed in version 2.2: The rijndael type was added. Access Control Lists class AclComponent(ComponentCollection $collection, array $settings = array()) CakePHPs access control list functionality is one of the most oft-discussed, most likely because it is the most sought after, but also because it can be the most confusing. If youre looking for a good way to get started with ACLs in general, read on. Be brave and stick with it, even if the going gets rough. Once you get the hang of it, its an extremely powerful tool to have on hand when developing your application.
Understanding How ACL Works

Powerful things require access control. Access control lists are a way to manage application permissions in a ne-grained, yet easily maintainable and manageable way. Access control lists, or ACL, handle two main things: things that want stuff, and things that are wanted. In ACL lingo, things (most often users) that want to use stuff are called access request objects, or AROs. Things in the system that are wanted (most often actions or data) are called access control objects, or ACOs. The

110

Chapter 4. Controllers

CakePHP Cookbook Documentation, Release 2.x

entities are called objects because sometimes the requesting object isnt a person - sometimes you might want to limit the access certain Cake controllers have to initiate logic in other parts of your application. ACOs could be anything you want to control, from a controller action, to a web service, to a line on your grandmas online diary. To review: ACO - Access Control Object - Something that is wanted ARO - Access Request Object - Something that wants something Essentially, ACL is what is used to decide when an ARO can have access to an ACO. In order to help you understand how everything works together, lets use a semi-practical example. Imagine, for a moment, a computer system used by a familiar group of fantasy novel adventurers from the Lord of the Rings. The leader of the group, Gandalf, wants to manage the partys assets while maintaining a healthy amount of privacy and security for the other members of the party. The rst thing he needs to do is create a list of the AROs involved: Gandalf Aragorn Bilbo Frodo Gollum Legolas Gimli Pippin Merry Note: Realize that ACL is not the same as authentication. ACL is what happens after a user has been authenticated. Although the two are usually used in concert, its important to realize the difference between knowing who someone is (authentication) and knowing what they can do (ACL). The next thing Gandalf needs to do is make an initial list of things, or ACOs, the system will handle. His list might look something like: Weapons The One Ring Salted Pork Diplomacy Ale Traditionally, systems were managed using a sort of matrix, that showed a basic set of users and permissions relating to objects. If this information were stored in a table, it might look like the following table:

More on controllers

111

CakePHP Cookbook Documentation, Release 2.x

x Gandalf Aragorn Bilbo Frodo Gollum Legolas Gimli Pippin Merry

Weapons Allow

The Ring

Salted Pork Allow Allow

Diplomacy Allow Allow

Allow Allow Allow Allow Allow Allow Allow Allow Allow

Ale Allow Allow Allow Allow Allow Allow Allow

At rst glance, it seems that this sort of system could work rather well. Assignments can be made to protect security (only Frodo can access the ring) and protect against accidents (keeping the hobbits out of the salted pork and weapons). It seems ne grained enough, and easy enough to read, right? For a small system like this, maybe a matrix setup would work. But for a growing system, or a system with a large amount of resources (ACOs) and users (AROs), a table can become unwieldy rather quickly. Imagine trying to control access to the hundreds of war encampments and trying to manage them by unit. Another drawback to matrices is that you cant really logically group sections of users or make cascading permissions changes to groups of users based on those logical groupings. For example, it would sure be nice to automatically allow the hobbits access to the ale and pork once the battle is over: Doing it on an individual user basis would be tedious and error prone. Making a cascading permissions change to all hobbits would be easy. ACL is most usually implemented in a tree structure. There is usually a tree of AROs and a tree of ACOs. By organizing your objects in trees, permissions can still be dealt out in a granular fashion, while still maintaining a good grip on the big picture. Being the wise leader he is, Gandalf elects to use ACL in his new system, and organizes his objects along the following lines: Fellowship of the Ring Warriors * Aragorn * Legolas * Gimli Wizards * Gandalf Hobbits * Frodo * Bilbo * Merry * Pippin Visitors * Gollum 112 Chapter 4. Controllers

CakePHP Cookbook Documentation, Release 2.x

Using a tree structure for AROs allows Gandalf to dene permissions that apply to entire groups of users at once. So, using our ARO tree, Gandalf can tack on a few group-based permissions: Fellowship of the Ring (Deny: all) Warriors (Allow: Weapons, Ale, Elven Rations, Salted Pork) * Aragorn * Legolas * Gimli Wizards (Allow: Salted Pork, Diplomacy, Ale) * Gandalf Hobbits (Allow: Ale) * Frodo * Bilbo * Merry * Pippin Visitors (Allow: Salted Pork) * Gollum If we wanted to use ACL to see if the Pippin was allowed to access the ale, wed rst get his path in the tree, which is Fellowship->Hobbits->Pippin. Then we see the different permissions that reside at each of those points, and use the most specic permission relating to Pippin and the Ale. ARO Node Fellowship of the Ring Hobbits Pippin Permission Info Deny all Allow ale Result Denying access to ale. Allowing access to ale! Still allowing ale!

Note: Since the Pippin node in the ACL tree doesnt specically deny access to the ale ACO, the nal result is that we allow access to that ACO. The tree also allows us to make ner adjustments for more granular control - while still keeping the ability to make sweeping changes to groups of AROs: Fellowship of the Ring (Deny: all) Warriors (Allow: Weapons, Ale, Elven Rations, Salted Pork) * Aragorn (Allow: Diplomacy) * Legolas * Gimli Wizards (Allow: Salted Pork, Diplomacy, Ale) * Gandalf More on controllers 113

CakePHP Cookbook Documentation, Release 2.x

Hobbits (Allow: Ale) * Frodo (Allow: Ring) * Bilbo * Merry (Deny: Ale) * Pippin (Allow: Diplomacy) Visitors (Allow: Salted Pork) * Gollum This approach allows us both the ability to make wide-reaching permissions changes, but also ne-grained adjustments. This allows us to say that all hobbits can have access to ale, with one exceptionMerry. To see if Merry can access the Ale, wed nd his path in the tree: Fellowship->Hobbits->Merry and work our way down, keeping track of ale-related permissions: ARO Node Fellowship of the Ring Hobbits Merry Permission Info Deny all Allow ale Deny Ale Result Denying access to ale. Allowing access to ale! Denying ale.

Dening Permissions: Cakes INI-based ACL

Cakes rst ACL implementation was based on INI les stored in the Cake installation. While its useful and stable, we recommend that you use the database backed ACL solution, mostly because of its ability to create new ACOs and AROs on the y. We meant it for usage in simple applications - and especially for those folks who might not be using a database for some reason. By default, CakePHPs ACL is database-driven. To enable INI-based ACL, youll need to tell CakePHP what system youre using by updating the following lines in app/Cong/core.php
// Change these lines: Configure::write(Acl.classname, DbAcl); Configure::write(Acl.database, default); // To look like this: Configure::write(Acl.classname, IniAcl); //Configure::write(Acl.database, default);

ARO/ACO permissions are specied in /app/Cong/acl.ini.php. The basic idea is that AROs are specied in an INI section that has three properties: groups, allow, and deny. groups: names of ARO groups this ARO is a member of. allow: names of ACOs this ARO has access to deny: names of ACOs this ARO should be denied access to ACOs are specied in INI sections that only include the allow and deny properties. As an example, lets see how the Fellowship ARO structure weve been crafting would look like in INI syntax: 114 Chapter 4. Controllers

CakePHP Cookbook Documentation, Release 2.x

;------------------------------------; AROs ;------------------------------------[aragorn] groups = warriors allow = diplomacy [legolas] groups = warriors [gimli] groups = warriors [gandalf] groups = wizards [frodo] groups = hobbits allow = ring [bilbo] groups = hobbits [merry] groups = hobbits deny = ale [pippin] groups = hobbits [gollum] groups = visitors ;------------------------------------; ARO Groups ;------------------------------------[warriors] allow = weapons, ale, salted_pork [wizards] allow = salted_pork, diplomacy, ale [hobbits] allow = ale [visitors] allow = salted_pork

Now that youve got your permissions dened, you can skip along to the section on checking permissions using the ACL component.

More on controllers

115

CakePHP Cookbook Documentation, Release 2.x

Dening Permissions: Cakes Database ACL

Now that weve covered INI-based ACL permissions, lets move on to the (more commonly used) database ACL. Getting Started The default ACL permissions implementation is database powered. Cakes database ACL consists of a set of core models, and a console application that comes with your Cake installation. The models are used by Cake to interact with your database in order to store and retrieve nodes in tree format. The console application is used to initialize your database and interact with your ACO and ARO trees. To get started, rst youll need to make sure your /app/Config/database.php is present and correctly congured. See section 4.1 for more information on database conguration. Once youve done that, use the CakePHP console to create your ACL database tables:
$ cake schema create DbAcl

Running this command will drop and re-create the tables necessary to store ACO and ARO information in tree format. The output of the console application should look something like the following:
--------------------------------------------------------------Cake Schema Shell --------------------------------------------------------------The following tables will be dropped. acos aros aros_acos Are you sure you want to drop the tables? (y/n) [n] > y Dropping tables. acos updated. aros updated. aros_acos updated. The following tables will be created. acos aros aros_acos Are you sure you want to create the tables? (y/n) [y] > y Creating tables. acos updated. aros updated. aros_acos updated. End create.

Note: This replaces an older deprecated command, initdb.

116

Chapter 4. Controllers

CakePHP Cookbook Documentation, Release 2.x

You can also use the SQL le found in app/Config/Schema/db_acl.sql, but thats nowhere near as fun. When nished, you should have three new database tables in your system: acos, aros, and aros_acos (the join table to create permissions information between the two trees). Note: If youre curious about how Cake stores tree information in these tables, read up on modied database tree traversal. The ACL component uses CakePHPs Tree to manage the trees inheritances. The model class les for ACL can be found in lib/Cake/Model/. Now that were all set up, lets work on creating some ARO and ACO trees. Creating Access Request Objects (AROs) and Access Control Objects (ACOs) In creating new ACL objects (ACOs and AROs), realize that there are two main ways to name and access nodes. The rst method is to link an ACL object directly to a record in your database by specifying a model name and foreign key value. The second method can be used when an object has no direct relation to a record in your database you can provide a textual alias for the object. Note: In general, when youre creating a group or higher level object, use an alias. If youre managing access to a specic item or record in the database, use the model/foreign key method. You create new ACL objects using the core CakePHP ACL models. In doing so, there are a number of elds youll want to use when saving data: model, foreign_key, alias, and parent_id. The model and foreign_key elds for an ACL object allows you to link up the object to its corresponding model record (if there is one). For example, many AROs will have corresponding User records in the database. Setting an AROs foreign_key to the Users ID will allow you to link up ARO and User information with a single User model nd() call if youve set up the correct model associations. Conversely, if you want to manage edit operation on a specic blog post or recipe listing, you may choose to link an ACO to that specic model record. The alias for an ACL object is just a human-readable label you can use to identify an ACL object that has no direct model record correlation. Aliases are usually useful in naming user groups or ACO collections. The parent_id for an ACL object allows you to ll out the tree structure. Supply the ID of the parent node in the tree to create a new child. Before we can create new ACL objects, well need to load up their respective classes. The easiest way to do this is to include Cakes ACL Component in your controllers $components array:
public $components = array(Acl);

Once weve got that done, lets see what some examples of creating these objects might look like. The following code could be placed in a controller action somewhere: Note: While the examples here focus on ARO creation, the same techniques can be used to create an ACO tree.

More on controllers

117

CakePHP Cookbook Documentation, Release 2.x

Keeping with our Fellowship setup, lets rst create our ARO groups. Because our groups wont really have specic records tied to them, well use aliases to create these ACL objects. What were doing here is from the perspective of a controller action, but could be done elsewhere. What well cover here is a bit of an articial approach, but you should feel comfortable using these techniques to build AROs and ACOs on the y. This shouldnt be anything drastically new - were just using models to save data like we always do:
public function any_action() { $aro = $this->Acl->Aro; // Heres all of our group info in an array we can iterate through $groups = array( 0 => array( alias => warriors ), 1 => array( alias => wizards ), 2 => array( alias => hobbits ), 3 => array( alias => visitors ), ); // Iterate and create ARO groups foreach ($groups as $data) { // Remember to call create() when saving in loops... $aro->create(); // Save data $aro->save($data); } // Other action logic goes here... }

Once weve got them in there, we can use the ACL console application to verify the tree structure.
$ cake acl view aro Aro tree: --------------------------------------------------------------[1]warriors [2]wizards [3]hobbits [4]visitors ---------------------------------------------------------------

118

Chapter 4. Controllers

CakePHP Cookbook Documentation, Release 2.x

I suppose its not much of a tree at this point, but at least weve got some verication that weve got four top-level nodes. Lets add some children to those ARO nodes by adding our specic user AROs under these groups. Every good citizen of Middle Earth has an account in our new system, so well tie these ARO records to specic model records in our database. Note: When adding child nodes to a tree, make sure to use the ACL node ID, rather than a foreign_key value.
public function any_action() { $aro = new Aro(); // Here are our user records, ready to be linked up to new ARO records // This data could come from a model and modified, but were using static // arrays here for demonstration purposes. $users = array( 0 => array( alias => Aragorn, parent_id => 1, model => User, foreign_key => 2356, ), 1 => array( alias => Legolas, parent_id => 1, model => User, foreign_key => 6342, ), 2 => array( alias => Gimli, parent_id => 1, model => User, foreign_key => 1564, ), 3 => array( alias => Gandalf, parent_id => 2, model => User, foreign_key => 7419, ), 4 => array( alias => Frodo, parent_id => 3, model => User, foreign_key => 7451, ), 5 => array( alias => Bilbo, parent_id => 3, model => User, foreign_key => 5126, ),

More on controllers

119

CakePHP Cookbook Documentation, Release 2.x

6 => array( alias => Merry, parent_id => 3, model => User, foreign_key => 5144, ), 7 => array( alias => Pippin, parent_id => 3, model => User, foreign_key => 1211, ), 8 => array( alias => Gollum, parent_id => 4, model => User, foreign_key => 1337, ), ); // Iterate and create AROs (as children) foreach ($users as $data) { // Remember to call create() when saving in loops... $aro->create(); //Save data $aro->save($data); } // Other action logic goes here... }

Note: Typically you wont supply both an alias and a model/foreign_key, but were using both here to make the structure of the tree easier to read for demonstration purposes. The output of that console application command should now be a little more interesting. Lets give it a try:
$ cake acl view aro Aro tree: --------------------------------------------------------------[1]warriors [5]Aragorn [6]Legolas [7]Gimli [2]wizards

120

Chapter 4. Controllers

CakePHP Cookbook Documentation, Release 2.x

[8]Gandalf [3]hobbits [9]Frodo [10]Bilbo [11]Merry [12]Pippin [4]visitors [13]Gollum ---------------------------------------------------------------

Now that weve got our ARO tree setup properly, lets discuss a possible approach for structuring an ACO tree. While we can structure more of an abstract representation of our ACOs, its often more practical to model an ACO tree after Cakes Controller/Action setup. Weve got ve main objects were handling in this Fellowship scenario, and the natural setup for that in a Cake application is a group of models, and ultimately the controllers that manipulate them. Past the controllers themselves, well want to control access to specic actions in those controllers. Based on that idea, lets set up an ACO tree that will mimic a Cake app setup. Since we have ve ACOs, well create an ACO tree that should end up looking something like the following: Weapons Rings PorkChops DiplomaticEfforts Ales One nice thing about a Cake ACL setup is that each ACO automatically contains four properties related to CRUD (create, read, update, and delete) actions. You can create children nodes under each of these ve main ACOs, but using Cakes built in action management covers basic CRUD operations on a given object. Keeping this in mind will make your ACO trees smaller and easier to maintain. Well see how these are used later on when we discuss how to assign permissions. Since youre now a pro at adding AROs, use those same techniques to create this ACO tree. Create these upper level groups using the core Aco model. Assigning Permissions After creating our ACOs and AROs, we can nally assign permissions between the two groups. This is done using Cakes core Acl component. Lets continue on with our example. Here well work in the context of a controller action. We do that because permissions are managed by the Acl Component.

More on controllers

121

CakePHP Cookbook Documentation, Release 2.x

class SomethingsController extends AppController { // You might want to place this in the AppController // instead, but here works great too. public $components = array(Acl); }

Lets set up some basic permissions using the AclComponent in an action inside this controller.
public function index() { // Allow warriors complete access to weapons // Both these examples use the alias syntax $this->Acl->allow(warriors, Weapons); // Though the King may not want to let everyone // have unfettered access $this->Acl->deny(warriors/Legolas, Weapons, delete); $this->Acl->deny(warriors/Gimli, Weapons, delete); die(print_r(done, 1)); }

The rst call we make to the AclComponent allows any user under the warriors ARO group full access to anything under the Weapons ACO group. Here were just addressing ACOs and AROs by their aliases. Notice the usage of the third parameter? Thats where we use those handy actions that are in-built for all Cake ACOs. The default options for that parameter are create, read, update, and delete but you can add a column in the aros_acos database table (prexed with _ - for example _admin) and use it alongside the defaults. The second set of calls is an attempt to make a more ne-grained permission decision. We want Aragorn to keep his full-access privileges, but deny other warriors in the group the ability to delete Weapons records. Were using the alias syntax to address the AROs above, but you might want to use the model/foreign key syntax yourself. What we have above is equivalent to this:
// 6342 = Legolas // 1564 = Gimli $this->Acl->deny(array(model => User, foreign_key => 6342), Weapons, delete); $this->Acl->deny(array(model => User, foreign_key => 1564), Weapons, delete);

Note: Addressing a node using the alias syntax uses a slash-delimited string (/users/employees/developers). Addressing a node using model/foreign key syntax uses an array with two parameters: array(model => User, foreign_key => 8282). The next section will help us validate our setup by using the AclComponent to check the permissions weve just set up. Checking Permissions: The ACL Component Lets use the AclComponent to make sure dwarves and elves cant remove things from the armory. At this point, we should be able to use the AclComponent to 122 Chapter 4. Controllers

CakePHP Cookbook Documentation, Release 2.x

make a check between the ACOs and AROs weve created. The basic syntax for making a permissions check is:
$this->Acl->check($aro, $aco, $action = *);

Lets give it a try inside a controller action:

public function index() { // These all return true: $this->Acl->check(warriors/Aragorn, $this->Acl->check(warriors/Aragorn, $this->Acl->check(warriors/Aragorn, $this->Acl->check(warriors/Aragorn, $this->Acl->check(warriors/Aragorn,

Weapons); Weapons, create); Weapons, read); Weapons, update); Weapons, delete);

// Remember, we can use the model/id syntax // for our user AROs $this->Acl->check(array(User => array(id => 2356)), Weapons); // These also return true: $result = $this->Acl->check(warriors/Legolas, Weapons, create); $result = $this->Acl->check(warriors/Gimli, Weapons, read); // But these return false: $result = $this->Acl->check(warriors/Legolas, Weapons, delete); $result = $this->Acl->check(warriors/Gimli, Weapons, delete); }

The usage here is demonstrational, but hopefully you can see how checking like this can be used to decide whether or not to allow something to happen, show an error message, or redirect the user to a login. Each of these core components are detailed in their own chapters. For now, well show you how to create your own components. Creating components keeps controller code clean and allows you to reuse code between projects. Conguring Components Many of the core components require conguration. Some examples of components requiring conguration are Authentication, Cookie and /core-libraries/components/email. Conguration for these components, and for components in general, is usually done in the $components array or your controllers beforeFilter() method:
class PostsController extends AppController { public $components = array( Auth => array( authorize => array(controller), loginAction => array(controller => users, action => login) ), Cookie => array(name => CookieMonster) );

Would be an example of conguring a component with the $components array. All core components allow their conguration settings to be set in this way. In addition you can congure components in your More on controllers 123

CakePHP Cookbook Documentation, Release 2.x

controllers beforeFilter() method. This is useful when you need to assign the results of a function to a component property. The above could also be expressed as:
public function beforeFilter() { $this->Auth->authorize = array(controller); $this->Auth->loginAction = array(controller => users, action => login); $this->Cookie->name = CookieMonster; }

Its possible, however, that a component requires certain conguration options to be set before the controllers beforeFilter() is run. To this end, some components allow conguration options be set in the $components array:
public $components = array( DebugKit.Toolbar => array(panels => array(history, session)) );

Consult the relevant documentation to determine what conguration options each component provides. One common setting to use is the className option, which allows you to alias components. This feature is useful when you want to replace $this->Auth or another common Component reference with a custom implementation:
// app/Controller/PostsController.php class PostsController extends AppController { public $components = array( Auth => array( className => MyAuth ) ); } // app/Controller/Component/MyAuthComponent.php App::uses(AuthComponent, Controller/Component); class MyAuthComponent extends AuthComponent { // Add your code to override the core AuthComponent }

The above would alias MyAuthComponent to $this->Auth in your controllers. Note: Aliasing a component replaces that instance anywhere that component is used, including inside other Components.

Using Components Once youve included some components in your controller, using them is pretty simple. Each component you use is exposed as a property on your controller. If you had loaded up the SessionComponent and the CookieComponent in your controller, you could access them like so:

124

Chapter 4. Controllers

CakePHP Cookbook Documentation, Release 2.x

class PostsController extends AppController { public $components = array(Session, Cookie); public function delete() { if ($this->Post->delete($this->request->data(Post.id)) { $this->Session->setFlash(Post deleted.); return $this->redirect(array(action => index)); } }

Note: Since both Models and Components are added to Controllers as properties they share the same namespace. Be sure to not give a component and a model the same name.

Loading components on the y

You might not need all of your components available on every controller action. In situations like this you can load a component at runtime using the Component Collection. From inside a controllers method you can do the following:
$this->OneTimer = $this->Components->load(OneTimer); $this->OneTimer->getTime();

Note: Keep in mind that loading a component on the y will not call its initialize method. If the component you are calling has this method you will need to call it manually after load.

Component Callbacks Components also offer a few request life-cycle callbacks that allow them to augment the request cycle. See the base Component API for more information on the callbacks components offer. Creating a Component Suppose our online application needs to perform a complex mathematical operation in many different parts of the application. We could create a component to house this shared logic for use in many different controllers. The rst step is to create a new component le and class. Create the le in /app/Controller/Component/MathComponent.php. The basic structure for the component would look something like this:
App::uses(Component, Controller); class MathComponent extends Component { public function doComplexOperation($amount1, $amount2) { return $amount1 + $amount2;

More on controllers

125

CakePHP Cookbook Documentation, Release 2.x

} }

Note: All components must extend Component. Failing to do this will trigger an exception.

Including your component in your controllers

Once our component is nished, we can use it in the applications controllers by placing the components name (minus the Component part) in the controllers $components array. The controller will automatically be given a new attribute named after the component, through which we can access an instance of it:
/* Make the new component available at $this->Math, as well as the standard $this->Session */ public $components = array(Math, Session);

Components declared in AppController will be merged with those in your other controllers. So there is no need to re-declare the same component twice. When including Components in a Controller you can also declare a set of parameters that will be passed on to the Components constructor. These parameters can then be handled by the Component:
public $components = array( Math => array( precision => 2, randomGenerator => srand ), Session, Auth );

The above would pass the array containing precision and randomGenerator to MathComponent::__construct() as the second parameter. By convention, any settings that have been passed that are also public properties on your component will have the values set based on the settings.
Using other Components in your Component

Sometimes one of your components may need to use another component. In this case you can include other components in your component the exact same way you include them in controllers - using the $components var:
// app/Controller/Component/CustomComponent.php App::uses(Component, Controller); class CustomComponent extends Component { // the other component your component uses public $components = array(Existing); public function initialize(Controller $controller) {

126

Chapter 4. Controllers

CakePHP Cookbook Documentation, Release 2.x

$this->Existing->foo(); } public function bar() { // ... } } // app/Controller/Component/ExistingComponent.php App::uses(Component, Controller); class ExistingComponent extends Component { public function foo() { // ... } }

Note that in contrast to a component included in a controller no callbacks will be triggered on a components component. Component API class Component The base Component class offers a few methods for lazily loading other Components through ComponentCollection as well as dealing with common handling of settings. It also provides prototypes for all the component callbacks. Component::__construct(ComponentCollection $collection, $settings = array()) Constructor for the base component class. All $settings that are also public properties will have their values changed to the matching value in $settings.
Callbacks

Component::initialize(Controller $controller) The initialize method is called before the controllers beforeFilter method. Component::startup(Controller $controller) The startup method is called after the controllers beforeFilter method but before the controller executes the current action handler. Component::beforeRender(Controller $controller) The beforeRender method is called after the controller executes the requested actions logic but before the controllers renders views and layout. Component::shutdown(Controller $controller) The shutdown method is called before output is sent to browser. Component::beforeRedirect(Controller $controller, $url, $status=null, $exit=true) The beforeRedirect method is invoked when the controllers redirect method is called but before any further action. If this method returns false the controller will not continue on to redirect the request.

More on controllers

127

CakePHP Cookbook Documentation, Release 2.x

The $url, $status and $exit variables have same meaning as for the controllers method. You can also return a string which will be interpreted as the url to redirect to or return associative array with key url and optionally status and exit.

128

Chapter 4. Controllers

CHAPTER 5

Views

Views are the V in MVC. Views are responsible for generating the specic output required for the request. Often this is in the form of HTML, XML, or JSON, but streaming les and creating PDFs that users can download are also responsibilities of the View Layer. CakePHP comes with a few built-in View classes for handling the most common rendering scenarios: To create XML or JSON webservices you can use the JSON and XML views. To serve protected les, or dynamically generated les, you can use Sending les. To create multiple themed views, you can use Themes.

View Templates
The view layer of CakePHP is how you speak to your users. Most of the time your views will be showing (X)HTML documents to browsers, but you might also need to serve AMF data to a Flash object, reply to a remote application via SOAP, or output a CSV le for a user. By default CakePHP view les are written in plain PHP and have a default extension of .ctp (CakePHP Template). These les contain all the presentational logic needed to get the data it received from the controller in a format that is ready for the audience youre serving to. If youd prefer using a templating language like Twig, or Smarty, a subclass of View will bridge your templating language and CakePHP. View les are stored in /app/View/, in a folder named after the controller that uses the les, and named after the action it corresponds to. For example, the view le for the Products controllers view() action, would normally be found in /app/View/Products/view.ctp. The view layer in CakePHP can be made up of a number of different parts. Each part has different uses, and will be covered in this chapter: views: Views are the part of the page that is unique to the action being run. They form the meat of your applications response. elements: smaller, reusable bits of view code. Elements are usually rendered inside of views.

129

CakePHP Cookbook Documentation, Release 2.x

layouts: view les that contain presentational code that is found wrapping many interfaces in your application. Most views are rendered inside of a layout. helpers: these classes encapsulate view logic that is needed in many places in the view layer. Among other things, helpers in CakePHP can help you build forms, build AJAX functionality, paginate model data, or serve RSS feeds.

Extending Views
New in version 2.1. View extending allows you to wrap one view in another. Combining this with view blocks gives you a powerful way to keep your views DRY . For example, your application has a sidebar that needs to change depending on the specic view being rendered. By extending a common view le you can avoid repeating the common markup for your sidebar, and only dene the parts that change:
// app/View/Common/view.ctp <h1><?php echo $this->fetch(title); ?></h1> <?php echo $this->fetch(content); ?> <div class="actions"> <h3>Related actions</h3> <ul> <?php echo $this->fetch(sidebar); ?> </ul> </div>

The above view le could be used as a parent view. It expects that the view extending it will dene the sidebar and title blocks. The content block is a special block that CakePHP creates. It will contain all the un-captured content from the extending view. Assuming our view le has a $post variable with the data about our post. Our view could look like:
<?php // app/View/Posts/view.ctp $this->extend(/Common/view); $this->assign(title, $post); $this->start(sidebar); ?> <li> <?php echo $this->Html->link(edit, array( action => edit, $post[Post][id] )); ?> </li> <?php $this->end(); ?> // The remaining content will be available as the content block // in the parent view. <?php echo h($post[Post][body]);

The post view above shows how you can extend a view, and populate a set of blocks. Any content not 130 Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

already in a dened block will be captured and put into a special block named content. When a view contains a call to extend() execution continues to the bottom of the current view le. Once its complete, the extended view will be rendered. Calling extend() more than once in a view le will override the parent view that will be processed next:
$this->extend(/Common/view); $this->extend(/Common/index);

The above will result in /Common/index.ctp being rendered as the parent view to the current view. You can nest extended views as many times as necessary. Each view can extend another view if desired. Each parent view will get the previous views content as the content block. Note: You should avoid using content as a block name in your application. CakePHP uses this for un-captured content in extended views.

Using view blocks

New in version 2.1. View blocks replace $scripts_for_layout and provide a exible API that allows you to dene slots or blocks in your views/layouts that will be dened elsewhere. For example blocks are ideal for implementing things such as sidebars, or regions to load assets at the bottom/top of the layout. Blocks can be dened in two ways. Either as a capturing block, or by direct assignment. The start(), append() and end() methods allow to work with capturing blocks:
// create the sidebar block. $this->start(sidebar); echo $this->element(sidebar/recent_topics); echo $this->element(sidebar/recent_comments); $this->end();

// Append into the sidebar later on. $this->append(sidebar); echo $this->element(sidebar/popular_topics); $this->end();

You can also append into a block using start() multiple times. assign() can be used to clear or overwrite a block at any time:
// Clear the previous content from the sidebar block. $this->assign(sidebar, );

In 2.3, a few new methods were added for working with blocks. The prepend() to prepend content to an existing block:
// Prepend to sidebar $this->prepend(sidebar, this content goes on top of sidebar);

The method startIfEmpty() can be used to start a block only if its empty or undened. If the block already exists the captured content will be discarded. This is useful when you want to conditionally dene Using view blocks 131

CakePHP Cookbook Documentation, Release 2.x

default content for a block should it not already exist:

// In a view file. // Create a navbar block $this->startIfEmpty(navbar); echo $this->element(navbar); echo $this->element(notifications); $this->end(); // In <?php <p>If <?php a parent view/layout $this->startIfEmpty(navbar); ?> the block is not defined by now - show this instead</p> $this->end(); ?>

// Somewhere later in the parent view/layout echo $this->fetch(navbar);

In the above example, the navbar block will only contain the content added in the rst section. Since the block was dened in the child view, the default content with the <p> tag will be discarded. Note: You should avoid using content as a block name. This is used by CakePHP internally for extended views, and view content in the layout.

Displaying blocks
New in version 2.1. You can display blocks using the fetch() method. fetch() will safely output a block, returning if a block does not exist:
echo $this->fetch(sidebar);

You can also use fetch to conditionally show content that should surround a block should it exist. This is helpful in layouts, or extended views where you want to conditionally show headings or other markup:
// in app/View/Layouts/default.ctp <?php if ($this->fetch(menu)): ?> <div class="menu"> <h3>Menu options</h3> <?php echo $this->fetch(menu); ?> </div> <?php endif; ?>

As of 2.3.0 you can also provide a default value for a block should it not have any content. This allows you to easily add placeholder content, for empty states. You can provide a default value using the 2nd argument:
<div class="shopping-cart"> <h3>Your Cart</h3> <?php echo $this->fetch(cart, Your cart is empty); ?> </div>

Changed in version 2.3: The $default argument was added in 2.3.

132

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

Using blocks for script and CSS les

New in version 2.1. Blocks replace the deprecated $scripts_for_layout layout variable. Instead you should use blocks. The HtmlHelper ties into view blocks, and its script(), css(), and meta() methods each update a block with the same name when used with the inline = false option:
<?php // in your view file $this->Html->script(carousel, array(inline => false)); $this->Html->css(carousel, null, array(inline => false)); ?> // In your layout file. <!DOCTYPE html> <html lang="en"> <head> <title><?php echo $this->fetch(title); ?></title> <?php echo $this->fetch(script); ?> <?php echo $this->fetch(css); ?> </head> // rest of the layout follows

The HtmlHelper also allows you to control which block the scripts and CSS go to:
// in your view $this->Html->script(carousel, array(block => scriptBottom)); // in your layout echo $this->fetch(scriptBottom);

Layouts
A layout contains presentation code that wraps around a view. Anything you want to see in all of your views should be placed in a layout. CakePHPs default layout is located at /app/View/Layouts/default.ctp. If you want to change the overall look of your application, then this is the right place to start, because controller-rendered view code is placed inside of the default layout when the page is rendered. Other layout les should be placed in /app/View/Layouts. When you create a layout, you need to tell CakePHP where to place the output of your views. To do so, make sure your layout includes a place for $this->fetch(content) Heres an example of what a default layout might look like:
<!DOCTYPE html> <html lang="en"> <head> <title><?php echo $title_for_layout?></title> <link rel="shortcut icon" href="favicon.ico" type="image/x-icon">  <?php echo $this->fetch(meta);

Layouts

133

CakePHP Cookbook Documentation, Release 2.x

echo $this->fetch(css); echo $this->fetch(script); ?> </head> <body>  <div id="header"> <div id="menu">...</div> </div>  <?php echo $this->fetch(content); ?>  <div id="footer">...</div> </body> </html>

Note: Prior to version 2.1, method fetch() was not available, fetch(content) is a replacement for $content_for_layout and lines fetch(meta), fetch(css) and fetch(script) are contained in the $scripts_for_layout variable in version 2.0 The script, css and meta blocks contain any content dened in the views using the built-in HTML helper. Useful for including javascript and CSS les from views. Note: When using HtmlHelper::css() or HtmlHelper::script() in view les, specify false for the inline option to place the html source in a block with the same name. (See API for more details on usage). The content block contains the contents of the rendered view. $title_for_layout contains the page title. This variable is generated automatically, but you can override it by setting it in your controller/view. To set the title for the layout, its easiest to do so in the controller, setting the $title_for_layout variable:
class UsersController extends AppController { public function view_active() { $this->set(title_for_layout, View Active Users); } }

You can also set the title_for_layout variable from inside the view le:
$this->set(title_for_layout, $titleContent);

134

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

You can create as many layouts as you wish: just place them in the app/View/Layouts directory, and switch between them inside of your controller actions using the controller or views $layout property:
// from a controller public function admin_view() { // stuff $this->layout = admin; } // from a view file $this->layout = loggedin;

For example, if a section of my site included a smaller ad banner space, I might create a new layout with the smaller advertising space and specify it as the layout for all controllers actions using something like:
class UsersController extends AppController { public function view_active() { $this->set(title_for_layout, View Active Users); $this->layout = default_small_ad; } public function view_image() { $this->layout = image; //output user image } }

CakePHP features two core layouts (besides CakePHPs default layout) you can use in your own application: ajax and ash. The Ajax layout is handy for crafting Ajax responses - its an empty layout (most ajax calls only require a bit of markup in return, rather than a fully-rendered interface). The ash layout is used for messages shown by Controller::flash() method. Three other layouts, xml, js, and rss, exist in the core for a quick and easy way to serve up content that isnt text/html.

Using layouts from plugins

New in version 2.1. If you want to use a layout that exists in a plugin, you can use plugin syntax. For example to use the contact layout from the Contacts plugin:
class UsersController extends AppController { public function view_active() { $this->layout = Contacts.contact; } }

Elements
Many applications have small blocks of presentation code that need to be repeated from page to page, sometimes in different places in the layout. CakePHP can help you repeat parts of your website that need to Elements 135

CakePHP Cookbook Documentation, Release 2.x

be reused. These reusable parts are called Elements. Ads, help boxes, navigational controls, extra menus, login forms, and callouts are often implemented in CakePHP as elements. An element is basically a miniview that can be included in other views, in layouts, and even within other elements. Elements can be used to make a view more readable, placing the rendering of repeating elements in its own le. They can also help you re-use content fragments in your application. Elements live in the /app/View/Elements/ folder, and have the .ctp lename extension. They are output using the element method of the view:
echo $this->element(helpbox);

Passing Variables into an Element

You can pass data to an element through the elements second argument:
echo $this->element(helpbox, array( "helptext" => "Oh, this text is very helpful." ));

Inside the element le, all the passed variables are available as members of the parameter array (in the same way that Controller::set() in the controller works with view les). In the above example, the /app/View/Elements/helpbox.ctp le can use the $helptext variable:
// inside app/View/Elements/helpbox.ctp echo $helptext; //outputs "Oh, this text is very helpful."

The View::element() method also supports options for the element. The options supported are cache and callbacks. An example:

echo $this->element(helpbox, array( "helptext" => "This is passed to the element as $helptext", "foobar" => "This is passed to the element as $foobar ", ), array( "cache" => "long_view", // uses the "long_view" cache configuration "callbacks" => true // set to true to have before/afterRender called for the elemen ) );

Element caching is facilitated through the Cache class. You can congure elements to be stored in any Cache conguration youve setup. This gives you a great amount of exibility to decide where and for how long elements are stored. To cache different versions of the same element in an application, provide a unique cache key value using the following format:
$this->element(helpbox, array(), array( "cache" => array(config => short, key => unique value) ) );

You can take full advantage of elements by using requestAction(). The requestAction() function fetches view variables from a controller action and returns them as an array. This enables your elements to perform in true MVC style. Create a controller action that prepares the view variables for your elements, 136 Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

then call requestAction() inside the second parameter of element() to feed the element the view variables from your controller. To do this, in your controller add something like the following for the Post example:
class PostsController extends AppController { // ... public function index() { $posts = $this->paginate(); if ($this->request->is(requested)) { return $posts; } else { $this->set(posts, $posts); } } }

And then in the element we can access the paginated posts model. To get the latest ve posts in an ordered list we would do something like the following:
<h2>Latest Posts</h2> <?php $posts = $this->requestAction(posts/index/sort:created/direction:asc/limit:5); ?> <ol> <?php foreach ($posts as $post): ?> <li><?php echo $post[Post][title]; ?></li> <?php endforeach; ?> </ol>

Caching Elements
You can take advantage of CakePHP view caching if you supply a cache parameter. If set to true, it will cache the element in the default Cache conguration. Otherwise, you can set which cache conguration should be used. See Caching for more information on conguring Cache. A simple example of caching an element would be:
echo $this->element(helpbox, array(), array(cache => true));

If you render the same element more than once in a view and have caching enabled be sure to set the key parameter to a different name each time. This will prevent each successive call from overwriting the previous element() calls cached result. E.g.:
echo $this->element( helpbox, array(var => $var), array(cache => array(key => first_use, config => view_long) ); echo $this->element( helpbox, array(var => $differenVar), array(cache => array(key => second_use, config => view_long) );

Elements

137

CakePHP Cookbook Documentation, Release 2.x

The above will ensure that both element results are cached separately. If you want all element caching to use the same cache conguration, you can save some repetition, by setting View::$elementCache to the cache conguration you want to use. CakePHP will use this conguration, when none is given.

Requesting Elements from a Plugin 2.0

To load an element from a plugin, use the plugin option (moved out of the data option in 1.x):
echo $this->element(helpbox, array(), array(plugin => Contacts));

2.1
If you are using a plugin and wish to use elements from within the plugin, just use the familiar plugin syntax. If the view is being rendered for a plugin controller/action, the plugin name will automatically be prexed onto all elements used, unless another plugin name is present. If the element doesnt exist in the plugin, it will look in the main APP folder.:
echo $this->element(Contacts.helpbox);

If your view is a part of a plugin you can omit the plugin name. ContactsController of the Contacts plugin:
echo $this->element(helpbox); // and echo $this->element(Contacts.helpbox);

For example, if you are in the

Are equivalent and will result in the same element being rendered. Changed in version 2.1: The $options[plugin] option was deprecated and support for Plugin.element was added.

Creating your own view classes

You may need to create custom view classes to enable new types of data views, or add additional custom view rendering logic to your application. Like most components of CakePHP view classes have a few conventions: View class les should be put in App/View. For example App/View/PdfView.php View classes should be sufxed with View. For example PdfView. When referencing view class names you should omit the View sufx. $this->viewClass = Pdf;. Youll also want to extend View to ensure things work correctly:
// in App/View/PdfView.php App::uses(View, View);

For example

138

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

class PdfView extends View { public function render($view = null, $layout = null) { // custom logic here. } }

Replacing the render method lets you take full control over how your content is rendered.

View API
class View View methods are accessible in all view, element and layout les. $this->method() To call any view method use

View::set(string $var, mixed $value) Views have a set() method that is analogous to the set() found in Controller objects. Using set() from your view le will add the variables to the layout and elements that will be rendered later. See Controller Methods for more information on using set(). In your view le you can do:
$this->set(activeMenuButton, posts);

Then in your layout the $activeMenuButton variable will be available and contain the value posts. View::getVar(string $var) Gets the value of the viewVar with the name $var View::getVars() Gets a list of all the available view variables in the current rendering scope. Returns an array of variable names. View::element(string $elementPath, array $data, array $options = array()) Renders an element or view partial. See the section on Elements for more information and examples. View::uuid(string $object, mixed $url) Generates a unique non-random DOM ID for an object, based on the object type and url. This method is often used by helpers that need to generate unique DOM IDs for elements such as the JsHelper:
$uuid = $this->uuid(form, array(controller => posts, action => index)); //$uuid contains form0425fe3bad

View::addScript(string $name, string $content) Adds content to the internal scripts buffer. This buffer is made available in the layout as $scripts_for_layout. This method is helpful when creating helpers that need to add javascript or css directly to the layout. Keep in mind that scripts added from the layout, or elements in the layout will not be added to $scripts_for_layout. This method is most often used from inside helpers, like the JsHelper and HtmlHelper Helpers. Deprecated since version 2.1: Use the Using view blocks features instead.

View API

139

CakePHP Cookbook Documentation, Release 2.x

View::blocks() Get the names of all dened blocks as an array. View::start($name) Start a capturing block for a view block. See the section on Using view blocks for examples. New in version 2.1. View::end() End the top most open capturing block. See the section on Using view blocks for examples. New in version 2.1. View::append($name, $content) Append into the block with $name. See the section on Using view blocks for examples. New in version 2.1. View::prepend($name, $content) Prepend into the block with $name. See the section on Using view blocks for examples. New in version 2.3. View::startIfEmpty($name) Conditionally start a block, only if its empty. All content in the block will be captured and discarded if the block is already dened. New in version 2.3. View::assign($name, $content) Assign the value of a block. This will overwrite any existing content. See the section on Using view blocks for examples. New in version 2.1. View::fetch($name, $default = ) Fetch the value of a block. If a block is empty or undened will be returned. See the section on Using view blocks for examples. New in version 2.1. View::extend($name) Extend the current view/element/layout with the named one. See the section on Extending Views for examples. New in version 2.1. property View::$layout Set the layout the current view will be wrapped in. property View::$elementCache The cache conguration used to cache elements. Setting this property will change the default conguration used to cache elements. This default can be overridden using the cache option in the element method. property View::$request An instance of CakeRequest. Use this instance to access information about the current request. property View::$output Contains the last rendered content from a view, either the view le, or the layout content. Deprecated since version 2.1: Use $view->Blocks->get(content); instead. property View::$Blocks An instance of ViewBlock. Used to provide view block functionality in view rendering. New in version 2.1.

140

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

More about Views

Themes
You can take advantage of themes, making it easy to switch the look and feel of your page quickly and easily. To use themes, specify the theme name in your controller:
class ExampleController extends AppController { public $theme = Example; }

Changed in version 2.1: Versions previous to 2.1 required setting the $this->viewClass = Theme. 2.1 removes this requirement as the normal View class supports themes You can also set or change the theme name within an action or within the beforeFilter or beforeRender callback functions:
$this->theme = AnotherExample;

Theme view les need to be within the /app/View/Themed/ folder. Within the themed folder, create a folder using the same name as your theme name. For example, the above theme would be found in /app/View/Themed/AnotherExample. Its important to remember that CakePHP expects CamelCase theme names. Beyond that, the folder structure within the /app/View/Themed/Example/ folder is exactly the same as /app/View/. For example, the view le for an edit action of a Posts controller would reside at /app/View/Themed/Example/Posts/edit.ctp. Layout les would reside in /app/View/Themed/Example/Layouts/. If a view le cant be found in the theme, CakePHP will try to locate the view le in the /app/View/ folder. This way, you can create master view les and simply override them on a case-by-case basis within your theme folder. Theme assets Themes can contain static assets as well as view les. A theme can include any necessary assets in its webroot directory. This allows for easy packaging and distribution of themes. While in development, requests for theme assets will be handled by Dispatcher. To improve performance for production environments, its recommended that you either symlink or copy theme assets into the applications webroot. See below for more information.

To use the new theme webroot create directories like app/View/Themed/<themeName>/webroot<path_to_file in your theme. The Dispatcher will handle nding the correct theme assets in your view paths. All of CakePHPs built-in helpers are aware of themes and will create the correct paths automatically. Like view les, if a le isnt in the theme folder, it will default to the main webroot folder:
//When in a theme with the name of purple_cupcake $this->Html->css(main.css);

More about Views

141

CakePHP Cookbook Documentation, Release 2.x

//creates a path like /theme/purple_cupcake/css/main.css //and links to app/View/Themed/PurpleCupcake/webroot/css/main.css

Increasing performance of plugin and theme assets Its a well known fact that serving assets through PHP is guaranteed to be slower than serving those assets without invoking PHP. And while the core team has taken steps to make plugin and theme asset serving as fast as possible, there may be situations where more performance is required. In these situations its recommended that you either symlink or copy out plugin/theme assets to directories in app/webroot with paths matching those used by CakePHP. app/Plugin/DebugKit/webroot/js/my_file.js app/webroot/debug_kit/js/my_file.js app/View/Themed/Navy/webroot/css/navy.css app/webroot/theme/Navy/css/navy.css becomes becomes

Media Views
class MediaView Deprecated since version 2.3: Use Sending les instead. Media views allow you to send binary les to the user. For example, you may wish to have a directory of les outside of the webroot to prevent users from direct linking them. You can use the Media view to pull the le from a special folder within /app/, allowing you to perform authentication before delivering the le to the user. To use the Media view, you need to tell your controller to use the MediaView class instead of the default View class. After that, just pass in additional parameters to specify where your le is located:
class ExampleController extends AppController { public function download() { $this->viewClass = Media; // Download app/outside_webroot_dir/example.zip $params = array( id => example.zip, name => example, download => true, extension => zip, path => APP . outside_webroot_dir . DS ); $this->set($params); } }

Heres an example of rendering a le whose mime type is not included in the MediaViews $mimeType array. We are also using a relative path which will default to your app/webroot folder:

142

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

public function download() { $this->viewClass = Media; // Render app/webroot/files/example.docx $params = array( id => example.docx, name => example, extension => docx, mimeType => array( docx => application/vnd.openxmlformats-officedocument.wordprocessingml.docum ), path => files . DS ); $this->set($params); }

Settable Parameters id The ID is the le name as it resides on the le server including the le extension. name The name allows you to specify an alternate le name to be sent to the user. Specify the name without the le extension. download A boolean value indicating whether headers should be set to force download. extension The le extension. This is matched against an internal list of acceptable mime types. If the mime type specied is not in the list (or sent in the mimeType parameter array), the le will not be downloaded. path The folder name, including the nal directory separator. The path should be absolute but can be relative to the app/webroot folder. mimeType An array with additional mime types to be merged with MediaView internal list of acceptable mime types. cache A boolean or integer value - If set to true it will allow browsers to cache the le (defaults to false if not set); otherwise set it to the number of seconds in the future for when the cache should expire.

JSON and XML views

New in CakePHP 2.1 are two new view classes. The XmlView and JsonView let you easily create XML and JSON responses, and integrate with the RequestHandlerComponent. By enabling RequestHandlerComponent in your application, and enabling support for the xml and or json extensions, you can automatically leverage the new view classes. XmlView and JsonView will be referred to as data views for the rest of this page. There are two ways you can generate data views. The rst is by using the _serialize key, and the second is by creating normal view les.

More about Views

143

CakePHP Cookbook Documentation, Release 2.x

Enabling data views in your application Before you can use the data view classes, youll need to do a bit of setup: 1. Enable the json and or xml extensions with Router::parseExtensions(). This will enable Router to handle multiple extensions. 2. Add the RequestHandlerComponent to your controllers list of components. This will enable automatic view class switching on content types. You can also set the component up with the viewClassMap setting, to map types to your custom classes and/or map other data types. New in version 2.3: RequestHandlerComponent::viewClassMap() method has been added to map types to viewClasses. The viewClassMap setting will not work on earlier versions. After adding Router::parseExtensions(json); to your routes le, CakePHP will automatically switch view classes when a request is done with the .json extension, or the Accept header is application/json. Using data views with the serialize key The _serialize key is a special view variable that indicates which other view variable(s) should be serialized when using a data view. This lets you skip dening view les for your controller actions if you dont need to do any custom formatting before your data is converted into json/xml. If you need to do any formatting or manipulation of your view variables before generating the response, you should use view les. The value of _serialize can be either a string or an array of view variables to serialize:
class PostsController extends AppController { public function index() { $this->set(posts, $this->paginate()); $this->set(_serialize, array(posts)); } }

You can also dene _serialize as an array of view variables to combine:

class PostsController extends AppController { public function index() { // some code that created $posts and $comments $this->set(compact(posts, comments)); $this->set(_serialize, array(posts, comments)); } }

Dening _serialize as an array has the added benet of automatically appending a top-level <response> element when using XmlView. If you use a string value for _serialize and XmlView, make sure that your view variable has a single top-level element. Without a single top-level element the Xml will fail to generate.

144

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

Using a data view with view les You should use view les if you need to do some manipulation of your view content before creating the nal output. For example if we had posts, that had a eld containing generated HTML, we would probably want to omit that from a JSON response. This is a situation where a view le would be useful:
// Controller code class PostsController extends AppController { public function index() { $this->set(compact(posts, comments)); } } // View code - app/View/Posts/json/index.ctp foreach ($posts as &$post) { unset($post[Post][generated_html]); } echo json_encode(compact(posts, comments));

You can do more more complex manipulations, or use helpers to do formatting as well. Note: The data view classes dont support layouts. They assume that the view le will output the serialized content. class XmlView A view class for generating Xml view data. See above for how you can use XmlView in your application. By default when using _serialize the XmlView will wrap your serialized view variables with a <response> node. You can set a custom name for this node using the _rootNode view variable. New in version 2.3: The _rootNode feature was added. class JsonView A view class for generating Json view data. See above for how you can use JsonView in your application. JSONP response New in version 2.4. When using JsonView you can use the special view variable _jsonp to enable returning a JSONP response. Setting it to true makes the view class check if query string parameter named callback is set and if so wrap the json response in the function name provided. If you want to use a custom query string paramer name instead of callback set _jsonp to required name instead of true.

Helpers
Helpers are the component-like classes for the presentation layer of your application. They contain presentational logic that is shared between many views, elements, or layouts. This chapter will show you how to create your own helpers, and outline the basic tasks CakePHPs core helpers can help you accomplish.

More about Views

145

CakePHP Cookbook Documentation, Release 2.x

CakePHP features a number of helpers that aid in view creation. They assist in creating well-formed markup (including forms), aid in formatting text, times and numbers, and can even speed up Ajax functionality. For more information on the helpers included in CakePHP, check out the chapter for each helper: CacheHelper class CacheHelper(View $view, array $settings = array()) The Cache helper assists in caching entire layouts and views, saving time repetitively retrieving data. View Caching in Cake temporarily stores parsed layouts and views as simple PHP + HTML les. It should be noted that the Cache helper works quite differently than other helpers. It does not have methods that are directly called. Instead, a view is marked with cache tags indicating which blocks of content should not be cached. The CacheHelper then uses helper callbacks to process the le and output to generate the cache le. When a URL is requested, CakePHP checks to see if that request string has already been cached. If it has, the rest of the url dispatching process is skipped. Any nocache blocks are processed normally and the view is served. This creates a big savings in processing time for each request to a cached URL as minimal code is executed. If Cake doesnt nd a cached view, or the cache has expired for the requested URL it continues to process the request normally.
Using the Helper

There are two steps you have to take before you can use the CacheHelper. First in your APP/Config/core.php uncomment the Congure write call for Cache.check. This will tell CakePHP to check for, and generate view cache les when handling requests. Once youve uncommented the Cache.check line you will need to add the helper to your controllers $helpers array:
class PostsController extends AppController { public $helpers = array(Cache); }

You will also need to add the CacheDispatcher to your dispatcher lters in your bootstrap:
Configure::write(Dispatcher.filters, array( CacheDispatcher ));

New in version 2.3: If you have a setup with multiple domains or languages you can use Congure::write(Cache.viewPrex, YOURPREFIX); to store the view cache les prexed. Additional conguration options CacheHelper has a few additional conguration options you can use to tune and tweak its behavior. This is done through the $cacheAction variable in your controllers. $cacheAction should be set to an array which contains the actions you want cached, and the duration in seconds you want those views cached. The time value can be expressed in a strtotime() format (e.g. 1 hour, or 3 minutes). Using the example of an ArticlesController, that receives a lot of trafc that needs to be cached:

146

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

public $cacheAction = array( view => 36000, index => 48000 );

This will cache the view action 10 hours, and the index action 13 hours. By making $cacheAction a strtotime() friendly value you can cache every action in the controller:
public $cacheAction = "1 hour";

You can also enable controller/component callbacks for cached views created with CacheHelper. To do so you must use the array format for $cacheAction and create an array like the following:
public $cacheAction = array( view => array(callbacks => true, duration => 21600), add => array(callbacks => true, duration => 36000), index => array(callbacks => true, duration => 48000) );

By setting callbacks => true you tell CacheHelper that you want the generated les to create the components and models for the controller. Additionally, re the component initialize, controller beforeFilter, and component startup callbacks. Note: Setting callbacks => true partly defeats the purpose of caching. This is also the reason it is disabled by default.

Marking Non-Cached Content in Views

There will be times when you dont want an entire view cached. For example, certain parts of the page may look different whether a user is currently logged in or browsing your site as a guest. To indicate blocks of content that are not to be cached, wrap them in   like so:
 <?php if ($this->Session->check(User.name)): ?> Welcome, <?php echo h($this->Session->read(User.name)); ?>. <?php else: ?> <?php echo $this->Html->link(Login, users/login); ?> <?php endif; ?>

Note: You cannot use nocache tags in elements. Since there are no callbacks around elements, they cannot be cached. It should be noted that once an action is cached, the controller method for the action will not be called. When a cache le is created, the request object, and view variables are serialized with PHPs serialize().

More about Views

147

CakePHP Cookbook Documentation, Release 2.x

Warning: If you have view variables that contain un-serializable content such as SimpleXML objects, resource handles, or closures you might not be able to use view caching.

Clearing the Cache

It is important to remember that CakePHP will clear a cached view if a model used in the cached view is modied. For example, if a cached view uses data from the Post model, and there has been an INSERT, UPDATE, or DELETE query made to a Post, the cache for that view is cleared, and new content is generated on the next request. Note: This automatic cache clearing requires the controller/model name to be part of the URL. If youve used routing to change your urls this feature will not work. If you need to manually clear the cache, you can do so by calling Cache::clear(). This will clear all cached data, excluding cached view les. If you need to clear the cached view les, use clearCache(). FormHelper class FormHelper(View $view, array $settings = array()) The FormHelper does most of the heavy lifting in form creation. The FormHelper focuses on creating forms quickly, in a way that will streamline validation, re-population and layout. The FormHelper is also exible - it will do almost everything for you using conventions, or you can use specic methods to get only what you need.
Creating Forms

The rst method youll need to use in order to take advantage of the FormHelper is create(). This special method outputs an opening form tag. FormHelper::create(string $model = null, array $options = array()) All parameters are optional. If create() is called with no parameters supplied, it assumes you are building a form that submits to the current controller, via the current URL. The default method for form submission is POST. The form element is also returned with a DOM ID. The ID is generated using the name of the model, and the name of the controller action, CamelCased. If I were to call create() inside a UsersController view, Id see something like the following output in the rendered view:
<form id="UserAddForm" method="post" action="/users/add">

Note: You can also pass false for $model. This will place your form data into the array: $this->request->data (instead of in the sub-array: $this->request->data[Model]). This can be handy for short forms that may not represent anything in your database.

148

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

The create() method allows us to customize much more using the parameters, however. First, you can specify a model name. By specifying a model for a form, you are creating that forms context. All elds are assumed to belong to this model (unless otherwise specied), and all models referenced are assumed to be associated with it. If you do not specify a model, then it assumes you are using the default model for the current controller:
// If you are on /recipes/add echo $this->Form->create(Recipe);

Output:
<form id="RecipeAddForm" method="post" action="/recipes/add">

This will POST the form data to the add() action of RecipesController. However, you can also use the same logic to create an edit form. The FormHelper uses the $this->request->data property to automatically detect whether to create an add or edit form. If $this->request->data contains an array element named after the forms model, and that array contains a non-empty value of the models primary key, then the FormHelper will create an edit form for that record. For example, if we browse to http://site.com/recipes/edit/5, we would get the following:
// Controller/RecipesController.php: public function edit($id = null) { if (empty($this->request->data)) { $this->request->data = $this->Recipe->findById($id); } else { // Save logic goes here } } // View/Recipes/edit.ctp: // Since $this->request->data[Recipe][id] = 5, we will get an edit form <?php echo $this->Form->create(Recipe); ?>

Output:
<form id="RecipeEditForm" method="post" action="/recipes/edit/5"> <input type="hidden" name="_method" value="PUT" />

Note: Since this is an edit form, a hidden input eld is generated to override the default HTTP method. When creating forms for models in plugins, you should always use plugin syntax when creating a form. This will ensure the form is correctly generated:
echo $this->Form->create(ContactManager.Contact);

The $options array is where most of the form conguration happens. This special array can contain a number of different key-value pairs that affect the way the form tag is generated. Changed in version 2.0: The default url for all forms, is now the current url including passed, named, and querystring parameters. You can override this default by supplying $options[url] in the second parameter of $this->Form->create().

More about Views

149

CakePHP Cookbook Documentation, Release 2.x

Options for create() There are a number of options for create(): $options[type] This key is used to specify the type of form to be created. Valid values include post, get, le, put and delete. Supplying either post or get changes the form submission method accordingly:
echo $this->Form->create(User, array(type => get));

Output:
<form id="UserAddForm" method="get" action="/users/add">

Specifying le changes the form submission method to post, and includes an enctype of multipart/form-data on the form tag. This is to be used if there are any le elements inside the form. The absence of the proper enctype attribute will cause the le uploads not to function:
echo $this->Form->create(User, array(type => file));

Output:

<form id="UserAddForm" enctype="multipart/form-data" method="post" action="/users/add"

When using put or delete, your form will be functionally equivalent to a post form, but when submitted, the HTTP request method will be overridden with PUT or DELETE, respectively. This allows CakePHP to emulate proper REST support in web browsers. $options[action] The action key allows you to point the form to a specic action in your current controller. For example, if youd like to point the form to the login() action of the current controller, you would supply an $options array like the following:
echo $this->Form->create(User, array(action => login));

Output:
<form id="UserLoginForm" method="post" action="/users/login">

$options[url] If the desired form action isnt in the current controller, you can specify a URL for the form action using the url key of the $options array. The supplied URL can be relative to your CakePHP application:
echo $this->Form->create(null, array( url => array(controller => recipes, action => add) ));

Output:
<form method="post" action="/recipes/add">

or can point to an external domain:

echo $this->Form->create(null, array( url => http://www.google.com/search, type => get ));

150

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

Output:
<form method="get" action="http://www.google.com/search">

Also check HtmlHelper::url() method for more examples of different types of urls. $options[default] If default has been set to boolean false, the forms submit action is changed so that pressing the submit button does not submit the form. If the form is meant to be submitted via AJAX, setting default to false suppresses the forms default behavior so you can grab the data and submit it via AJAX instead. $options[inputDefaults] You can declare a set of default options for input() with the inputDefaults key to customize your default input creation:
echo $this->Form->create(User, array( inputDefaults => array( label => false, div => false ) ));

All inputs created from that point forward would inherit the options declared in inputDefaults. You can override the defaultOptions by declaring the option in the input() call:

echo $this->Form->input(password); // No div, no label echo $this->Form->input(username, array(label => Username)); // has a label elem

Closing the Form

FormHelper::end($options = null) The FormHelper includes an end() method that completes the form. Often, end() only outputs a closing form tag, but using end() also allows the FormHelper to insert needed hidden form elements that SecurityComponent requires:
<?php echo $this->Form->create(); ?>  <?php echo $this->Form->end(); ?>

If a string is supplied as the rst parameter to end(), the FormHelper outputs a submit button named accordingly along with the closing form tag:
<?php echo $this->Form->end(Finish); ?>

Will output:
<div class="submit"> <input type="submit" value="Finish" /> </div> </form>

You can specify detail settings by passing an array to end(): More about Views 151

CakePHP Cookbook Documentation, Release 2.x

$options = array( label => Update, div => array( class => glass-pill, ) ); echo $this->Form->end($options);

Will output:
<div class="glass-pill"><input type="submit" value="Update" name="Update"></div>

See the API (http://api20.cakephp.org) for further details. Note: If you are using SecurityComponent in your application you should always end your forms with end().

Creating form elements

There are a few ways to create form inputs with the FormHelper. Well start by looking at input(). This method will automatically inspect the model eld it has been supplied in order to create an appropriate input for that eld. Internally input() delegates to other methods in FormHelper. FormHelper::input(string $eldName, array $options = array()) Creates the following elements given a particular Model.field: Wrapping div. Label element Input element(s) Error element with message if applicable. The type of input created depends on the column datatype: Column Type Resulting Form Field string (char, varchar, etc.) text boolean, tinyint(1) checkbox text textarea text, with name of password, passwd, or psword password text, with name of email email text, with name of tel, telephone, or phone tel date day, month, and year selects datetime, timestamp day, month, year, hour, minute, and meridian selects time hour, minute, and meridian selects 152 Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

The $options parameter allows you to customize how input() works, and nely control what is generated. The wrapping div will have a required classname appended if the validation rules for the Models eld do not specify allowEmpty => true. One limitation of this behavior is the elds model must have been loaded during this request. Or be directly associated to the model supplied to create(). New in version 2.3. Since 2.3 the HTML5 required attribute will also be added to the input based on validation rules. You can explicitly set required key in options array to override it for a eld. To skip browser validation triggering for the whole form you can set option formnovalidate => true for the input button you generate using FormHelper::submit() or set novalidate => true in options for FormHelper::create(). For example, lets assume that your User model includes elds for a username (varchar), password (varchar), approved (datetime) and quote (text). You can use the input() method of the FormHelper to create appropriate inputs for all of these form elds:
echo $this->Form->create(); echo echo echo echo $this->Form->input(username); $this->Form->input(password); $this->Form->input(approved); $this->Form->input(quote); //text //password //day, month, year, hour, minute, meridian //textarea

echo $this->Form->end(Add);

A more extensive example showing some options for a date eld:

echo $this->Form->input(birth_dt, array( label => Date of birth, dateFormat => DMY, minYear => date(Y) - 70, maxYear => date(Y) - 18, ));

Besides the specic options for input() found below, you can specify any option for the input type & any html attribute (for instance onfocus). For more information on $options and $htmlAttributes see HtmlHelper. Assuming that User hasAndBelongsToMany Group. In your controller, set a camelCase plural variable (group -> groups in this case, or ExtraFunkyModel -> extraFunkyModels) with the select options. In the controller action you would put the following:
$this->set(groups, $this->User->Group->find(list));

And in the view a multiple select can be created with this simple code:
echo $this->Form->input(Group);

If you want to create a select eld while using a belongsTo - or hasOne - Relation, you can add the following to your Users-controller (assuming your User belongsTo Group):

More about Views

153

CakePHP Cookbook Documentation, Release 2.x

$this->set(groups, $this->User->Group->find(list));

Afterwards, add the following to your form-view:

echo $this->Form->input(group_id);

If your model name consists of two or more words, e.g., UserGroup, when passing the data using set() you should name your data in a pluralised and camelCased format as follows:

$this->set(userGroups, $this->UserGroup->find(list)); // or $this->set(reallyInappropriateModelNames, $this->ReallyInappropriateModelName->find(

Note: Try to avoid using FormHelper::input() to generate submit buttons. FormHelper::submit() instead. FormHelper::inputs(mixed $elds = null, array $blacklist = null) Generate a set of inputs for $fields. If $elds is null the current model will be used.

Use

In addition to controller elds output, $fields can be used to control legend and eldset rendering with the fieldset and legend keys. $this->Form->inputs(array(legend => My legend)); Would generate an input set with a custom legend. You can customize individual inputs through $fields as well.:
echo $this->Form->inputs(array( name => array(label => custom label) ));

In addition to elds control, inputs() allows you to use a few additional options. fieldset Set to false to disable the eldset. If a string is supplied it will be used as the classname for the eldset element. legend Set to false to disable the legend for the generated input set. Or supply a string to customize the legend text. Field naming conventions The Form helper is pretty smart. Whenever you specify a eld name with the form helper methods, itll automatically use the current model name to build an input with a format like the following:
<input type="text" id="ModelnameFieldname" name="data[Modelname][fieldname]">

This allows you to omit the model name when generating inputs for the model that the form was created for. You can create inputs for associated models, or arbitrary models by passing in Modelname.eldname as the rst parameter:
echo $this->Form->input(Modelname.fieldname);

If you need to specify multiple elds using the same eld name, thus creating an array that can be saved in one shot with saveAll(), use the following convention:

154

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

echo $this->Form->input(Modelname.0.fieldname); echo $this->Form->input(Modelname.1.fieldname);

Output:
<input type="text" id="Modelname0Fieldname" name="data[Modelname][0][fieldname]"> <input type="text" id="Modelname1Fieldname" name="data[Modelname][1][fieldname]">

FormHelper uses several eld-sufxes internally for datetime input creation. If you are using elds named year, month, day, hour, minute, or meridian and having issues getting the correct input, you can set the name attribute to override the default behavior:
echo $this->Form->input(Model.year, array( type => text, name => data[Model][year] ));

Options FormHelper::input() supports a large number of options. In addition to its own options input() accepts options for the generated input types, as well as html attributes. The following will cover the options specic to FormHelper::input(). $options[type] You can force the type of an input, overriding model introspection, by specifying a type. In addition to the eld types found in the Creating form elements, you can also create le, password, and any type supported by HTML5:
echo $this->Form->input(field, array(type => file)); echo $this->Form->input(email, array(type => email));

Output:
<div class="input file"> <label for="UserField">Field</label> <input type="file" name="data[User][field]" value="" id="UserField" /> </div> <div class="input email"> <label for="UserEmail">Email</label> <input type="email" name="data[User][email]" value="" id="UserEmail" /> </div>

$options[div] Use this option to set attributes of the inputs containing div. Using a string value will set the divs class name. An array will set the divs attributes to those specied by the arrays keys/values. Alternatively, you can set this key to false to disable the output of the div. Setting the class name:
echo $this->Form->input(User.name, array( div => class_name ));

Output:

More about Views

155

CakePHP Cookbook Documentation, Release 2.x

Setting multiple attributes:

echo $this->Form->input(User.name, array( div => array( id => mainDiv, title => Div Title, style => display:block ) ));

Output:
<div class="input text" id="mainDiv" title="Div Title" style="display:block"> <label for="UserName">Name</label> <input name="data[User][name]" type="text" value="" id="UserName" /> </div>

Disabling div output:

echo $this->Form->input(User.name, array(div => false)); ?>

Output:
<label for="UserName">Name</label> <input name="data[User][name]" type="text" value="" id="UserName" />

$options[label] Set this key to the string you would like to be displayed within the label that usually accompanies the input:
echo $this->Form->input(User.name, array( label => The User Alias ));

Output:
<div class="input"> <label for="UserName">The User Alias</label> <input name="data[User][name]" type="text" value="" id="UserName" /> </div>

Alternatively, set this key to false to disable the output of the label:
echo $this->Form->input(User.name, array(label => false));

Output:
<div class="input"> <input name="data[User][name]" type="text" value="" id="UserName" /> </div>

156

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

Set this to an array to provide additional options for the label element. If you do this, you can use a text key in the array to customize the label text:
echo $this->Form->input(User.name, array( label => array( class => thingy, text => The User Alias ) ));

Output:
<div class="input"> <label for="UserName" class="thingy">The User Alias</label> <input name="data[User][name]" type="text" value="" id="UserName" /> </div>

$options[error] Using this key allows you to override the default model error messages and can be used, for example, to set i18n messages. It has a number of suboptions which control the wrapping element, wrapping element class name, and whether HTML in the error message will be escaped. To disable error message output & eld classes set the error key to false:
$this->Form->input(Model.field, array(error => false));

To disable only the error message, but retain the eld classes, set the errorMessage key to false:
$this->Form->input(Model.field, array(errorMessage => false));

To modify the wrapping element type and its class, use the following format:
$this->Form->input(Model.field, array( error => array(attributes => array(wrap => span, class => bzzz)) ));

To prevent HTML being automatically escaped in the error message output, set the escape suboption to false:
$this->Form->input(Model.field, array( error => array( attributes => array(escape => false) ) ));

To override the model error messages use an array with the keys matching the validation rule names:
$this->Form->input(Model.field, array( error => array(tooShort => __(This is not long enough)) ));

As seen above you can set the error message for each validation rule you have in your models. In addition you can provide i18n messages for your forms. New in version 2.3: Support for the errorMessage option was added in 2.3

More about Views

157

CakePHP Cookbook Documentation, Release 2.x

$options[before], $options[after]

$options[between],

$options[separator],

and

Use these keys if you need to inject some markup inside the output of the input() method:
echo $this->Form->input(field, array( before => --before--, after => --after--, between => --between--- ));

Output:
<div class="input"> --before-<label for="UserField">Field</label> --between--<input name="data[User][field]" type="text" value="" id="UserField" /> --after-</div>

For radio inputs the separator attribute can be used to inject markup to separate each input/label pair:
echo $this->Form->input(field, array( before => --before--, after => --after--, between => --between---, separator => --separator--, options => array(1, 2) ));

Output:
<div class="input"> --before-<input name="data[User][field]" type="radio" value="1" id="UserField1" /> <label for="UserField1">1</label> --separator-<input name="data[User][field]" type="radio" value="2" id="UserField2" /> <label for="UserField2">2</label> --between----after-</div>

For date and datetime type elements the separator attribute can be used to change the string between select elements. Defaults to -. $options[format] The ordering of the html generated FormHelper is controllable as well. The format options supports an array of strings describing the template you would like said element to follow. The supported array keys are: array(before, input, between, label, after,error). $options[inputDefaults] If you nd yourself repeating the same options in multiple input() calls, you can use inputDefaults to keep your code dry:

158

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

echo $this->Form->create(User, array( inputDefaults => array( label => false, div => false ) ));

All inputs created from that point forward would inherit the options declared in inputDefaults. You can override the defaultOptions by declaring the option in the input() call:
// No div, no label echo $this->Form->input(password); // has a label element echo $this->Form->input(username, array(label => Username));

If you need to later change the defaults you can use FormHelper::inputDefaults().
Generating specic types of inputs

In addition to the generic input() method, FormHelper has specic methods for generating a number of different types of inputs. These can be used to generate just the input widget itself, and combined with other methods like label() and error() to generate fully custom form layouts. Common options Many of the various input element methods support a common set of options. All of these options are also supported by input(). To reduce repetition the common options shared by all input methods are as follows: $options[class] You can set the classname for an input:
echo $this->Form->input(title, array(class => custom-class));

$options[id] Set this key to force the value of the DOM id for the input. $options[default] Used to set a default value for the input eld. The value is used if the data passed to the form does not contain a value for the eld (or if no data is passed at all). Example usage:
echo $this->Form->input(ingredient, array(default => Sugar));

Example with select eld (Size Medium will be selected as default):

$sizes = array(s => Small, m => Medium, l => Large); echo $this->Form->input(size, array(options => $sizes, default => m));

Note: You cannot use default to check a checkbox - instead you might set the value in $this->request->data in your controller, or set the input option checked to true. Date and datetime elds default values can be set by using the selected key.

More about Views

159

CakePHP Cookbook Documentation, Release 2.x

Beware of using false to assign a default value. A false value is used to disable/exclude options of an input eld, so default => false would not set any value at all. Instead use default => 0. In addition to the above options, you can mixin any html attribute you wish to use. Any non-special option name will be treated as an HTML attribute, and applied to the generated HTML input element. Options for select, checkbox and radio inputs $options[selected] Used in combination with a select-type input (i.e. For types select, date, time, datetime). Set selected to the value of the item you wish to be selected by default when the input is rendered:
echo $this->Form->input(close_time, array( type => time, selected => 13:30:00 ));

Note: The selected key for date and datetime inputs may also be a UNIX timestamp. $options[empty] If set to true, forces the input to remain empty. When passed to a select list, this creates a blank option with an empty value in your drop down list. If you want to have a empty value with text displayed instead of just a blank option, pass in a string to empty:
echo $this->Form->input(field, array( options => array(1, 2, 3, 4, 5), empty => (choose one) ));

Output:
<div class="input"> <label for="UserField">Field</label> <select name="data[User][field]" id="UserField"> <option value="">(choose one)</option> <option value="0">1</option> <option value="1">2</option> <option value="2">3</option> <option value="3">4</option> <option value="4">5</option> </select> </div>

Note: If you need to set the default value in a password eld to blank, use value => instead. Options can also supplied as key-value pairs.

160

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

$options[hiddenField] For certain input types (checkboxes, radios) a hidden input is created so that the key in $this->request->data will exist even without a value specied:
<input type="hidden" name="data[Post][Published]" id="PostPublished_" value="0" /> <input type="checkbox" name="data[Post][Published]" value="1" id="PostPublished" />

This can be disabled by setting the $options[hiddenField] = false:

echo $this->Form->checkbox(published, array(hiddenField => false));

Which outputs:
<input type="checkbox" name="data[Post][Published]" value="1" id="PostPublished" />

If you want to create multiple blocks of inputs on a form that are all grouped together, you should use this parameter on all inputs except the rst. If the hidden input is on the page in multiple places, only the last group of inputs values will be saved In this example, only the tertiary colors would be passed, and the primary colors would be overridden:
<h2>Primary Colors</h2> <input type="hidden" name="data[Color][Color]" id="Colors_" value="0" /> <input type="checkbox" name="data[Color][Color][]" value="5" id="ColorsRed" /> <label for="ColorsRed">Red</label> <input type="checkbox" name="data[Color][Color][]" value="5" id="ColorsBlue" /> <label for="ColorsBlue">Blue</label> <input type="checkbox" name="data[Color][Color][]" value="5" id="ColorsYellow" /> <label for="ColorsYellow">Yellow</label> <h2>Tertiary Colors</h2> <input type="hidden" name="data[Color][Color]" id="Colors_" value="0" /> <input type="checkbox" name="data[Color][Color][]" value="5" id="ColorsGreen" /> <label for="ColorsGreen">Green</label> <input type="checkbox" name="data[Color][Color][]" value="5" id="ColorsPurple" /> <label for="ColorsPurple">Purple</label> <input type="checkbox" name="data[Addon][Addon][]" value="5" id="ColorsOrange" /> <label for="ColorsOrange">Orange</label>

Disabling the hiddenField on the second input group would prevent this behavior. You can set a different hidden eld value other than 0 such as N:
echo $this->Form->checkbox(published, array( value => Y, hiddenField => N, ));

Datetime options $options[timeFormat] Used to specify the format of the select inputs for a time-related set of inputs. Valid values include 12, 24, and null. $options[dateFormat] Used to specify the format of the select inputs for a date-related set of inputs. Valid values include any combination of D, M and Y or null. The inputs will be put More about Views 161

CakePHP Cookbook Documentation, Release 2.x

in the order dened by the dateFormat option. $options[minYear], $options[maxYear] Used in combination with a date/datetime input. Denes the lower and/or upper end of values shown in the years select eld. $options[orderYear] Used in combination with a date/datetime input. Denes the order in which the year values will be set. Valid values include asc, desc. The default value is desc. $options[interval] This option species the number of minutes between each option in the minutes select box:
echo $this->Form->input(Model.time, array( type => time, interval => 15 ));

Would create 4 options in the minute select. One for each 15 minutes. $options[round] Can be set to up or down to force rounding in either direction. Defaults to null which rounds half up according to interval. New in version 2.4.
Form Element-Specic Methods

FormHelper::label(string $eldName, string $text, array $options) Create a label element. $fieldName is used for generating the DOM id. If $text is undened, $fieldName will be used to inect the labels text:
echo $this->Form->label(User.name); echo $this->Form->label(User.name, Your username);

Output:
<label for="UserName">Name</label> <label for="UserName">Your username</label>

$options can either be an array of html attributes, or a string that will be used as a classname:
echo $this->Form->label(User.name, null, array(id => user-label)); echo $this->Form->label(User.name, Your username, highlight);

Output:
<label for="UserName" id="user-label">Name</label> <label for="UserName" class="highlight">Your username</label>

FormHelper::text(string $name, array $options) The rest of the methods available in the FormHelper are for creating specic form elements. Many of these methods also make use of a special $options parameter. In this case, however, $options is used primarily to specify HTML tag attributes (such as the value or DOM id of an element in the form):
echo $this->Form->text(username, array(class => users));

162

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

Will output:
<input name="data[User][username]" type="text" class="users" id="UserUsername" />

FormHelper::password(string $eldName, array $options) Creates a password eld.:

echo $this->Form->password(password);

Will output:
<input name="data[User][password]" value="" id="UserPassword" type="password" />

FormHelper::hidden(string $eldName, array $options) Creates a hidden form input. Example:

echo $this->Form->hidden(id);

Will output:
<input name="data[User][id]" value="10" id="UserId" type="hidden" />

Changed in version 2.0: Hidden elds no longer remove the class attribute. This means that if there are validation errors on hidden elds, the error-eld classname will be applied. FormHelper::textarea(string $eldName, array $options) Creates a textarea input eld.:
echo $this->Form->textarea(notes);

Will output:
<textarea name="data[User][notes]" id="UserNotes"></textarea>

Note: The textarea input type allows for the $options attribute of escape which determines whether or not the contents of the textarea should be escaped. Defaults to true.
echo $this->Form->textarea(notes, array(escape => false); // OR.... echo $this->Form->input(notes, array(type => textarea, escape => false);

Options In addition to the Common options, textarea() supports a few specic options: $options[rows], $options[cols] These two keys specify the number of rows and columns:
echo $this->Form->textarea(textarea, array(rows => 5, cols => 5));

Output:

More about Views

163

CakePHP Cookbook Documentation, Release 2.x

<textarea name="data[Form][textarea]" cols="5" rows="5" id="FormTextarea"> </textarea>

FormHelper::checkbox(string $eldName, array $options) Creates a checkbox form element. This method also generates an associated hidden form input to force the submission of data for the specied eld.:
echo $this->Form->checkbox(done);

Will output:
<input type="hidden" name="data[User][done]" value="0" id="UserDone_" /> <input type="checkbox" name="data[User][done]" value="1" id="UserDone" />

It is possible to specify the value of the checkbox by using the $options array:
echo $this->Form->checkbox(done, array(value => 555));

Will output:
<input type="hidden" name="data[User][done]" value="0" id="UserDone_" /> <input type="checkbox" name="data[User][done]" value="555" id="UserDone" />

If you dont want the Form helper to create a hidden input:

echo $this->Form->checkbox(done, array(hiddenField => false));

Will output:
<input type="checkbox" name="data[User][done]" value="1" id="UserDone" />

FormHelper::radio(string $eldName, array $options, array $attributes) Creates a set of radio button inputs. Options $attributes[value] to set which value should be selected default. $attributes[separator] to specify HTML in between radio buttons (e.g. <br />). $attributes[between] specify some content to be inserted between the legend and rst element. $attributes[disabled] Setting this to true or disabled will disable all of the generated radio buttons. $attributes[legend] Radio elements are wrapped with a label and eldset by default. Set $attributes[legend] to false to remove them.:
$options = array(M => Male, F => Female); $attributes = array(legend => false); echo $this->Form->radio(gender, $options, $attributes);

Will output:

164

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

<input <input <label <input <label

name="data[User][gender]" id="UserGender_" value="" type="hidden" /> name="data[User][gender]" id="UserGenderM" value="M" type="radio" /> for="UserGenderM">Male</label> name="data[User][gender]" id="UserGenderF" value="F" type="radio" /> for="UserGenderF">Female</label>

If for some reason you dont want the hidden input, setting $attributes[value] to a selected value or boolean false will do just that. Changed in version 2.1: The $attributes[disabled] option was added in 2.1. FormHelper::select(string $eldName, array $options, array $attributes) Creates a select element, populated with the items in $options, with the option specied by $attributes[value] shown as selected by default. Set to false the the empty key in the $attributes variable to turn off the default empty option:
$options = array(M => Male, F => Female); echo $this->Form->select(gender, $options);

Will output:
<select name="data[User][gender]" id="UserGender"> <option value=""></option> <option value="M">Male</option> <option value="F">Female</option> </select>

The select input type allows for a special $option attribute called escape which accepts a bool and determines whether to HTML entity encode the contents of the select options. Defaults to true:
$options = array(M => Male, F => Female); echo $this->Form->select(gender, $options, array(escape => false));

$attributes[options] This key allows you to manually specify options for a select input, or for a radio group. Unless the type is specied as radio, the FormHelper will assume that the target output is a select input:
echo $this->Form->select(field, array(1,2,3,4,5));

Output:
<select name="data[User][field]" id="UserField"> <option value="0">1</option> <option value="1">2</option> <option value="2">3</option> <option value="3">4</option> <option value="4">5</option> </select>

Options can also be supplied as key-value pairs:

echo $this->Form->select(field, array( Value 1 => Label 1,

More about Views

165

CakePHP Cookbook Documentation, Release 2.x

Value 2 => Label 2, Value 3 => Label 3 ));

Output:
<select name="data[User][field]" id="UserField"> <option value="Value 1">Label 1</option> <option value="Value 2">Label 2</option> <option value="Value 3">Label 3</option> </select>

If you would like to generate a select with optgroups, just pass data in hierarchical format. This works on multiple checkboxes and radio buttons too, but instead of optgroups wraps elements in eldsets:
$options = array( Group 1 => array( Value 1 => Label 1, Value 2 => Label 2 ), Group 2 => array( Value 3 => Label 3 ) ); echo $this->Form->select(field, $options);

Output:
<select name="data[User][field]" id="UserField"> <optgroup label="Group 1"> <option value="Value 1">Label 1</option> <option value="Value 2">Label 2</option> </optgroup> <optgroup label="Group 2"> <option value="Value 3">Label 3</option> </optgroup> </select>

$attributes[multiple] If multiple has been set to true for an input that outputs a select, the select will allow multiple selections:
echo $this->Form->select(Model.field, $options, array(multiple => true));

Alternatively set multiple to checkbox to output a list of related check boxes:

$options = array( Value 1 => Label 1, Value 2 => Label 2 ); echo $this->Form->select(Model.field, $options, array( multiple => checkbox ));

166

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

Output:

<div class="input select"> <label for="ModelField">Field</label> <input name="data[Model][field]" value="" id="ModelField" type="hidden"> <div class="checkbox"> <input name="data[Model][field][]" value="Value 1" id="ModelField1" type="ch <label for="ModelField1">Label 1</label> </div> <div class="checkbox"> <input name="data[Model][field][]" value="Value 2" id="ModelField2" type="ch <label for="ModelField2">Label 2</label> </div> </div>

$attributes[disabled] When creating checkboxes, this option can be set to disable all or some checkboxes. To disable all checkboxes set disabled to true:
$options = array( Value 1 => Label 1, Value 2 => Label 2 ); echo $this->Form->select(Model.field, $options, array( multiple => checkbox, disabled => array(Value 1) ));

Output:

<div class="input select"> <label for="ModelField">Field</label> <input name="data[Model][field]" value="" id="ModelField" type="hidden"> <div class="checkbox"> <input name="data[Model][field][]" disabled="disabled" value="Value 1" id="M <label for="ModelField1">Label 1</label> </div> <div class="checkbox"> <input name="data[Model][field][]" value="Value 2" id="ModelField2" type="ch <label for="ModelField2">Label 2</label> </div> </div>

Changed in version 2.3: Support for arrays in $attributes[disabled] was added in 2.3. FormHelper::file(string $eldName, array $options) To add a le upload eld to a form, you must rst make sure that the form enctype is set to multipart/form-data, so start off with a create function such as the following:
echo $this->Form->create(Document, array(enctype => multipart/form-data)); // OR echo $this->Form->create(Document, array(type => file));

Next add either of the two lines to your form view le:

More about Views

167

CakePHP Cookbook Documentation, Release 2.x

echo $this->Form->input(Document.submittedfile, array( between => <br />, type => file )); // OR echo $this->Form->file(Document.submittedfile);

Due to the limitations of HTML itself, it is not possible to put default values into input elds of type le. Each time the form is displayed, the value inside will be empty. Upon submission, le elds provide an expanded data array to the script receiving the form data. For the example above, the values in the submitted data array would be organized as follows, if the CakePHP was installed on a Windows server. tmp_name will have a different path in a Unix environment:
$this->request->data[Document][submittedfile] = array( name => conference_schedule.pdf, type => application/pdf, tmp_name => C:/WINDOWS/TEMP/php1EE.tmp, error => 0, size => 41737, );

This array is generated by PHP itself, so for more detail on the way PHP handles data passed via le elds read the PHP manual section on le uploads (http://php.net/features.le-upload). Validating Uploads Below is an example validation method you could dene in your model to validate whether a le has been successfully uploaded:
public function isUploadedFile($params) { $val = array_shift($params); if ((isset($val[error]) && $val[error] == 0) || (!empty( $val[tmp_name]) && $val[tmp_name] != none) ) { return is_uploaded_file($val[tmp_name]); } return false; }

Creates a le input:
echo $this->Form->create(User, array(type => file)); echo $this->Form->file(avatar);

Will output:
<form enctype="multipart/form-data" method="post" action="/users/add"> <input name="data[User][avatar]" value="" id="UserAvatar" type="file">

168

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

Note: When using $this->Form->file(), remember to set the form encoding-type, by setting the type option to le in $this->Form->create()

Creating buttons and submit elements

FormHelper::submit(string $caption, array $options) Creates a submit button with caption $caption. If the supplied $caption is a URL to an image (it contains a . character), the submit button will be rendered as an image. It is enclosed between div tags by default; you can avoid this by declaring $options[div] = false:
echo $this->Form->submit();

Will output:
<div class="submit"><input value="Submit" type="submit"></div>

You can also pass a relative or absolute url to an image for the caption parameter instead of caption text.:
echo $this->Form->submit(ok.png);

Will output:
<div class="submit"><input type="image" src="/img/ok.png"></div>

FormHelper::button(string $title, array $options = array()) Creates an HTML button with the specied title and a default type of button. $options[type] will output one of the three possible button types: 1.submit: Same as the $this->Form->submit method - (the default). 2.reset: Creates a form reset button. 3.button: Creates a standard push button.
echo echo echo echo

Setting

$this->Form->button(A Button); $this->Form->button(Another Button, array(type => button)); $this->Form->button(Reset the Form, array(type => reset)); $this->Form->button(Submit Form, array(type => submit));

Will output:
<button <button <button <button type="submit">A Button</button> type="button">Another Button</button> type="reset">Reset the Form</button> type="submit">Submit Form</button>

The button input type supports the escape option, which accepts a bool and determines whether to HTML entity encode the $title of the button. Defaults to false:

More about Views

169

CakePHP Cookbook Documentation, Release 2.x

echo $this->Form->button(Submit Form, array(type => submit, escape => true));

FormHelper::postButton(string $title, mixed $url, array $options = array ()) Create a <button> tag with a surrounding <form> that submits via POST. This method creates a <form> element. So do not use this method in some opened form. Instead use FormHelper::submit() or FormHelper::button() to create buttons inside opened forms. FormHelper::postLink(string $title, mixed $url = null, array $options = array (), string $conrmMessage = false) Creates an HTML link, but access the url using method POST. Requires javascript to be enabled in browser. This method creates a <form> element. So do not use this method inside an existing form. Instead you should add a submit button using FormHelper::submit() Changed in version 2.3: The method option was added.
Creating date and time inputs

FormHelper::dateTime($eldName, $dateFormat = DMY, $timeFormat = 12, $attributes = array()) Creates a set of select inputs for date and time. Valid values for $dateformat are DMY, MDY, YMD or NONE. Valid values for $timeFormat are 12, 24, and null. You can specify not to display empty values by setting array(empty => false) in the attributes parameter. It will also pre-select the elds with the current datetime. FormHelper::year(string $eldName, int $minYear, int $maxYear, array $attributes) Creates a select element populated with the years from $minYear to $maxYear. HTML attributes may be supplied in $attributes. If $attributes[empty] is false, the select will not include an empty option:
echo $this->Form->year(purchased, 2000, date(Y));

Will output:
<select name="data[User][purchased][year]" id="UserPurchasedYear"> <option value=""></option> <option value="2009">2009</option> <option value="2008">2008</option> <option value="2007">2007</option> <option value="2006">2006</option> <option value="2005">2005</option> <option value="2004">2004</option> <option value="2003">2003</option> <option value="2002">2002</option> <option value="2001">2001</option> <option value="2000">2000</option> </select>

170

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

FormHelper::month(string $eldName, array $attributes) Creates a select element populated with month names:
echo $this->Form->month(mob);

Will output:
<select name="data[User][mob][month]" id="UserMobMonth"> <option value=""></option> <option value="01">January</option> <option value="02">February</option> <option value="03">March</option> <option value="04">April</option> <option value="05">May</option> <option value="06">June</option> <option value="07">July</option> <option value="08">August</option> <option value="09">September</option> <option value="10">October</option> <option value="11">November</option> <option value="12">December</option> </select>

You can pass in your own array of months to be used by setting the monthNames attribute, or have months displayed as numbers by passing false. (Note: the default months are internationalized and can be translated using localization.):
echo $this->Form->month(mob, null, array(monthNames => false));

FormHelper::day(string $eldName, array $attributes) Creates a select element populated with the (numerical) days of the month. To create an empty option with prompt text of your choosing (e.g. the rst option is Day), you can supply the text as the nal parameter as follows:
echo $this->Form->day(created);

Will output:
<select name="data[User][created][day]" id="UserCreatedDay"> <option value=""></option> <option value="01">1</option> <option value="02">2</option> <option value="03">3</option> ... <option value="31">31</option> </select>

FormHelper::hour(string $eldName, boolean $format24Hours, array $attributes) Creates a select element populated with the hours of the day. FormHelper::minute(string $eldName, array $attributes) Creates a select element populated with the minutes of the hour.

More about Views

171

CakePHP Cookbook Documentation, Release 2.x

FormHelper::meridian(string $eldName, array $attributes) Creates a select element populated with am and pm.
Displaying and checking errors

FormHelper::error(string $eldName, mixed $text, array $options) Shows a validation error message, specied by $text, for the given eld, in the event that a validation error has occurred. Options: escape bool Whether or not to html escape the contents of the error. wrap mixed Whether or not the error message should be wrapped in a div. If a string, will be used as the HTML tag to use. class string The classname for the error message FormHelper::isFieldError(string $eldName) Returns true if the supplied $eldName has an active validation error.:
if ($this->Form->isFieldError(gender)) { echo $this->Form->error(gender); }

Note: When using FormHelper::input(), errors are rendered by default. FormHelper::tagIsInvalid() Returns false if given form eld described by the current entity has no errors. Otherwise it returns the validation message.
Setting Defaults for all elds

New in version 2.2. You can declare a set of default options for input() using FormHelper::inputDefaults(). Changing the default options allows you to consolidate repeated options into a single method call:
$this->Form->inputDefaults(array( label => false, div => false, class => fancy ) );

All inputs created from that point forward will inherit the options declared in inputDefaults. You can override the default options by declaring the option in the input() call:

echo $this->Form->input(password); // No div, no label with class fancy echo $this->Form->input(username, array(label => Username)); // has a label element s

172

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

Working with SecurityComponent

SecurityComponent offers several features that make your forms safer and more secure. By simply including the SecurityComponent in your controller, youll automatically benet from CSRF and form tampering features. As mentioned previously when using SecurityComponent, you should always close your forms using FormHelper::end(). This will ensure that the special _Token inputs are generated. FormHelper::unlockField($name) Unlocks a eld making it exempt from the SecurityComponent eld hashing. This also allows the elds to be manipulated by Javascript. The $name parameter should be the entity name for the input:
$this->Form->unlockField(User.id);

FormHelper::secure(array $elds = array()) Generates a hidden eld with a security hash based on the elds used in the form.
2.0 updates

$selected parameter removed The $selected parameter was removed from several methods in FormHelper. All methods now support a $attributes[value] key now which should be used in place of $selected. This change simplies the FormHelper methods, reducing the number of arguments, and reduces the duplication that $selected created. The effected methods are: FormHelper::select() FormHelper::dateTime() FormHelper::year() FormHelper::month() FormHelper::day() FormHelper::hour() FormHelper::minute() FormHelper::meridian() Default urls on forms is the current action The default url for all forms, is now the current url including passed, named, and querystring parameters. You can override this default by supplying $options[url] in the second parameter of $this->Form->create() FormHelper::hidden() Hidden elds no longer remove the class attribute. This means that if there are validation errors on hidden elds, the error-eld classname will be applied.

More about Views

173

CakePHP Cookbook Documentation, Release 2.x

HtmlHelper class HtmlHelper(View $view, array $settings = array()) The role of the HtmlHelper in CakePHP is to make HTML-related options easier, faster, and more resilient to change. Using this helper will enable your application to be more light on its feet, and more exible on where it is placed in relation to the root of a domain. Many HtmlHelper methods include a $htmlAttributes parameter, that allow you to tack on any extra attributes on your tags. Here are a few examples of how to use the $htmlAttributes parameter:
Desired attributes: <tag class="someClass" /> Array parameter: array(class => someClass) Desired attributes: <tag name="foo" value="bar" /> Array parameter: array(name => foo, value => bar)

Note: The HtmlHelper is available in all views by default. If youre getting an error informing you that it isnt there, its usually due to its name being missing from a manually congured $helpers controller variable.

Inserting Well-Formatted elements

The most important task the HtmlHelper accomplishes is creating well formed markup. Dont be afraid to use it often - you can cache views in CakePHP in order to save some CPU cycles when views are being rendered and delivered. This section will cover some of the methods of the HtmlHelper and how to use them. HtmlHelper::charset($charset=null) Parameters $charset (string) Desired character set. If null, the value of App.encoding will be used. Used to create a meta tag specifying the documents character. Defaults to UTF-8 Example use:
echo $this->Html->charset();

Will output:
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />

Alternatively,
echo $this->Html->charset(ISO-8859-1);

Will output:

174

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />

HtmlHelper::css(mixed $path, array $options = array()) Changed in version 2.4. Parameters $path (mixed) Either a string of the css le to link, or an array with multiple les $options (array) An array of options or html attributes. Creates a link(s) to a CSS style-sheet. If key inline is set to false in $options parameter, the link tags are added to the css block which you can print inside the head tag of the document. You can use the block option to control which block the link element will be appended to. By default it will append to the css block. If key rel in $options array is set to import the stylesheet will be imported. This method of CSS inclusion assumes that the CSS le specied resides inside the /app/webroot/css directory if path doesnt start with a /.:
echo $this->Html->css(forms);

Will output:
<link rel="stylesheet" type="text/css" href="/css/forms.css" />

The rst parameter can be an array to include multiple les.:

echo $this->Html->css(array(forms, tables, menu));

Will output:
<link rel="stylesheet" type="text/css" href="/css/forms.css" /> <link rel="stylesheet" type="text/css" href="/css/tables.css" /> <link rel="stylesheet" type="text/css" href="/css/menu.css" />

You can include css les from any loaded plugin using plugin syntax. To include app/Plugin/DebugKit/webroot/css/toolbar.css You could use the following:
echo $this->Html->css(DebugKit.toolbar.css);

If you want to include a css le which shares a name with a loaded plugin you can do the following. For example if you had a Blog plugin, and also wanted to include app/webroot/css/Blog.common.css, you would:
echo $this->Html->css(Blog.common.css, null, array(plugin => false));

Changed in version 2.1: The block option was added. Support for plugin syntax was added. HtmlHelper::meta(string $type, string $url = null, array $options = array()) Parameters $type (string) The type meta tag you want. More about Views 175

CakePHP Cookbook Documentation, Release 2.x

$url (mixed) The url for the meta tag, either a string or a routing array. $options (array) An array of html attributes. This method is handy for linking to external resources like RSS/Atom feeds and favicons. Like css(), you can specify whether or not youd like this tag to appear inline or appended to the meta block by setting the inline key in the $attributes parameter to false, ie - array(inline => false). If you set the type attribute using the $attributes parameter, CakePHP contains a few shortcuts: type html rss atom icon translated value text/html application/rss+xml application/atom+xml image/x-icon

<?php echo $this->Html->meta( favicon.ico, /favicon.ico, array(type => icon) ); ?> // Output (line breaks added) <link href="http://example.com/favicon.ico" title="favicon.ico" type="image/x-icon" rel="alternate" /> <?php echo $this->Html->meta( Comments, /comments/index.rss, array(type => rss) ); ?> // Output (line breaks added) <link href="http://example.com/comments/index.rss" title="Comments" type="application/rss+xml" rel="alternate" />

This method can also be used to add the meta keywords and descriptions. Example:
<?php echo $this->Html->meta( keywords, enter any meta keyword here ); ?> // Output <meta name="keywords" content="enter any meta keyword here" />

176

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

<?php echo $this->Html->meta( description, enter any meta description here ); ?> // Output <meta name="description" content="enter any meta description here" />

If you want to add a custom meta tag then the rst parameter should be set to an array. To output a robots noindex tag use the following code:
echo $this->Html->meta(array(name => robots, content => noindex));

Changed in version 2.1: The block option was added. HtmlHelper::docType(string $type = xhtml-strict) Parameters $type (string) The type of doctype being made. Returns a (X)HTML doctype tag. Supply the doctype according to the following table: type html4-strict html4-trans html4-frame html5 xhtml-strict xhtml-trans xhtml-frame xhtml11 translated value HTML4 Strict HTML4 Transitional HTML4 Frameset HTML5 XHTML1 Strict XHTML1 Transitional XHTML1 Frameset XHTML1.1

echo $this->Html->docType(); // Outputs: <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.or echo $this->Html->docType(html5); // Outputs: <!DOCTYPE html>

echo $this->Html->docType(html4-trans); // Outputs: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www

Changed in version 2.1: The default doctype is html5 in 2.1. HtmlHelper::style(array $data, boolean $oneline = true) Parameters $data (array) A set of key => values with CSS properties. $oneline (boolean) Should the contents be on one line. Builds CSS style denitions based on the keys and values of the array passed to the method. Especially handy if your CSS le is dynamic.:

More about Views

177

CakePHP Cookbook Documentation, Release 2.x

echo $this->Html->style(array( background => #633, border-bottom => 1px solid #000, padding => 10px ));

Will output:
background:#633; border-bottom:1px solid #000; padding:10px;

HtmlHelper::image(string $path, array $options = array()) Parameters $path (string) Path to the image. $options (array) An array of html attributes. Creates a formatted image tag. The path supplied should be relative to /app/webroot/img/.:
echo $this->Html->image(cake_logo.png, array(alt => CakePHP));

Will output:
<img src="/img/cake_logo.png" alt="CakePHP" />

To create an image link specify the link destination using the url option in $htmlAttributes.:
echo $this->Html->image("recipes/6.jpg", array( "alt" => "Brownies", url => array(controller => recipes, action => view, 6) ));

Will output:
<a href="/recipes/view/6"> <img src="/img/recipes/6.jpg" alt="Brownies" /> </a>

If you are creating images in emails, or want absolute paths to images you can use the fullBase option:
echo $this->Html->image("logo.png", array(fullBase => true));

Will output:
<img src="http://example.com/img/logo.jpg" alt="" />

You can include image les from any loaded plugin using plugin syntax. To include app/Plugin/DebugKit/webroot/img/icon.png You could use the following:
echo $this->Html->image(DebugKit.icon.png);

If you want to include a image le which shares a name with a loaded plugin you can do the following. For example if you had a Blog plugin, and also wanted to include app/webroot/js/Blog.icon.png, you would: 178 Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

echo $this->Html->image(Blog.icon.png, array(plugin => false));

Changed in version 2.1: The fullBase option was added. Support for plugin syntax was added. HtmlHelper::link(string $title, mixed $url = null, array $options = array(), string $conrmMessage = false) param string $title The text to display as the body of the link. param mixed $url Either the string location, or a routing array. param array $options An array of html attributes. General purpose method for creating HTML links. Use $options to specify attributes for the element and whether or not the $title should be escaped.:

echo $this->Html->link(Enter, /pages/home, array(class => button, target

Will output:
<a href="/pages/home" class="button" target="_blank">Enter</a>

Use full_base=>true option for absolute URLs:

echo $this->Html->link( Dashboard, array(controller => dashboards, action => index, full_base => true) );

Will output:
<a href="http://www.yourdomain.com/dashboards/index">Dashboard</a>

Specify $confirmMessage to display a javascript confirm() dialog:

echo $this->Html->link( Delete, array(controller => recipes, action => delete, 6), array(), "Are you sure you wish to delete this recipe?" );

Will output:

<a href="/recipes/delete/6" onclick="return confirm(Are you sure you wish to dele

Query strings can also be created with link().:

echo $this->Html->link(View image, array( controller => images, action => view, 1, ? => array(height => 400, width => 500)) );

Will output: More about Views 179

CakePHP Cookbook Documentation, Release 2.x

<a href="/images/view/1?height=400&width=500">View image</a>

When using named parameters, use the array syntax and include names for ALL parameters in the URL. Using the string syntax for paramters (i.e. recipes/view/6/comments:false will result in the colon characters being HTML escaped and the link will not work as desired. <?php echo $this->Html->link( $this->Html->image(recipes/6.jpg, array(alt => Brownies)), array(controller => recipes, action => view, id => 6, comments => false) ); Will output:
<a href="/recipes/view/id:6/comments:false"> <img src="/img/recipes/6.jpg" alt="Brownies" /> </a>

HTML special characters in $title will be converted to HTML entities. To disable this conversion, set the escape option to false in the $options array.:
<?php echo $this->Html->link( $this->Html->image("recipes/6.jpg", array("alt" => "Brownies")), "recipes/view/6", array(escape => false) );

Will output:
<a href="/recipes/view/6"> <img src="/img/recipes/6.jpg" alt="Brownies" /> </a>

Setting escape to false will also disable escaping of attributes of the link. As of 2.4 you can use the option escapeTitle to disable just escaping of title and not the attributes.:
<?php echo $this->Html->link( $this->Html->image(recipes/6.jpg, array(alt => Brownies)), recipes/view/6, array(escapeTitle => false, title => hi "howdy") );

Will output:
<a href="/recipes/view/6" title="hi "howdy""> <img src="/img/recipes/6.jpg" alt="Brownies" /> </a>

Changed in version 2.4: The escapeTitle option was added. Also check HtmlHelper::url method for more examples of different types of urls. 180 Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

HtmlHelper::media(string|array $path, array $options) Parameters $path (string|array) Path to the video le, relative to the webroot/{$options[pathPrex]} directory. Or an array where each item itself can be a path string or an associate array containing keys src and type. $options (array) Array of HTML attributes, and special options. Options: type Type of media element to generate, valid values are audio or video. If type is not provided media type is guessed based on les mime type. text Text to include inside the video tag pathPrex Path prex to use for relative urls, defaults to les/ fullBase If provided the src attribute will get a full address including domain name New in version 2.1. Returns a formatted audio/video tag:
<?php echo $this->Html->media(audio.mp3); ?> // Output <audio src="/files/audio.mp3"></audio> <?php echo $this->Html->media(video.mp4, array( fullBase => true, text => Fallback text )); ?> // Output <video src="http://www.somehost.com/files/video.mp4">Fallback text</video>

<?php echo $this->Html->media( array(video.mp4, array(src => video.ogg, type => "video/ogg; codecs=theo array(autoplay) ); ?> // Output <video autoplay="autoplay"> <source src="/files/video.mp4" type="video/mp4"/> <source src="/files/video.ogg" type="video/ogg; codecs=theora, vorbis"/> </video>

HtmlHelper::tag(string $tag, string $text, array $htmlAttributes) Parameters $tag (string) The tag name being generated. $text (string) The contents for the tag. $options (array) An array of html attributes.

More about Views

181

CakePHP Cookbook Documentation, Release 2.x

Returns text wrapped in a specied tag. If no text is specied then only the opening <tag> is returned.:
<?php echo $this->Html->tag(span, Hello World., array(class => welcome)); ?> // Output <span class="welcome">Hello World</span> // No text specified. <?php echo $this->Html->tag(span, null, array(class => welcome)); ?> // Output <span class="welcome">

Note: Text is not escaped by default but you may use $htmlOptions[escape] = true to escape your text. This replaces a fourth parameter boolean $escape = false that was available in previous versions. HtmlHelper::div(string $class, string $text, array $options) Parameters $class (string) The classname for the div. $text (string) The content inside the div. $options (array) An array of html attributes. Used for creating div-wrapped sections of markup. The rst parameter species a CSS class, and the second is used to supply the text to be wrapped by div tags. If the last parameter has been set to true, $text will be printed HTML-escaped. If no text is specied, only an opening div tag is returned.:
<?php echo $this->Html->div(error, Please enter your credit card number.); ?> // Output <div class="error">Please enter your credit card number.</div>

HtmlHelper::para(string $class, string $text, array $options) Parameters $class (string) The classname for the paragraph. $text (string) The content inside the paragraph. $options (array) An array of html attributes.

182

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

Returns a text wrapped in a CSS-classed <p> tag. If no text is supplied, only a starting <p> tag is returned.:
<?php echo $this->Html->para(null, Hello World.); ?> // Output <p>Hello World.</p>

HtmlHelper::script(mixed $url, mixed $options) Parameters $url (mixed) Either a string to a single Javascript le, or an array of strings for multiple les. $options (array) An array of html attributes. Include a script le(s), contained either locally or as a remote url. By default, script tags are added to the document inline. If you override this by setting $options[inline] to false, the script tags will instead be added to the script block which you can print elsewhere in the document. If you wish to override which block name is used, you can do so by setting $options[block]. $options[once] controls whether or not you want to include this script once per request or more than once. This defaults to true. You can use $options to set additional properties to the generated script tag. If an array of script tags is used, the attributes will be applied to all of the generated script tags. This method of javascript le inclusion assumes that the javascript le specied resides inside the /app/webroot/js directory:
echo $this->Html->script(scripts);

Will output:
<script type="text/javascript" href="/js/scripts.js"></script>

You can link to les with absolute paths as well to link les that are not in app/webroot/js:
echo $this->Html->script(/otherdir/script_file);

You can also link to a remote URL:

echo $this->Html->script(http://code.jquery.com/jquery.min.js);

Will output:
<script type="text/javascript" href="http://code.jquery.com/jquery.min.js"></script>

The rst parameter can be an array to include multiple les.:

More about Views

183

CakePHP Cookbook Documentation, Release 2.x

echo $this->Html->script(array(jquery, wysiwyg, scripts));

Will output:
<script type="text/javascript" href="/js/jquery.js"></script> <script type="text/javascript" href="/js/wysiwyg.js"></script> <script type="text/javascript" href="/js/scripts.js"></script>

You can append the script tag to a specic block using the block option:
echo $this->Html->script(wysiwyg, array(block => scriptBottom));

In your layout you can output all the script tags added to scriptBottom:
echo $this->fetch(scriptBottom);

You can include script les from any loaded plugin using plugin syntax. To include app/Plugin/DebugKit/webroot/js/toolbar.js You could use the following:
echo $this->Html->script(DebugKit.toolbar.js);

If you want to include a script le which shares a name with a loaded plugin you can do the following. For example if you had a Blog plugin, and also wanted to include app/webroot/js/Blog.plugins.js, you would:
echo $this->Html->script(Blog.plugins.js, array(plugin => false));

Changed in version 2.1: The block option was added. Support for plugin syntax was added. HtmlHelper::scriptBlock($code, $options = array()) Parameters $code (string) The code to go in the script tag. $options (array) An array of html attributes. Generate a code block containing $code set $options[inline] to false to have the script block appear in the script view block. Other options dened will be added as attributes to script tags. $this->Html->scriptBlock(stuff, array(defer => true)); will create a script tag with defer="defer" attribute. HtmlHelper::scriptStart($options = array()) Parameters $options (array) An array of html attributes to be used when scriptEnd is called. Begin a buffering code block. This code block will capture all output between scriptStart() and scriptEnd() and create an script tag. Options are the same as scriptBlock() HtmlHelper::scriptEnd() End a buffering script block, returns the generated script element or null if the script block was opened with inline = false. An example of using scriptStart() and scriptEnd() would be:

184

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

$this->Html->scriptStart(array(inline => false)); echo $this->Js->alert(I am in the javascript); $this->Html->scriptEnd();

HtmlHelper::nestedList(array $list, array $options = array(), array $itemOptions = array(), string $tag = ul) Parameters $list (array) Set of elements to list. $options (array) Additional HTML attributes of the list (ol/ul) tag or if ul/ol use that as tag. $itemOptions (array) Additional HTML attributes of the list item (LI) tag. $tag (string) Type of list tag to use (ol/ul). Build a nested list (UL/OL) out of an associative array:
$list = array( Languages => array( English => array( American, Canadian, British, ), Spanish, German, ) ); echo $this->Html->nestedList($list);

Output:
// Output (minus the whitespace) <ul> <li>Languages <ul> <li>English <ul> <li>American</li> <li>Canadian</li> <li>British</li> </ul> </li> <li>Spanish</li> <li>German</li> </ul> </li> </ul>

HtmlHelper::tableHeaders(array $names, array $trOptions = null, array $thOptions = null) More about Views 185

CakePHP Cookbook Documentation, Release 2.x

Parameters $names (array) An array of strings to create table headings. $trOptions (array) An array of html attributes for the <tr> $thOptions (array) An array of html attributes for the <th> elements Creates a row of table header cells to be placed inside of <table> tags.:
echo $this->Html->tableHeaders(array(Date, Title, Active));

Output:
<tr> <th>Date</th> <th>Title</th> <th>Active</th> </tr> echo $this->Html->tableHeaders( array(Date,Title,Active), array(class => status), array(class => product_table) );

Output:
<tr class="status"> <th class="product_table">Date</th> <th class="product_table">Title</th> <th class="product_table">Active</th> </tr>

Changed in version 2.2: tableHeaders() now accepts attributes per cell, see below. As of 2.2 you can set attributes per column, these are used instead of the defaults provided in the $thOptions:
echo $this->Html->tableHeaders(array( id, array(Name => array(class => highlight)), array(Date => array(class => sortable)) ));

Output:
<tr> <th>id</th> <th class="highlight">Name</th> <th class="sortable">Date</th> </tr>

HtmlHelper::tableCells(array $data, array $oddTrOptions = null, array $evenTrOptions = null, $useCount = false, $continueOddEven = true) Parameters $data (array) A two dimensional array with data for the rows. 186 Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

$oddTrOptions (array) An array of html attributes for the odd <tr>s. $evenTrOptions (array) An array of html attributes for the even <tr>s. $useCount (boolean) Adds class column-$i. $continueOddEven (boolean) If false, will use a non-static $count variable, so that the odd/even count is reset to zero just for that call. Creates table cells, in rows, assigning <tr> attributes differently for odd- and even-numbered rows. Wrap a single table cell within an array() for specic <td>-attributes.
echo $this->Html->tableCells(array( array(Jul 7th, 2007, Best Brownies, Yes), array(Jun 21st, 2007, Smart Cookies, Yes), array(Aug 1st, 2006, Anti-Java Cake, No), ));

Output:
<tr><td>Jul 7th, 2007</td><td>Best Brownies</td><td>Yes</td></tr> <tr><td>Jun 21st, 2007</td><td>Smart Cookies</td><td>Yes</td></tr> <tr><td>Aug 1st, 2006</td><td>Anti-Java Cake</td><td>No</td></tr>

echo $this->Html->tableCells(array( array(Jul 7th, 2007, array(Best Brownies, array(class => highlight)) , Ye array(Jun 21st, 2007, Smart Cookies, Yes), array(Aug 1st, 2006, Anti-Java Cake, array(No, array(id => special))), ));

Output:
<tr><td>Jul 7th, 2007</td><td class="highlight">Best Brownies</td><td>Yes</td></tr> <tr><td>Jun 21st, 2007</td><td>Smart Cookies</td><td>Yes</td></tr> <tr><td>Aug 1st, 2006</td><td>Anti-Java Cake</td><td id="special">No</td></tr> echo $this->Html->tableCells( array( array(Red, Apple), array(Orange, Orange), array(Yellow, Banana), ), array(class => darker) );

Output:
<tr class="darker"><td>Red</td><td>Apple</td></tr> <tr><td>Orange</td><td>Orange</td></tr> <tr class="darker"><td>Yellow</td><td>Banana</td></tr>

HtmlHelper::url(mixed $url = NULL, boolean $full = false) Parameters $url (mixed) A routing array. More about Views 187

CakePHP Cookbook Documentation, Release 2.x

$full (mixed) Either a boolean to indicate whether or not the base path should be included on an array of options for Router::url() Returns an URL pointing to a combination of controller and action. If $url is empty, it returns the REQUEST_URI, otherwise it generates the url for the controller and action combo. If full is true, the full base URL will be prepended to the result:
echo $this->Html->url(array( "controller" => "posts", "action" => "view", "bar" )); // Output /posts/view/bar

Here are a few more usage examples: URL with named parameters:
echo $this->Html->url(array( "controller" => "posts", "action" => "view", "foo" => "bar" )); // Output /posts/view/foo:bar

URL with extension:

echo $this->Html->url(array( "controller" => "posts", "action" => "list", "ext" => "rss" )); // Output /posts/list.rss

URL (starting with /) with the full base URL prepended:

echo $this->Html->url(/posts, true); // Output http://somedomain.com/posts

URL with GET params and named anchor:

echo $this->Html->url(array( "controller" => "posts", "action" => "search", "?" => array("foo" => "bar"), "#" => "first" ));

188

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

// Output /posts/search?foo=bar#first

For further information check Router::url (http://api20.cakephp.org/class/router#method-Routerurl) in the API. HtmlHelper::useTag(string $tag) Returns a formatted existent block of $tag:
$this->Html->useTag( form, http://example.com, array(method => post, class => myform) );

Output:
<form action="http://example.com" method="post" class="myform">

Changing the tags output by HtmlHelper

HtmlHelper::loadConfig(mixed $congFile, string $path = null) The built in tag sets for HtmlHelper are XHTML compliant, however if you need to generate HTML for HTML5 you will need to create and load a new tags cong le containing the tags youd like to use. To change the tags used create app/Config/html5_tags.php containing:
$config = array(tags => array( css => <link rel="%s" href="%s" %s>, style => <style%s>%s</style>, charset => <meta charset="%s">, javascriptblock => <script%s>%s</script>, javascriptstart => <script>, javascriptlink => <script src="%s"%s></script>, // ... ));

You can then load this tag set by calling $this->Html->loadConfig(html5_tags);

Creating breadcrumb trails with HtmlHelper

HtmlHelper::getCrumbs(string $separator = », string $startText = false) CakePHP has the built in ability to automatically create a breadcrumb trail in your app. To set this up, rst add something similar to the following in your layout template:
echo $this->Html->getCrumbs( > , Home);

The $startText option can also accept an array. This gives more control over the generated rst link:

More about Views

189

CakePHP Cookbook Documentation, Release 2.x

echo $this->Html->getCrumbs( > , array( text => $this->Html->image(home.png), url => array(controller => pages, action => display, home), escape => false ));

Any keys that are not text or url will be passed to link() as the $options parameter. Changed in version 2.1: The $startText parameter now accepts an array. HtmlHelper::addCrumb(string $name, string $link = null, mixed $options = null) Now, in your view youll want to add the following to start the breadcrumb trails on each of the pages:
$this->Html->addCrumb(Users, /users); $this->Html->addCrumb(Add User, /users/add);

This will add the output of Home > Users > Add User in your layout where getCrumbs was added. HtmlHelper::getCrumbList(array $options = array(), mixed $startText) Parameters $options (array) An array of html attributes for the containing <ul> element. Can also contain the separator, rstClass and lastClass options. $startText (string|array) The text or element that precedes the ul. Returns breadcrumbs as a (x)html list. This method uses HtmlHelper::tag() to generate list and its elements. Works similar to getCrumbs(), so it uses options which every crumb was added with. You can use the $startText parameter to provide the rst breadcrumb link/text. This is useful when you always want to include a root link. This option works the same as the $startText option for getCrumbs(). Changed in version 2.1: The $startText parameter was added.Changed in version 2.3: The separator, rstClass and lastClass options were added. JsHelper class JsHelper(View $view, array $settings = array()) Since the beginning CakePHPs support for Javascript has been with Prototype/Scriptaculous. While we still think these are an excellent Javascript library, the community has been asking for support for other libraries. Rather than drop Prototype in favour of another Javascript library. We created an Adapter based helper, and included 3 of the most requested libraries. Prototype/Scriptaculous, Mootools/Mootools-more, and jQuery/jQuery UI. And while the API is not as expansive as the previous AjaxHelper we feel that the adapter based solution allows for a more extensible solution giving developers the power and exibility they need to address their specic application needs. Javascript Engines form the backbone of the new JsHelper. A Javascript engine translates an abstract Javascript element into concrete Javascript code specic to the Javascript library being used. In addition they create an extensible system for others to use.

190

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

Using a specic Javascript engine

First of all download your preferred javascript library and place it in app/webroot/js Then you must include the library in your page. To include it in all pages, add this line to the <head> section of app/View/Layouts/default.ctp (copy this le from lib/Cake/View/Layouts/default.ctp if you have not created your own):
echo $this->Html->script(jquery); // Include jQuery library

Replace jquery with the name of your library le (.js will be added to the name). By default scripts are cached, and you must explicitly print out the cache. To do this at the end of each page, include this line just before the ending </body> tag:
echo $this->Js->writeBuffer(); // Write cached scripts

Warning: You must include the library in your page and print the cache for the helper to function. Javascript engine selection is declared when you include the helper in your controller:
public $helpers = array(Js => array(Jquery));

The above would use the Jquery Engine in the instances of JsHelper in your views. If you do not declare a specic engine, the jQuery engine will be used as the default. As mentioned before, there are three engines implemented in the core, but we encourage the community to expand the library compatibility. Using jQuery with other libraries The jQuery library, and virtually all of its plugins are constrained within the jQuery namespace. As a general rule, global objects are stored inside the jQuery namespace as well, so you shouldnt get a clash between jQuery and any other library (like Prototype, MooTools, or YUI). That said, there is one caveat: By default, jQuery uses $ as a shortcut for jQuery To override the $ shortcut, use the jQueryObject variable:
$this->Js->JqueryEngine->jQueryObject = $j; echo $this->Html->scriptBlock( var $j = jQuery.noConflict();, array(inline => false) ); // Tell jQuery to go into noconflict mode

Using the JsHelper inside customHelpers Declare the JsHelper in the $helpers array in your customHelper:
public $helpers = array(Js);

Note: It is not possible to declare a javascript engine inside a custom helper. Doing that will have no effect.

More about Views

191

CakePHP Cookbook Documentation, Release 2.x

If you are willing to use an other javascript engine than the default, do the helper setup in your controller as follows:
public $helpers = array( Js => array(Prototype), CustomHelper );

Warning: controller.

Be sure to declare the JsHelper and its engine on top of the $helpers array in your

The selected javascript engine may disappear (replaced by the default) from the jsHelper object in your helper, if you miss to do so and you will get code that does not t your javascript library.
Creating a Javascript Engine

Javascript engine helpers follow normal helper conventions, with a few additional restrictions. They must have the Engine sufx. DojoHelper is not good, DojoEngineHelper is correct. Furthermore, they should extend JsBaseEngineHelper in order to leverage the most of the new API.
Javascript engine usage

The JsHelper provides a few methods, and acts as a facade for the the Engine helper. You should not directly access the Engine helper except in rare occasions. Using the facade features of the JsHelper allows you to leverage the buffering and method chaining features built-in; (method chaining only works in PHP5). The JsHelper by default buffers almost all script code generated, allowing you to collect scripts throughout the view, elements and layout, and output it in one place. Outputting buffered scripts is done with $this->Js->writeBuffer(); this will return the buffer contents in a script tag. You can disable buffering wholesale with the $bufferScripts property or setting buffer => false in methods taking $options. Since most methods in Javascript begin with a selection of elements in the DOM, $this->Js->get() returns a $this, allowing you to chain the methods using the selection. Method chaining allows you to write shorter, more expressive code:
$this->Js->get(#foo)->event(click, $eventCode);

Is an example of method chaining. Method chaining is not possible in PHP4 and the above sample would be written like:
$this->Js->get(#foo); $this->Js->event(click, $eventCode);

Common options In attempts to simplify development where Js libraries can change, a common set of options is supported by JsHelper, these common options will be mapped out to the library specic options

192

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

internally. If you are not planning on switching Javascript libraries, each library also supports all of its native callbacks and options. Callback wrapping By default all callback options are wrapped with the an anonymous function with the correct arguments. You can disable this behavior by supplying the wrapCallbacks = false in your options array. Working with buffered scripts One drawback to previous implementation of Ajax type features was the scattering of script tags throughout your document, and the inability to buffer scripts added by elements in the layout. The new JsHelper if used correctly avoids both of those issues. It is recommended that you place $this->Js->writeBuffer() at the bottom of your layout le above the </body> tag. This will allow all scripts generated in layout elements to be output in one place. It should be noted that buffered scripts are handled separately from included script les. JsHelper::writeBuffer($options = array()) Writes all Javascript generated so far to a code block or caches them to a le and returns a linked script. Options inline - Set to true to have scripts output as a script block inline if cache is also true, a script link tag will be generated. (default true) cache - Set to true to have scripts cached to a le and linked in (default false) clear - Set to false to prevent script cache from being cleared (default true) onDomReady - wrap cached scripts in domready event (default true) safe - if an inline block is generated should it be wrapped in <![CDATA[ ... ]]> (default true) Creating a cache le with writeBuffer() requires that webroot/js be world writable and allows a browser to cache generated script resources for any page. JsHelper::buffer($content) Add $content to the internal script buffer. JsHelper::getBuffer($clear = true) Get the contents of the current buffer. Pass in false to not clear the buffer at the same time. Buffering methods that are not normally buffered Some methods in the helpers are buffered by default. The engines buffer the following methods by default: event sortable drag drop slider

More about Views

193

CakePHP Cookbook Documentation, Release 2.x

Additionally you can force any other method in JsHelper to use the buffering. By appending an boolean to the end of the arguments you can force other methods to go into the buffer. For example the each() method does not normally buffer:
$this->Js->each(alert("whoa!");, true);

The above would force the each() method to use the buffer. Conversely if you want a method that does buffer to not buffer, you can pass a false in as the last argument:
$this->Js->event(click, alert("whoa!");, false);

This would force the event function which normally buffers to return its result.
Other Methods

The core Javascript Engines provide the same feature set across all libraries, there is also a subset of common options that are translated into library specic options. This is done to provide end developers with as unied an API as possible. The following list of methods are supported by all the Engines included in the CakePHP core. Whenever you see separate lists for Options and Event Options both sets of parameters are supplied in the $options array for the method. JsHelper::object($data, $options = array()) Serializes $data into JSON. This method is a proxy for json_encode() with a few extra features added via the $options parameter. Options: prefix - String prepended to the returned data. postfix - String appended to the returned data. Example Use:
$json = $this->Js->object($data);

JsHelper::sortable($options = array()) Sortable generates a javascript snippet to make a set of elements (usually a list) drag and drop sortable. The normalized options are: Options containment - Container for move action handle - Selector to handle element. Only this element will start sort action. revert - Whether or not to use an effect to move sortable into nal position. opacity - Opacity of the placeholder distance - Distance a sortable must be dragged before sorting starts. Event Options start - Event red when sorting starts

194

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

sort - Event red during sorting complete - Event red when sorting completes. Other options are supported by each Javascript library, and you should check the documentation for your javascript library for more detailed information on its options and parameters. Example Use:
$this->Js->get(#my-list); $this->Js->sortable(array( distance => 5, containment => parent, start => onStart, complete => onStop, sort => onSort, wrapCallbacks => false ));

Assuming you were using the jQuery engine, you would get the following code in your generated Javascript block

$("#myList").sortable({containment:"parent", distance:5, sort:onSort, start:onStart, s

JsHelper::request($url, $options = array()) Generate a javascript snippet to create an XmlHttpRequest or AJAX request. Event Options complete - Callback to re on complete. success - Callback to re on success. before - Callback to re on request initialization. error - Callback to re on request failure. Options method - The method to make the request with defaults to GET in more libraries async - Whether or not you want an asynchronous request. data - Additional data to send. update - Dom id to update with the content of the response. type - Data type for response. json and html are supported. Default is html for most libraries. evalScripts - Whether or not <script> tags should be evaled. dataExpression - Should the data key be treated as a callback. Useful for supplying $options[data] as another Javascript expression. Example use:

More about Views

195

CakePHP Cookbook Documentation, Release 2.x

$this->Js->event( click, $this->Js->request( array(action => foo, param1), array(async => true, update => #element) ) );

JsHelper::get($selector) Set the internal selection to a CSS selector. The active selection is used in subsequent operations until a new selection is made:
$this->Js->get(#element);

The JsHelper now will reference all other element based methods on the selection of #element. To change the active selection, call get() again with a new element. JsHelper::set(mixed $one, mixed $two = null) Pass variables into Javascript. Allows you to set variables that will be output when the buffer is fetched with JsHelper::getBuffer() or JsHelper::writeBuffer(). The Javascript variable used to output set variables can be controlled with JsHelper::$setVariable. JsHelper::drag($options = array()) Make an element draggable. Options handle - selector to the handle element. snapGrid - The pixel grid that movement snaps to, an array(x, y) container - The element that acts as a bounding box for the draggable element. Event Options start - Event red when the drag starts drag - Event red on every step of the drag stop - Event red when dragging stops (mouse release) Example use:
$this->Js->get(#element); $this->Js->drag(array( container => #content, start => onStart, drag => onDrag, stop => onStop, snapGrid => array(10, 10), wrapCallbacks => false ));

If you were using the jQuery engine the following code would be added to the buffer

196

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

$("#element").draggable({containment:"#content", drag:onDrag, grid:[10,10], start:onSt

JsHelper::drop($options = array()) Make an element accept draggable elements and act as a dropzone for dragged elements. Options accept - Selector for elements this droppable will accept. hoverclass - Class to add to droppable when a draggable is over. Event Options drop - Event red when an element is dropped into the drop zone. hover - Event red when a drag enters a drop zone. leave - Event red when a drag is removed from a drop zone without being dropped. Example use:
$this->Js->get(#element); $this->Js->drop(array( accept => .items, hover => onHover, leave => onExit, drop => onDrop, wrapCallbacks => false ));

If you were using the jQuery engine the following code would be added to the buffer
$("#element").droppable({accept:".items", drop:onDrop, out:onExit, over:onHover});

Note: Droppables in Mootools function differently from other libraries. Droppables are implemented as an extension of Drag. So in addition to making a get() selection for the droppable element. You must also provide a selector rule to the draggable element. Furthermore, Mootools droppables inherit all options from Drag. JsHelper::slider($options = array()) Create snippet of Javascript that converts an element into a slider ui widget. See your libraries implementation for additional usage and features. Options handle - The id of the element used in sliding. direction - The direction of the slider either vertical or horizontal min - The min value for the slider. max - The max value for the slider. step - The number of steps or ticks the slider will have. value - The initial offset of the slider. More about Views 197

CakePHP Cookbook Documentation, Release 2.x

Events change - Fired when the sliders value is updated complete - Fired when the user stops sliding the handle Example use:
$this->Js->get(#element); $this->Js->slider(array( complete => onComplete, change => onChange, min => 0, max => 10, value => 2, direction => vertical, wrapCallbacks => false ));

If you were using the jQuery engine the following code would be added to the buffer

$("#element").slider({change:onChange, max:10, min:0, orientation:"vertical", stop:onC

JsHelper::effect($name, $options = array()) Creates a basic effect. By default this method is not buffered and returns its result. Supported effect names The following effects are supported by all JsEngines show - reveal an element. hide - hide an element. fadeIn - Fade in an element. fadeOut - Fade out an element. slideIn - Slide an element in. slideOut - Slide an element out. Options speed - Speed at which the animation should occur. Accepted values are slow, fast. Not all effects use the speed option. Example use If you were using the jQuery engine:
$this->Js->get(#element); $result = $this->Js->effect(fadeIn); // $result contains $("#foo").fadeIn();

JsHelper::event($type, $content, $options = array()) Bind an event to the current selection. $type can be any of the normal DOM events or a custom

198

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

event type if your library supports them. $content should contain the function body for the callback. Callbacks will be wrapped with function (event) { ... } unless disabled with the $options. Options wrap - Whether you want the callback wrapped in an anonymous function. (defaults to true) stop - Whether you want the event to stop. (defaults to true) Example use:
$this->Js->get(#some-link); $this->Js->event(click, $this->Js->alert(hey you!));

If you were using the jQuery library you would get the following Javascript code:
$(#some-link).bind(click, function (event) { alert(hey you!); return false; });

You can remove the return false; by passing setting the stop option to false:
$this->Js->get(#some-link); $this->Js->event(click, $this->Js->alert(hey you!), array(stop => false));

If you were using the jQuery library you would the following Javascript code would be added to the buffer. Note that the default browser event is not cancelled:
$(#some-link).bind(click, function (event) { alert(hey you!); });

JsHelper::domReady($callback) Creates the special DOM ready event. JsHelper::writeBuffer() automatically wraps the buffered scripts in a domReady method. JsHelper::each($callback) Create a snippet that iterates over the currently selected elements, and inserts $callback. Example:
$this->Js->get(div.message); $this->Js->each($(this).css({color: "red"}););

Using the jQuery engine would create the following Javascript:

$(div.message).each(function () { $(this).css({color: "red"}); });

JsHelper::alert($message) Create a javascript snippet containing an alert() snippet. By default, alert does not buffer, and returns the script snippet.:

More about Views

199

CakePHP Cookbook Documentation, Release 2.x

$alert = $this->Js->alert(Hey there);

JsHelper::confirm($message) Create a javascript snippet containing a confirm() snippet. By default, confirm does not buffer, and returns the script snippet.:
$alert = $this->Js->confirm(Are you sure?);

JsHelper::prompt($message, $default) Create a javascript snippet containing a prompt() snippet. By default, prompt does not buffer, and returns the script snippet.:
$prompt = $this->Js->prompt(What is your favorite color?, blue);

JsHelper::submit($caption = null, $options = array()) Create a submit input button that enables XmlHttpRequest submitted forms. Options can include both those for FormHelper::submit() and JsBaseEngine::request(), JsBaseEngine::event(); Forms submitting with this method, cannot send les. Files do not transfer over XmlHttpRequest and require an iframe, or other more specialized setups that are beyond the scope of this helper. Options url - The url you wish the XHR request to submit to. confirm - Conrm message displayed before sending the request. Using conrm, does not replace any before callback methods in the generated XmlHttpRequest. buffer - Disable the buffering and return a script tag in addition to the link. wrapCallbacks - Set to false to disable automatic callback wrapping. Example use:
echo $this->Js->submit(Save, array(update => #content));

Will create a submit button with an attached onclick event. The click event will be buffered by default.:
echo $this->Js->submit(Save, array( update => #content, div => false, type => json, async => false ));

Shows how you can combine options that JsHelper::request() when using submit.

both

FormHelper::submit()

and

JsHelper::link($title, $url = null, $options = array()) Create an html anchor element that has a click event bound to it. Options can include both those for HtmlHelper::link() and JsHelper::request(), JsHelper::event(), $options is a html attributes array that are appended to the generated anchor element. If an option is not part of the standard attributes or $htmlAttributes it will be passed to JsHelper::request() as an option. If an id is not supplied, a randomly generated one will be created for each link generated.

200

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

Options confirm - Generate a conrm() dialog before sending the event. id - use a custom id. htmlAttributes - additional non-standard htmlAttributes. Standard attributes are class, id, rel, title, escape, onblur and onfocus. buffer - Disable the buffering and return a script tag in addition to the link. Example use:
echo $this->Js->link(Page 2, array(page => 2), array(update => #content));

Will create a link pointing to /page:2 and updating #content with the response. You can use the htmlAttributes option to add in additional custom attributes.:
echo $this->Js->link(Page 2, array(page => 2), array( update => #content, htmlAttributes => array(other => value) ));

Outputs the following html:

JsHelper::serializeForm($options = array()) Serialize the form attached to $selector. Pass true for $isForm if the current selection is a form element. Converts the form or the form element attached to the current selection into a string/json object (depending on the library implementation) for use with XHR operations. Options isForm - is the current selection a form, or an input? (defaults to false) inline - is the rendered statement going to be used inside another JS statement? (defaults to false) Setting inline == false allows you to remove the trailing ;. This is useful when you need to serialize a form element as part of another Javascript operation, or use the serialize method in an Object literal. JsHelper::redirect($url) Redirect the page to $url using window.location. JsHelper::value($value) Converts a PHP-native variable of any type to a JSON-equivalent representation. Escapes any string values into JSON compatible strings. UTF-8 characters will be escaped.
Ajax Pagination

Much like Ajax Pagination in 1.2, you can use the JsHelper to handle the creation of Ajax pagination links instead of plain HTML links.

More about Views

201

CakePHP Cookbook Documentation, Release 2.x

Making Ajax Links Before you can create ajax links you must include the Javascript library that matches the adapter you are using with JsHelper. By default the JsHelper uses jQuery. So in your layout include jQuery (or whichever library you are using). Also make sure to include RequestHandlerComponent in your components. Add the following to your controller:
public $components = array(RequestHandler); public $helpers = array(Js);

Next link in the javascript library you want to use. For this example well be using jQuery:
echo $this->Html->script(jquery);

Similar to 1.2 you need to tell the PaginatorHelper that you want to make Javascript enhanced links instead of plain HTML ones. To do so you use options():
$this->Paginator->options(array( update => #content, evalScripts => true ));

The PaginatorHelper now knows to make javascript enhanced links, and that those links should update the #content element. Of course this element must exist, and often times you want to wrap $content_for_layout with a div matching the id used for the update option. You also should set evalScripts to true if you are using the Mootools or Prototype adapters, without evalScripts these libraries will not be able to chain requests together. The indicator option is not supported by JsHelper and will be ignored. You then create all the links as needed for your pagination features. Since the JsHelper automatically buffers all generated script content to reduce the number of <script> tags in your source code you must write the buffer out. At the bottom of your view le. Be sure to include:
echo $this->Js->writeBuffer();

If you omit this you will not be able to chain ajax pagination links. When you write the buffer, it is also cleared, so you dont have worry about the same Javascript being output twice. Adding effects and transitions Since indicator is no longer supported, you must add any indicator effects yourself:
<!DOCTYPE html> <html> <head> <?php echo $this->Html->script(jquery); ?> //more stuff here. </head> <body> <div id="content"> <?php echo $content_for_layout; ?> </div> <?php echo $this->Html->image(indicator.gif, array(id => busy-indicator)); ?> </body> </html>

202

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

Remember to place the indicator.gif le inside app/webroot/img folder. You may see a situation where the indicator.gif displays immediately upon the page load. You need to put in this css #busy-indicator { display:none; } in your main css le. With the above layout, weve included an indicator image le, that will display a busy indicator animation that we will show and hide with the JsHelper. To do that we need to update our options() function:

$this->Paginator->options(array( update => #content, evalScripts => true, before => $this->Js->get(#busy-indicator)->effect(fadeIn, array(buffer => false complete => $this->Js->get(#busy-indicator)->effect(fadeOut, array(buffer => fa ));

This will show/hide the busy-indicator element before and after the #content div is updated. Although indicator has been removed, the new features offered by JsHelper allow for more control and more complex effects to be created. NumberHelper class NumberHelper(View $view, array $settings = array()) The NumberHelper contains convenience methods that enable display numbers in common formats in your views. These methods include ways to format currency, percentages, data sizes, format numbers to specic precisions and also to give you more exibility with formatting numbers. Changed in version 2.1: NumberHelper have been refactored into CakeNumber class to allow easier use outside of the View layer. Within a view, these methods are accessible via the NumberHelper class and you can call it as you would call a normal helper method: $this->Number->method($args);. All of these functions return the formatted number; They do not automatically echo the output into the view. NumberHelper::currency(mixed $number, string $currency = USD, array $options = array()) Parameters $number (oat) The value to covert. $currency (string) The known currency format to use. $options (array) Options, see below. This method is used to display a number in common currency formats (EUR,GBP,USD). Usage in a view looks like:
// called as NumberHelper echo $this->Number->currency($number, $currency); // called as CakeNumber App::uses(CakeNumber, Utility); echo CakeNumber::currency($number, $currency);

The rst parameter, $number, should be a oating point number that represents the amount of money you are expressing. The second parameter is used to choose a predened currency formatting scheme:

More about Views

203

CakePHP Cookbook Documentation, Release 2.x

$currency EUR GBP USD

1234.56, formatted by currency type C 1.236,33 1,236.33 $ 1,236.33

The third parameter is an array of options for further dening the output. The following options are available: Option before after zero places thousands decimals negative escape wholeSymbol wholePosition fractionSymbol fractionPosition fractionExponent Description The currency symbol to place before whole numbers ie. $ The currency symbol to place after decimal numbers ie. c. Set to boolean false to use no decimal symbol. eg. 0.35 => $0.35. The text to use for zero values, can be a string or a number. ie. 0, Free! Number of decimal places to use. ie. 2 Thousands separator ie. , Decimal separator symbol ie. . Symbol for negative numbers. If equal to (), the number will be wrapped with ( and ) Should the output be htmlentity escaped? Defaults to true String to use for whole numbers ie. dollars Either before or after to place the whole symbol String to use for fraction numbers ie. cents Either before or after to place the fraction symbol Fraction exponent of this specic currency. Defaults to 2.

If a non-recognized $currency value is supplied, it is prepended to a USD formatted number. For example:
// called as NumberHelper echo $this->Number->currency(1234.56, FOO); // Outputs FOO 1,234.56 // called as CakeNumber App::uses(CakeNumber, Utility); echo CakeNumber::currency(1234.56, FOO);

Changed in version 2.4: The fractionExponent option was added. NumberHelper::defaultCurrency(string $currency) Parameters $currency (string) Set a known currency for CakeNumber::currency(). Setter/getter for default currency. This removes the need always passing the currency to CakeNumber::currency() and change all currency outputs by setting other default. New in 204 Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

version 2.3: This method was added in 2.3 NumberHelper::addFormat(string $formatName, array $options) Parameters $formatName (string) The format name to be used in the future $options (array) The array of options for this format. $options keys as CakeNumber::currency(). Uses the same

Add a currency format to the Number helper. Makes reusing currency formats easier:
// called as NumberHelper $this->Number->addFormat(BRR, array(before => R$ )); // called as CakeNumber App::uses(CakeNumber, Utility); CakeNumber::addFormat(BRR, array(before => R$ ));

You can now use BRR as a short form when formatting currency amounts:
// called as NumberHelper echo $this->Number->currency($value, BRR); // called as CakeNumber App::uses(CakeNumber, Utility); echo CakeNumber::currency($value, BRR);

Added formats are merged with the following defaults:

array( wholeSymbol wholePosition fractionSymbol fractionPosition zero places thousands decimals negative escape ) => => => => => => => => => => , before, , after, 0, 2, ,, ., (), true

NumberHelper::precision(mixed $number, int $precision = 3) Parameters $number (oat) The value to covert $precision (integer) The number of decimal places to display This method displays a number with the specied amount of precision (decimal places). It will round in order to maintain the level of precision dened.:
// called as NumberHelper echo $this->Number->precision(456.91873645, 2);

More about Views

205

CakePHP Cookbook Documentation, Release 2.x

// Outputs 456.92 // called as CakeNumber App::uses(CakeNumber, Utility); echo CakeNumber::precision(456.91873645, 2);

NumberHelper::toPercentage(mixed $number, int $precision = 2, array $options = array()) Parameters $number (oat) The value to covert. $precision (integer) The number of decimal places to display. $options (array) Options, see below. Option multiply Description Boolean to indicate whether the value has to be multiplied by 100. Useful for decimal percentages.

Like precision(), this method formats a number according to the supplied precision (where numbers are rounded to meet the given precision). This method also expresses the number as a percentage and prepends the output with a percent sign.:
// Called as NumberHelper. Output: 45.69% echo $this->Number->toPercentage(45.691873645); // Called as CakeNumber. Output: 45.69% App::uses(CakeNumber, Utility); echo CakeNumber::toPercentage(45.691873645); // Called with multiply. Output: 45.69% echo CakeNumber::toPercentage(0.45691, 2, array( multiply => true ));

New in version 2.4: The $options argument with the multiply option was added. NumberHelper::fromReadableSize(string $size, $default) Parameters $size (string) The formatted human readable value. This method unformats a number from a human readable byte size to an integer number of bytes. New in version 2.3: This method was added in 2.3 NumberHelper::toReadableSize(string $dataSize) Parameters $dataSize (string) The number of bytes to make readable.

206

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

This method formats data sizes in human readable forms. It provides a shortcut way to convert bytes to KB, MB, GB, and TB. The size is displayed with a two-digit precision level, according to the size of data supplied (i.e. higher sizes are expressed in larger terms):
// called as NumberHelper echo $this->Number->toReadableSize(0); // 0 Bytes echo $this->Number->toReadableSize(1024); // 1 KB echo $this->Number->toReadableSize(1321205.76); // 1.26 MB echo $this->Number->toReadableSize(5368709120); // 5.00 GB // called as CakeNumber App::uses(CakeNumber, Utility); echo CakeNumber::toReadableSize(0); // 0 Bytes echo CakeNumber::toReadableSize(1024); // 1 KB echo CakeNumber::toReadableSize(1321205.76); // 1.26 MB echo CakeNumber::toReadableSize(5368709120); // 5.00 GB

NumberHelper::format(mixed $number, mixed $options=false) This method gives you much more control over the formatting of numbers for use in your views (and is used as the main method by most of the other NumberHelper methods). Using this method might looks like:
// called as NumberHelper $this->Number->format($number, $options); // called as CakeNumber CakeNumber::format($number, $options);

The $number parameter is the number that you are planning on formatting for output. With no $options supplied, the number 1236.334 would output as 1,236. Note that the default precision is zero decimal places. The $options parameter is where the real magic for this method resides. If you pass an integer then this becomes the amount of precision or places for the function. If you pass an associated array, you can use the following keys: places (integer): the amount of desired precision before (string): to be put before the outputted number escape (boolean): if you want the value in before to be escaped decimals (string): used to delimit the decimal places in a number thousands (string): used to mark off thousand, millions, . . . places Example:
// called as NumberHelper echo $this->Number->format(123456.7890, array( places => 2, before => , escape => false, decimals => .,

More about Views

207

CakePHP Cookbook Documentation, Release 2.x

thousands => , )); // output 123,456.79 // called as CakeNumber App::uses(CakeNumber, Utility); echo CakeNumber::format(123456.7890, array( places => 2, before => , escape => false, decimals => ., thousands => , )); // output 123,456.79

NumberHelper::formatDelta(mixed $number, mixed $options=array()) This method displays differences in value as a signed number:
// called as NumberHelper $this->Number->formatDelta($number, $options); // called as CakeNumber CakeNumber::formatDelta($number, $options);

The $number parameter is the number that you are planning on formatting for output. With no $options supplied, the number 1236.334 would output as 1,236. Note that the default precision is zero decimal places. The $options parameter takes the same keys as CakeNumber::format() itself: places (integer): the amount of desired precision before (string): to be put before the outputted number after (string): to be put after the outputted number decimals (string): used to delimit the decimal places in a number thousands (string): used to mark off thousand, millions, . . . places Example:
// called as NumberHelper echo $this->Number->formatDelta(123456.7890, array( places => 2, decimals => ., thousands => , )); // output +123,456.79 // called as CakeNumber App::uses(CakeNumber, Utility); echo CakeNumber::formatDelta(123456.7890, array( places => 2, decimals => .,

208

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

thousands => , )); // output +123,456.79

New in version 2.3: This method was added in 2.3 Warning: Since 2.4 the symbols are now UTF-8. Please see the migration guide for details if you run a non-UTF-8 app.

Paginator class PaginatorHelper(View $view, array $settings = array()) The Pagination helper is used to output pagination controls such as page numbers and next/previous links. It works in tandem with PaginatorComponent. See also Pagination for information on how to create paginated datasets and do paginated queries.
Creating sort links

PaginatorHelper::sort($key, $title = null, $options = array()) Parameters $key (string) The name of the key that the recordset should be sorted. $title (string) Title for the link. If $title is null $key will be used for the title and will be generated by inection. $options (array) Options for sorting link. Generates a sorting link. Sets named or querystring parameters for the sort and direction. Links will default to sorting by asc. After the rst click, links generated with sort() will handle direction switching automatically. Link sorting default by asc. If the resultset is sorted asc by the specied key the returned link will sort by desc. Accepted keys for $options: escape Whether you want the contents html entity encoded, defaults to true. model The model to use, defaults to PaginatorHelper::defaultModel(). Assuming you are paginating some posts, and are on page one:
echo $this->Paginator->sort(user_id);

Output:
<a href="/posts/index/page:1/sort:user_id/direction:asc/">User Id</a>

You can use the title parameter to create custom text for your link:

More about Views

209

CakePHP Cookbook Documentation, Release 2.x

echo $this->Paginator->sort(user_id, User account);

Output:
<a href="/posts/index/page:1/sort:user_id/direction:asc/">User account</a>

If you are using HTML like images in your links remember to set escaping off:
echo $this->Paginator->sort(user_id, <em>User account</em>, array(escape => false));

Output:
<a href="/posts/index/page:1/sort:user_id/direction:asc/"><em>User account</em></a>

The direction option can be used to set the default direction for a link. Once a link is active, it will automatically switch directions like normal:
echo $this->Paginator->sort(user_id, null, array(direction => desc));

Output:
<a href="/posts/index/page:1/sort:user_id/direction:desc/">User Id</a>

PaginatorHelper::sortDir(string $model = null, mixed $options = array()) Gets the current direction the recordset is sorted. PaginatorHelper::sortKey(string $model = null, mixed $options = array()) Gets the current key by which the recordset is sorted.
Creating page number links

PaginatorHelper::numbers($options = array()) Returns a set of numbers for the paged result set. Uses a modulus to decide how many numbers to show on each side of the current page By default 8 links on either side of the current page will be created if those pages exist. Links will not be generated for pages that do not exist. The current page is also not a link. Supported options are: before Content to be inserted before the numbers. after Content to be inserted after the numbers. model Model to create numbers for, defaults to PaginatorHelper::defaultModel(). modulus how many numbers to include on either side of the current page, defaults to 8. separator Separator content defaults to | tag The tag to wrap links in, defaults to span. first Whether you want rst links generated, set to an integer to dene the number of rst links to generate. Defaults to false. If a string is set a link to the rst page will be generated with the value as the title:

210

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

echo $this->Paginator->numbers(array(first => First page));

last Whether you want last links generated, set to an integer to dene the number of last links to generate. Defaults to false. Follows the same logic as the first option. There is a last() method to be used separately as well if you wish. ellipsis Ellipsis content, defaults to ... class The classname used on the wrapping tag. currentClass The classname to use on the current/active link. Defaults to current. currentTag Tag to use for current page number, defaults to null. This allows you to generate for example Twitter Bootstrap like links with the current page number wrapped in extra a or span tag. While this method allows a lot of customization for its output. It is also ok to just call the method without any params.:
echo $this->Paginator->numbers();

Using the rst and last options you can create links to the beginning and end of the page set. The following would create a set of page links that include links to the rst 2 and last 2 pages in the paged results:
echo $this->Paginator->numbers(array(first => 2, last => 2));

New in version 2.1: The currentClass option was added in 2.1.New in version 2.3: The currentTag option was added in 2.3.
Creating jump links

In addition to generating links that go directly to specic page numbers, youll often want links that go to the previous and next links, rst and last pages in the paged data set. PaginatorHelper::prev($title = << Previous, $options = array(), $disabledTitle = null, $disabledOptions = array()) Parameters $title (string) Title for the link. $options (mixed) Options for pagination link. $disabledTitle (string) Title when the link is disabled, as when youre already on the rst page, no previous page to go. $disabledOptions (mixed) Options for the disabled pagination link. Generates a link to the previous page in a set of paged records. $options and $disabledOptions supports the following keys: tag The tag wrapping tag you want to use, defaults to span. Set this to false to disable this option. escape Whether you want the contents html entity encoded, defaults to true.

More about Views

211

CakePHP Cookbook Documentation, Release 2.x

model The model to use, defaults to PaginatorHelper::defaultModel(). disabledTag Tag to use instead of A tag when there is no previous page A simple example would be:

echo $this->Paginator->prev( << . __(previous), array(), null, array(class =>

If you were currently on the second page of posts, you would get the following:

<span class="prev"><a rel="prev" href="/posts/index/page:1/sort:title/order:desc"><< p

If there were no previous pages you would get:

You can change the wrapping tag using the tag option:
echo $this->Paginator->prev(__(previous), array(tag => li));

Output:

<li class="prev"><a rel="prev" href="/posts/index/page:1/sort:title/order:desc">previo

You can also disable the wrapping tag:

echo $this->Paginator->prev(__(previous), array(tag => false));

Output:

<a class="prev" rel="prev" href="/posts/index/page:1/sort:title/order:desc">previous</

Changed in version 2.3: For methods: PaginatorHelper::prev() and PaginatorHelper::next() it is now possible to set the tag option to false to disable the wrapper. New options disabledTag has been added. If you leave the $disabledOptions empty the $options parameter will be used. This can save some additional typing if both sets of options are the same. PaginatorHelper::next($title = Next >>, $options = array(), $disabledTitle = null, $disabledOptions = array()) This method is identical to prev() with a few exceptions. It creates links pointing to the next page instead of the previous one. It also uses next as the rel attribute value instead of prev PaginatorHelper::first($rst = << rst, $options = array()) Returns a rst or set of numbers for the rst pages. If a string is given, then only a link to the rst page with the provided text will be created:
echo $this->Paginator->first(< first);

The above creates a single link for the rst page. Will output nothing if you are on the rst page. You can also use an integer to indicate how many rst paging links you want generated:
echo $this->Paginator->first(3);

The above will create links for the rst 3 pages, once you get to the third or greater page. Prior to that nothing will be output. 212 Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

The options parameter accepts the following: tag The tag wrapping tag you want to use, defaults to span after Content to insert after the link/tag model The model to use defaults to PaginatorHelper::defaultModel() separator Content between the generated links, defaults to | ellipsis Content for ellipsis, defaults to ... PaginatorHelper::last($last = last >>, $options = array()) This method works very much like the first() method. It has a few differences though. It will not generate any links if you are on the last page for a string values of $last. For an integer value of $last no links will be generated once the user is inside the range of last pages. PaginatorHelper::current(string $model = null) Gets the current page of the recordset for the given model:
// Our url is: http://example.com/comments/view/page:3 echo $this->Paginator->current(Comment); // Output is 3

PaginatorHelper::hasNext(string $model = null) Returns true if the given result set is not at the last page. PaginatorHelper::hasPrev(string $model = null) Returns true if the given result set is not at the rst page. PaginatorHelper::hasPage(string $model = null, integer $page = 1) Returns true if the given result set has the page number given by $page.
Creating a page counter

PaginatorHelper::counter($options = array()) Returns a counter string for the paged result set. Using a provided format string and a number of options you can create localized and application specic indicators of where a user is in the paged data set. There are a number of options for counter(). The supported ones are: format Format of the counter. Supported formats are range, pages and custom. Defaults to pages which would output like 1 of 10. In the custom mode the supplied string is parsed and tokens are replaced with actual values. The available tokens are: {:page} - the current page displayed. {:pages} - total number of pages. {:current} - current number of records being shown. {:count} - the total number of records in the result set. {:start} - number of the rst record being displayed. {:end} - number of the last record being displayed. More about Views 213

CakePHP Cookbook Documentation, Release 2.x

{:model} - The pluralized human form of the model name. If your model was RecipePage, {:model} would be recipe pages. This option was added in 2.0. You could also supply only a string to the counter method using the tokens available. For example:
echo $this->Paginator->counter( Page {:page} of {:pages}, showing {:current} records out of {:count} total, starting on record {:start}, ending on {:end} );

Setting format to range would output like 1 - 3 of 13:

echo $this->Paginator->counter(array( format => range ));

separator The separator between the actual page and the number of pages. Defaults to of . This is used in conjunction with format = pages which is format default value:
echo $this->Paginator->counter(array( separator => of a total of ));

model The name of the model being paginated, defaults to PaginatorHelper::defaultModel(). This is used in conjunction with the custom string on format option.
Modifying the options PaginatorHelper uses

PaginatorHelper::options($options = array()) Parameters $options (mixed) Default options for pagination links. If a string is supplied - it is used as the DOM id element to update. Sets all the options for the Paginator Helper. Supported options are: url The url of the paginating action. url has a few sub options as well: sort The key that the records are sorted by. direction The direction of the sorting. Defaults to ASC. page The page number to display. The above mentioned options can be used to force particular pages/directions. You can also append additional url content into all urls generated in the helper:
$this->Paginator->options(array( url => array( sort => email, direction => desc, page => 6, lang => en ) ));

214

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

The above adds the en route parameter to all links the helper will generate. It will also create links with specic sort, direction and page values. By default PaginatorHelper will merge in all of the current pass and named parameters. So you dont have to do that in each view le. escape Denes if the title eld for links should be HTML escaped. Defaults to true. update The CSS selector of the element to update with the results of AJAX pagination calls. If not specied, regular links will be created:
$this->Paginator->options(array(update => #content));

This is useful when doing Ajax Pagination. Keep in mind that the value of update can be any valid CSS selector, but most often is simpler to use an id selector. model The name of the model PaginatorHelper::defaultModel(). being paginated, defaults to

Using GET parameters for pagination Normally Pagination in CakePHP uses Named parameters. There are times you want to use GET parameters instead. While the main conguration option for this feature is in PaginatorComponent, you have some additional control in the view. You can use options() to indicate that you want other named parameters to be converted:
$this->Paginator->options(array(convertKeys => array(your, keys, here)));

Conguring the PaginatorHelper to use a javascript helper By default the PaginatorHelper uses JsHelper to do ajax features. However, if you dont want that and want to use a custom helper for ajax links, you can do so by changing the $helpers array in your controller. After running paginate() do the following:
// In your controller action. $this->set(posts, $this->paginate()); $this->helpers[Paginator] = array(ajax => CustomJs);

Will change the PaginatorHelper to use the CustomJs for ajax operations. You could also set the ajax key to be any helper, as long as that class implements a link() method that behaves like HtmlHelper::link()
Pagination in Views

Its up to you to decide how to show records to the user, but most often this will be done inside HTML tables. The examples below assume a tabular layout, but the PaginatorHelper available in views doesnt always need to be restricted as such. See the details on PaginatorHelper (http://api20.cakephp.org/class/paginator-helper) in the API. As mentioned, the PaginatorHelper also offers sorting features which can be easily integrated into your table column headers:
// app/View/Posts/index.ctp <table> <tr>

More about Views

215

CakePHP Cookbook Documentation, Release 2.x

<th><?php echo $this->Paginator->sort(id, ID); ?></th> <th><?php echo $this->Paginator->sort(title, Title); ?></th> </tr> <?php foreach ($data as $recipe): ?> <tr> <td><?php echo $recipe[Recipe][id]; ?> </td> <td><?php echo h($recipe[Recipe][title]); ?> </td> </tr> <?php endforeach; ?> </table>

The links output from the sort() method of the PaginatorHelper allow users to click on table headers to toggle the sorting of the data by a given eld. It is also possible to sort a column based on associations:
<table> <tr> <th><?php echo $this->Paginator->sort(title, Title); ?></th> <th><?php echo $this->Paginator->sort(Author.name, Author); ?></th> </tr> <?php foreach ($data as $recipe): ?> <tr> <td><?php echo h($recipe[Recipe][title]); ?> </td> <td><?php echo h($recipe[Author][name]); ?> </td> </tr> <?php endforeach; ?> </table>

The nal ingredient to pagination display in views is the addition of page navigation, also supplied by the PaginationHelper:
// Shows the page numbers echo $this->Paginator->numbers(); // Shows the next and previous links echo $this->Paginator->prev( Previous, null, null, array(class => disabled)); echo $this->Paginator->next(Next , null, null, array(class => disabled)); // prints X of Y, where X is current page and Y is number of pages echo $this->Paginator->counter();

The wording output by the counter() method can also be customized using special markers:
echo $this->Paginator->counter(array( format => Page {:page} of {:pages}, showing {:current} records out of {:count} total, starting on record {:start}, ending on {:end} ));

Other Methods

PaginatorHelper::link($title, $url = array(), $options = array())

216

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

Parameters $title (string) Title for the link. $url (mixed) Url for the action. See Router::url() $options (array) Options for the link. See options() for list of keys. Accepted keys for $options: update The Id of the DOM element you wish to update. Creates Ajax enabled links. escape Whether you want the contents html entity encoded, defaults to true. model The model to use, defaults to PaginatorHelper::defaultModel(). Creates a regular or AJAX link with pagination parameters:
echo $this->Paginator->link(Sort by title on page 5, array(sort => title, page => 5, direction => desc));

If created in the view for /posts/index /posts/index/page:5/sort:title/direction:desc

Would

create

link

pointing

PaginatorHelper::url($options = array(), $asArray = false, $model = null) Parameters $options (array) Pagination/URL options array. As used on options() or link() method. $asArray (boolean) Return the url as an array, or a URI string. Defaults to false. $model (string) Which model to paginate on By default returns a full pagination URL string for use in non-standard contexts (i.e. JavaScript).:
echo $this->Paginator->url(array(sort => title), true);

PaginatorHelper::defaultModel() Gets the default model of the paged sets or null if pagination is not initialized. PaginatorHelper::params(string $model = null) Gets the current paging parameters from the resultset for the given model:
debug($this->Paginator->params()); /* Array ( [page] => 2 [current] => 2 [count] => 43 [prevPage] => 1 [nextPage] => 3 [pageCount] => 3 [order] => [limit] => 20

More about Views

217

CakePHP Cookbook Documentation, Release 2.x

[options] => Array ( [page] => 2 [conditions] => Array ( ) ) [paramType] => named ) */

PaginatorHelper::param(string $key, string $model = null) Gets the specic paging parameter from the resultset for the given model:
debug($this->Paginator->param(count)); /* (int)43 */

New in version 2.4: The param() method was added in 2.4. RSS class RssHelper(View $view, array $settings = array()) The RSS helper makes generating XML for RSS feeds easy.
Creating an RSS feed with the RssHelper

This example assumes you have a Posts Controller and Post Model already created and want to make an alternative view for RSS. Creating an xml/rss version of posts/index is a snap with CakePHP. After a few simple steps you can simply append the desired extension .rss to posts/index making your URL posts/index.rss. Before we jump too far ahead trying to get our webservice up and running we need to do a few things. First parseExtensions needs to be activated, this is done in app/Config/routes.php:
Router::parseExtensions(rss);

In the call above weve activated the .rss extension. When using Router::parseExtensions() you can pass as many arguments or extensions as you want. This will activate each extension/content-type for use in your application. Now when the address posts/index.rss is requested you will get an xml version of your posts/index. However, rst we need to edit the controller to add in the rss-specic code. Controller Code It is a good idea to add RequestHandler to your PostsControllers $components array. This will allow a lot of automagic to occur:

218

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

public $components = array(RequestHandler);

Our view will also use the TextHelper for formatting, so that should be added to the controller as well:
public $helpers = array(Text);

Before we can make an RSS version of our posts/index we need to get a few things in order. It may be tempting to put the channel metadata in the controller action and pass it to your view using the Controller::set() method but this is inappropriate. That information can also go in the view. That will come later though, for now if you have a different set of logic for the data used to make the RSS feed and the data for the html view you can use the RequestHandler::isRss() method, otherwise your controller can stay the same:
// Modify the Posts Controller action that corresponds to // the action which deliver the rss feed, which is the // index action in our example

public function index() { if ($this->RequestHandler->isRss() ) { $posts = $this->Post->find(all, array(limit => 20, order => Post.created DES return $this->set(compact(posts)); } // this is not an Rss request, so deliver // data used by websites interface $this->paginate[Post] = array(order => Post.created DESC, limit => 10); $posts = $this->paginate(); $this->set(compact(posts)); }

With all the View variables set we need to create an rss layout. Layout An Rss layout is very simple, app/View/Layouts/rss/default.ctp: put the following contents in

if (!isset($documentData)) { $documentData = array(); } if (!isset($channelData)) { $channelData = array(); } if (!isset($channelData[title])) { $channelData[title] = $title_for_layout; } $channel = $this->Rss->channel(array(), $channelData, $content_for_layout); echo $this->Rss->document($documentData, $channel);

It doesnt look like much but thanks to the power in the RssHelper its doing a lot of lifting for us. We havent set $documentData or $channelData in the controller, however in CakePHP your views can pass variables back to the layout. Which is where our $channelData array will come from setting all of the meta data for our feed. More about Views 219

CakePHP Cookbook Documentation, Release 2.x

Next up is view le for my posts/index. Much like the layout le we created, we need to create a View/Posts/rss/ directory and create a new index.ctp inside that folder. The contents of the le are below. View Our view, located at app/View/Posts/rss/index.ctp, begins by setting the $documentData and $channelData variables for the layout, these contain all the metadata for our RSS feed. This is done by using the View::set() method which is analogous to the Controller::set() method. Here though we are passing the channels metadata back to the layout:
$this->set(channelData, array( title => __("Most Recent Posts"), link => $this->Html->url(/, true), description => __("Most recent posts."), language => en-us ));

The second part of the view generates the elements for the actual records of the feed. This is accomplished by looping through the data that has been passed to the view ($items) and using the RssHelper::item() method. The other method you can use, RssHelper::items() which takes a callback and an array of items for the feed. (The method I have seen used for the callback has always been called transformRss(). There is one downfall to this method, which is that you cannot use any of the other helper classes to prepare your data inside the callback method because the scope inside the method does not include anything that is not passed inside, thus not giving access to the TimeHelper or any other helper that you may need. The RssHelper::item() transforms the associative array into an element for each key value pair. Note: You will need to modify the $postLink variable as appropriate to your application.
foreach ($posts as $post) { $postTime = strtotime($post[Post][created]); $postLink = array( controller => posts, action => view, year => date(Y, $postTime), month => date(m, $postTime), day => date(d, $postTime), $post[Post][slug] ); // Remove & escape any HTML to make sure the feed content will validate. $bodyText = h(strip_tags($post[Post][body])); $bodyText = $this->Text->truncate($bodyText, 400, array( ending => ..., exact => true, html => true, )); echo $this->Rss->item(array(), array( title => $post[Post][title],

220

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

link => $postLink, guid => array(url => $postLink, isPermaLink => true), description => $bodyText, pubDate => $post[Post][created] )); }

You can see above that we can use the loop to prepare the data to be transformed into XML elements. It is important to lter out any non-plain text characters out of the description, especially if you are using a rich text editor for the body of your blog. In the code above we used strip_tags() and h() to remove/escape any XML special characaters from the content, as they could cause validation errors. Once we have set up the data for the feed, we can then use the RssHelper::item() method to create the XML in RSS format. Once you have all this setup, you can test your RSS feed by going to your site /posts/index.rss and you will see your new feed. It is always important that you validate your RSS feed before making it live. This can be done by visiting sites that validate the XML such as Feed Validator or the w3c site at http://validator.w3.org/feed/. Note: You may need to set the value of debug in your core conguration to 1 or to 0 to get a valid feed, because of the various debug information added automagically under higher debug settings that break XML syntax or feed validation rules.

Rss Helper API

property RssHelper::$action Current action property RssHelper::$base Base URL property RssHelper::$data POSTed model data property RssHelper::$field Name of the current eld property RssHelper::$helpers Helpers used by the RSS Helper property RssHelper::$here URL to current action property RssHelper::$model Name of current model property RssHelper::$params Parameter array property RssHelper::$version Default spec version of generated RSS.

More about Views

221

CakePHP Cookbook Documentation, Release 2.x

RssHelper::channel(array $attrib = array (), array $elements = array (), mixed $content = null) Return type string Returns an RSS <channel /> element. RssHelper::document(array $attrib = array (), string $content = null) Return type string Returns an RSS document wrapped in <rss /> tags. RssHelper::elem(string $name, array $attrib = array (), mixed $content = null, boolean $endTag = true) Return type string Generates an XML element. RssHelper::item(array $att = array (), array $elements = array ()) Return type string Converts an array into an <item /> element and its contents. RssHelper::items(array $items, mixed $callback = null) Return type string Transforms an array of data using an optional callback, and maps it to a set of <item /> tags. RssHelper::time(mixed $time) Return type string Converts a time in any format to an RSS time. See TimeHelper::toRSS(). SessionHelper class SessionHelper(View $view, array $settings = array()) As a natural counterpart to the Session Component, the Session Helper replicates most of the components functionality and makes it available in your view. The major difference between the Session Helper and the Session Component is that the helper does not have the ability to write to the session. As with the Session Component, data is read by using dot notation array structures:
array(User => array( username => [email protected] ));

Given the previous array structure, the node would be accessed by User.username, with the dot indicating the nested array. This notation is used for all Session helper methods wherever a $key is used. SessionHelper::read(string $key)

222

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

Return type mixed Read from the Session. Returns a string or array depending on the contents of the session. SessionHelper::check(string $key) Return type boolean Check to see if a key is in the Session. Returns a boolean on the keys existence. SessionHelper::error() Return type string Returns last error encountered in a session. SessionHelper::valid() Return type boolean Used to check is a session is valid in a view.
Displaying notications or ash messages

SessionHelper::flash(string $key = ash, array $params = array()) Return type string As explained in Creating notication messages you can create one-time notications for feedback. After creating messages with SessionComponent::setFlash() you will want to display them. Once a message is displayed, it will be removed and not displayed again:
echo $this->Session->flash();

The above will output a simple message, with the following html:
<div id="flashMessage" class="message"> Your stuff has been saved. </div>

As with the component method you can set additional properties and customize which element is used. In the controller you might have code like:
// in a controller $this->Session->setFlash(The user could not be deleted.);

When outputting this message, you can choose the element used to display this message:
// in a layout. echo $this->Session->flash(flash, array(element => failure));

This would use View/Elements/failure.ctp to render the message. The message text would be available as $message in the element. Inside the failure element le would be something like this:

More about Views

223

CakePHP Cookbook Documentation, Release 2.x

<div class="flash flash-failure"> <?php echo h($message); ?> </div>

You can also pass additional parameters into the flash() method, which allow you to generate customized messages:
// In the controller $this->Session->setFlash(Thanks for your payment.); // In the layout. echo $this->Session->flash(flash, array( params => array(name => $user[User][name]) element => payment )); // View/Elements/payment.ctp <div class="flash payment"> <?php printf($message, h($name)); ?> </div>

Note: By default CakePHP does not HTML escape ash messages. If you are using any request or user data in your ash messages you should escape it with h when formatting your messages.

TextHelper class TextHelper(View $view, array $settings = array()) The TextHelper contains methods to make text more usable and friendly in your views. It aids in enabling links, formatting urls, creating excerpts of text around chosen words or phrases, highlighting key words in blocks of text, and to gracefully truncating long stretches of text. Changed in version 2.1: Several of TextHelper methods have been moved into String class to allow easier use outside of the View layer. Within a view, these methods are accessible via the TextHelper class and you can call it as you would call a normal helper method: $this->Text->method($args);. TextHelper::autoLinkEmails(string $text, array $options=array()) Parameters $text (string) The text to convert. $options (array) An array of html attributes for the generated links. Adds links to the well-formed email addresses in $text, according to any options dened in $htmlOptions (see HtmlHelper::link()).:

$myText = For more information regarding our world-famous pastries and desserts, cont $linkedText = $this->Text->autoLinkEmails($myText);

Output:

224

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

For more information regarding our world-famous pastries and desserts, contact <a href="mailto:[email protected]">[email protected]</a>

Changed in version 2.1: In 2.1 this method automatically escapes its input. Use the escape option to disable this if necessary. TextHelper::autoLinkUrls(string $text, array $htmlOptions=array()) Parameters $text (string) The text to convert. $htmlOptions (array) An array html attributes for the generated links Same as in autoLinkEmails(), only this method searches for strings that start with https, http, ftp, or nntp and links them appropriately. Changed in version 2.1: In 2.1 this method automatically escapes its input. Use the escape option to disable this if necessary. TextHelper::autoLink(string $text, array $htmlOptions=array()) Parameters $text (string) The text to autolink. $htmlOptions (array) An array html attributes for the generated links Performs the functionality in both autoLinkUrls() and autoLinkEmails() on the supplied $text. All URLs and emails are linked appropriately given the supplied $htmlOptions. Changed in version 2.1: In 2.1 this method automatically escapes its input. Use the escape option to disable this if necessary. TextHelper::autoParagraph(string $text) Parameters $text (string) The text to convert. Adds proper <p> around text where double-line returns and <br> where single-line returns are found.:
$myText = For more information regarding our world-famous pastries and desserts. contact [email protected]; $formattedText = $this->Text->autoParagraph($myText);

Output:
<p>For more information<br /> regarding our world-famous pastries and desserts.<p> <p>contact [email protected]</p>

New in version 2.4. TextHelper::highlight(string $haystack, string $needle, array $options = array()) Parameters $haystack (string) The string to search. More about Views 225

CakePHP Cookbook Documentation, Release 2.x

$needle (string) The string to nd. $options (array) An array of options, see below. Highlights $needle in $haystack using the $options[format] string specied or a default string. Options: format - string The piece of html with that the phrase will be highlighted html - bool If true, will ignore any HTML tags, ensuring that only the correct text is highlighted Example:

// called as TextHelper echo $this->Text->highlight($lastSentence, using, array(format => <span class="hi

// called as String App::uses(String, Utility); echo String::highlight($lastSentence, using, array(format => <span class="highlig

Output:
Highlights $needle in $haystack <span class="highlight">using</span> the $options[format] string specified or a default string.

TextHelper::stripLinks($text) Strips the supplied $text of any HTML links. TextHelper::truncate(string $text, int $length=100, array $options) Parameters $text (string) The text to truncate. $length (int) The length to trim to. $options (array) An array of options to use. Cuts a string to the $length and adds a sufx with ellipsis if the text is longer than $length. If exact is passed as false, the truncation will occur after the next word ending. If html is passed as true, html tags will be respected and will not be cut off. $options is used to pass all extra parameters, and has the following possible keys by default, all of which are optional:
array( ellipsis => ..., exact => true, html => false )

Example:
// called as TextHelper echo $this->Text->truncate( The killer crept forward and tripped on the rug.,

226

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

22, array( ellipsis => ..., exact => false ) ); // called as String App::uses(String, Utility); echo String::truncate( The killer crept forward and tripped on the rug., 22, array( ellipsis => ..., exact => false ) );

Output:
The killer crept...

Changed in version 2.3: ending has been replaced by ellipsis. ending is still used in 2.2.1 TextHelper::tail(string $text, int $length=100, array $options) Parameters $text (string) The text to truncate. $length (int) The length to trim to. $options (array) An array of options to use. Cuts a string to the $length and adds a prex with ellipsis if the text is longer than $length. If exact is passed as false, the truncation will occur before the next word ending. $options is used to pass all extra parameters, and has the following possible keys by default, all of which are optional:
array( ellipsis => ..., exact => true )

New in version 2.3. Example:

// called as TextHelper echo $this->Text->tail( I packed my bag and in it I put a PSP, a PS3, a TV, a C# program that can divide 70, array( ellipsis => ..., exact => false )

More about Views

227

CakePHP Cookbook Documentation, Release 2.x

); // called as String App::uses(String, Utility); echo String::tail( I packed my bag and in it I put a PSP, a PS3, a TV, a C# program that can divide 70, array( ellipsis => ..., exact => false ) );

Output:
...a TV, a C# program that can divide by zero, death metal t-shirts

TextHelper::excerpt(string $haystack, string $needle, integer $radius=100, string $ellipsis=...) Parameters $haystack (string) The string to search. $needle (string) The string to excerpt around. $radius (int) The number of characters on either side of $needle you want to include. $ellipsis (string) Text to append/prepend to the beginning or end of the result. Extracts an excerpt from $haystack surrounding the $needle with a number of characters on each side determined by $radius, and prex/sufx with $ellipsis. This method is especially handy for search results. The query string or keywords can be shown within the resulting document.:
// called as TextHelper echo $this->Text->excerpt($lastParagraph, method, 50, ...); // called as String App::uses(String, Utility); echo String::excerpt($lastParagraph, method, 50, ...);

Output:
... by $radius, and prefix/suffix with $ellipsis. This method is especially handy for search results. The query...

TextHelper::toList(array $list, $and=and) Parameters $list (array) Array of elements to combine into a list sentence. $and (string) The word used for the last join. Creates a comma-separated list where the last two items are joined with and.:

228

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

// called as TextHelper echo $this->Text->toList($colors); // called as String App::uses(String, Utility); echo String::toList($colors);

Output:
red, orange, yellow, green, blue, indigo and violet

TimeHelper class TimeHelper(View $view, array $settings = array()) The Time Helper does what it says on the tin: saves you time. It allows for the quick processing of time related information. The Time Helper has two main tasks that it can perform: 1. It can format time strings. 2. It can test time (but cannot bend time, sorry). Changed in version 2.1: TimeHelper has been refactored into the CakeTime class to allow easier use outside of the View layer. Within a view, these methods are accessible via the TimeHelper class and you can call it as you would call a normal helper method: $this->Time->method($args);.
Using the Helper

A common use of the Time Helper is to offset the date and time to match a users time zone. Lets use a forum as an example. Your forum has many users who may post messages at any time from any part of the world. An easy way to manage the time is to save all dates and times as GMT+0 or UTC. Uncomment the line date_default_timezone_set(UTC); in app/Config/core.php to ensure your applications time zone is set to GMT+0. Next add a time zone eld to your users table and make the necessary modications to allow your users to set their time zone. Now that we know the time zone of the logged in user we can correct the date and time on our posts using the Time Helper:
echo $this->Time->format(F jS, Y // Will display August 22nd, 2011 // August 22nd, 2011 03:53 PM for // and August 23rd, 2011 09:53 AM

h:i A, $post[Post][created], null, $user[User][ti 11:53 PM for a user in GMT+0 a user in GMT-8 GMT+10

Most of the Time Helper methods have a $timezone parameter. The $timezone parameter accepts a valid timezone identier string or an instance of DateTimeZone class.
Formatting

TimeHelper::convert($serverTime, $timezone = NULL)

More about Views

229

CakePHP Cookbook Documentation, Release 2.x

Return type integer Converts given time (in servers time zone) to users local time, given his/her timezone.:
// called via TimeHelper echo $this->Time->convert(time(), Asia/Jakarta); // 1321038036 // called as CakeTime App::uses(CakeTime, Utility); echo CakeTime::convert(time(), new DateTimeZone(Asia/Jakarta));

Changed in version 2.2: $timezone parameter replaces $userOffset parameter used in 2.1 and below. TimeHelper::convertSpecifiers($format, $time = NULL) Return type string Converts a string representing the format for the function strftime and returns a windows safe and i18n aware format. TimeHelper::dayAsSql($dateString, $eld_name, $timezone = NULL) Return type string Creates a string in the same format as daysAsSql but only needs a single date object:
// called via TimeHelper echo $this->Time->dayAsSql(Aug 22, 2011, modified); // (modified >= 2011-08-22 00:00:00) AND (modified <= 2011-08-22 23:59:59) // called as CakeTime App::uses(CakeTime, Utility); echo CakeTime::dayAsSql(Aug 22, 2011, modified);

Changed in version 2.2: $timezone parameter replaces $userOffset parameter used in 2.1 and below.New in version 2.2: $dateString parameter now also accepts a DateTime object. TimeHelper::daysAsSql($begin, $end, $eldName, $timezone = NULL) Return type string Returns a string in the format ($eld_name >= 2008-01-21 00:00:00) AND ($eld_name <= 200801-25 23:59:59). This is handy if you need to search for records between two dates inclusively:
// called via TimeHelper echo $this->Time->daysAsSql(Aug 22, 2011, Aug 25, 2011, created); // (created >= 2011-08-22 00:00:00) AND (created <= 2011-08-25 23:59:59) // called as CakeTime App::uses(CakeTime, Utility); echo CakeTime::daysAsSql(Aug 22, 2011, Aug 25, 2011, created);

Changed in version 2.2: $timezone parameter replaces $userOffset parameter used in 2.1 and below.New in version 2.2: $dateString parameter now also accepts a DateTime object.

230

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

TimeHelper::format($date, $format = NULL, $default = false, $timezone = NULL) Return type string Will return a string formatted to the given format using the PHP date() formatting options (http://www.php.net/manual/en/function.date.php):
// called via TimeHelper echo $this->Time->format(%F %jS, %Y %h:%i %A, 2011-08-22 11:53:00); // August 22nd, 2011 11:53 AM echo $this->Time->format(%r, +2 days); // 2 days from now formatted as Sun, 13 Nov 2011 03:36:10 +0800 // called as CakeTime App::uses(CakeTime, Utility); echo CakeTime::format(2011-08-22 11:53:00, %F %jS, %Y %h:%i %A); echo CakeTime::format(+2 days, %r);

You can also provide the date/time as the rst argument. When doing this you should use strftime compatible formatting. This call signature allows you to leverage locale aware date formatting which is not possible using date() compatible formatting:
// called via TimeHelper echo $this->Time->format(2012-01-13, %d-%m-%Y, invalid); // called as CakeTime App::uses(CakeTime, Utility); echo CakeTime::format(2011-08-22, %d-%m-%Y);

Changed in version 2.2: $format and $date parameters are in opposite order as used in 2.1 and below. $timezone parameter replaces $userOffset parameter used in 2.1 and below. $default parameter replaces $invalid parameter used in 2.1 and below.New in version 2.2: $date parameter now also accepts a DateTime object. TimeHelper::fromString($dateString, $timezone = NULL) Return type string Takes a string and uses strtotime (http://us.php.net/manual/en/function.date.php) to convert it into a date integer:
// called via TimeHelper echo $this->Time->fromString(Aug 22, 2011); // 1313971200 echo $this->Time->fromString(+1 days); // 1321074066 (+1 day from current date) // called as CakeTime App::uses(CakeTime, Utility); echo CakeTime::fromString(Aug 22, 2011); echo CakeTime::fromString(+1 days);

More about Views

231

CakePHP Cookbook Documentation, Release 2.x

Changed in version 2.2: $timezone parameter replaces $userOffset parameter used in 2.1 and below.New in version 2.2: $dateString parameter now also accepts a DateTime object. TimeHelper::gmt($dateString = NULL) Return type integer Will return the date as an integer set to Greenwich Mean Time (GMT).:
// called via TimeHelper echo $this->Time->gmt(Aug 22, 2011); // 1313971200 // called as CakeTime App::uses(CakeTime, Utility); echo CakeTime::gmt(Aug 22, 2011);

TimeHelper::i18nFormat($date, $format = NULL, $invalid = false, $timezone = NULL) Return type string Returns a formatted date string, given either a UNIX timestamp or a valid strtotime() date string. It take in account the default date format for the current language if a LC_TIME le is used. For more info about LC_TIME le check here. Changed in version 2.2: $timezone parameter replaces $userOffset parameter used in 2.1 and below. TimeHelper::nice($dateString = NULL, $timezone = NULL, $format = null) Return type string Takes a date string and outputs it in the format Tue, Jan 1st 2008, 19:25 or as per optional $format param passed:
// called via TimeHelper echo $this->Time->nice(2011-08-22 11:53:00); // Mon, Aug 22nd 2011, 11:53 // called as CakeTime App::uses(CakeTime, Utility); echo CakeTime::nice(2011-08-22 11:53:00);

TimeHelper::niceShort($dateString = NULL, $timezone = NULL) Return type string Takes a date string and outputs it in the format Jan 1st 2008, 19:25. If the date object is today, the format will be Today, 19:25. If the date object is yesterday, the format will be Yesterday, 19:25:
// called via TimeHelper echo $this->Time->niceShort(2011-08-22 11:53:00); // Aug 22nd, 11:53 // called as CakeTime App::uses(CakeTime, Utility); echo CakeTime::niceShort(2011-08-22 11:53:00);

232

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

Changed in version 2.2: $timezone parameter replaces $userOffset parameter used in 2.1 and below.New in version 2.2: $dateString parameter now also accepts a DateTime object. TimeHelper::serverOffset() Return type integer Returns servers offset from GMT in seconds. TimeHelper::timeAgoInWords($dateString, $options = array()) Return type string Will take a datetime string (anything that is parsable by PHPs strtotime() function or MySQLs datetime format) and convert it into a friendly word format like, 3 weeks, 3 days ago:
// called via TimeHelper echo $this->Time->timeAgoInWords(Aug 22, 2011); // on 22/8/11 echo $this->Time->timeAgoInWords(Aug 22, 2011, array(format => F jS, Y)); // on August 22nd, 2011 // called as CakeTime App::uses(CakeTime, Utility); echo CakeTime::timeAgoInWords(Aug 22, 2011); echo CakeTime::timeAgoInWords(Aug 22, 2011, array(format => F jS, Y));

Use the end option to determine the cutoff point to no longer will use words; default +1 month:

// called via TimeHelper echo $this->Time->timeAgoInWords(Aug 22, 2011, array(format => F jS, Y, end => // On Nov 10th, 2011 it would display: 2 months, 2 weeks, 6 days ago

// called as CakeTime App::uses(CakeTime, Utility); echo CakeTime::timeAgoInWords(Aug 22, 2011, array(format => F jS, Y, end => +

Use the accuracy option to determine how precise the output should be. You can use this to limit the output:
// If $timestamp is 1 month, 1 week, 5 days and 6 hours ago echo CakeTime::timeAgoInWords($timestamp, array( accuracy => array(month => month), end => 1 year )); // Outputs 1 month ago

Changed in version 2.2: The accuracy option was added.New in version 2.2: $dateString parameter now also accepts a DateTime object. TimeHelper::toAtom($dateString, $timezone = NULL) Return type string Will return a date string in the Atom format 2008-01-12T00:00:00Z Changed in version 2.2:

More about Views

233

CakePHP Cookbook Documentation, Release 2.x

$timezone parameter replaces $userOffset parameter used in 2.1 and below.New in version 2.2: $dateString parameter now also accepts a DateTime object. TimeHelper::toQuarter($dateString, $range = false) Return type mixed Will return 1, 2, 3 or 4 depending on what quarter of the year the date falls in. If range is set to true, a two element array will be returned with start and end dates in the format 2008-03-31:
// called via TimeHelper echo $this->Time->toQuarter(Aug 22, 2011); // Would print 3 $arr = $this->Time->toQuarter(Aug 22, 2011, true); /* Array ( [0] => 2011-07-01 [1] => 2011-09-30 ) */ // called as CakeTime App::uses(CakeTime, Utility); echo CakeTime::toQuarter(Aug 22, 2011); $arr = CakeTime::toQuarter(Aug 22, 2011, true);

New in version 2.2: $dateString parameter now also accepts a DateTime object.New in version 2.4: The new option parameters relativeString (defaults to %s ago) and absoluteString (defaults to on %s) to allow customization of the resulting output string are now available. TimeHelper::toRSS($dateString, $timezone = NULL) Return type string Will return a date string in the RSS format Sat, 12 Jan 2008 00:00:00 -0500 Changed in version 2.2: $timezone parameter replaces $userOffset parameter used in 2.1 and below.New in version 2.2: $dateString parameter now also accepts a DateTime object. TimeHelper::toUnix($dateString, $timezone = NULL) Return type integer A wrapper for fromString. Changed in version 2.2: $timezone parameter replaces $userOffset parameter used in 2.1 and below.New in version 2.2: $dateString parameter now also accepts a DateTime object. TimeHelper::toServer($dateString, $timezone = NULL, $format = Y-m-d H:i:s) Return type mixed New in version 2.2: Returns a formatted date in servers timezone. TimeHelper::timezone($timezone = NULL) Return type DateTimeZone 234 Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

New in version 2.2: Returns a timezone object from a string or the users timezone object. If the function is called without a parameter it tries to get timezone from Cong.timezone conguration variable. TimeHelper::listTimezones($lter = null, $country = null, $group = true) Return type array New in version 2.2: Returns a list of timezone identiers.
Testing Time

TimeHelper::isToday($dateString, $timezone = NULL) TimeHelper::isThisWeek($dateString, $timezone = NULL) TimeHelper::isThisMonth($dateString, $timezone = NULL) TimeHelper::isThisYear($dateString, $timezone = NULL) TimeHelper::wasYesterday($dateString, $timezone = NULL) TimeHelper::isTomorrow($dateString, $timezone = NULL) TimeHelper::isFuture($dateString, $timezone = NULL) New in version 2.4. TimeHelper::isPast($dateString, $timezone = NULL) New in version 2.4. TimeHelper::wasWithinLast($timeInterval, $dateString, $timezone = NULL) Changed in version 2.2: $timezone parameter replaces $userOffset parameter used in 2.1 and below.New in version 2.2: $dateString parameter now also accepts a DateTime object. All of the above functions return true or false when passed a date string. wasWithinLast takes an additional $timeInterval option:
// called via TimeHelper $this->Time->wasWithinLast($timeInterval, $dateString); // called as CakeTime App::uses(CakeTime, Utility); CakeTime::wasWithinLast($timeInterval, $dateString);

wasWithinLast takes a time interval which is a string in the format 3 months and accepts a time interval of seconds, minutes, hours, days, weeks, months and years (plural and not). If a time interval is not recognized (for example, if it is mistyped) then it will default to days. Using and Conguring Helpers You enable helpers in CakePHP by making a controller aware of them. Each controller has a $helpers property that lists the helpers to be made available in the view. To enable a helper in your view, add the name of the helper to the controllers $helpers array:

More about Views

235

CakePHP Cookbook Documentation, Release 2.x

class BakeriesController extends AppController { public $helpers = array(Form, Html, Js, Time); }

Adding helpers from plugins uses the plugin syntax used elsewhere in CakePHP:
class BakeriesController extends AppController { public $helpers = array(Blog.Comment); }

You can also add helpers from within an action, so they will only be available to that action and not the other actions in the controller. This saves processing power for the other actions that do not use the helper as well as help keep the controller better organized:
class BakeriesController extends AppController { public function bake() { $this->helpers[] = Time; } public function mix() { // The Time helper is not loaded here and thus not available } }

If you need to enable a helper for all controllers add the name of the helper to the $helpers array in /app/Controller/AppController.php (or create if not present). Remember to include the default Html and Form helpers:
class AppController extends Controller { public $helpers = array(Form, Html, Js, Time); }

You can pass options to helpers. These options can be used to set attribute values or modify behavior of a helper:
class AwesomeHelper extends AppHelper { public function __construct(View $view, $settings = array()) { parent::__construct($view, $settings); debug($settings); } } class AwesomeController extends AppController { public $helpers = array(Awesome => array(option1 => value1)); }

As of 2.3 the options are merged with the Helper::$settings property of the helper. One common setting to use is the className option, which allows you to create aliased helpers in your views. This feature is useful when you want to replace $this->Html or another common Helper reference with a custom implementation:
// app/Controller/PostsController.php class PostsController extends AppController { public $helpers = array(

236

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

Html => array( className => MyHtml ) ); } // app/View/Helper/MyHtmlHelper.php App::uses(HtmlHelper, View/Helper); class MyHtmlHelper extends HtmlHelper { // Add your code to override the core HtmlHelper }

The above would alias MyHtmlHelper to $this->Html in your views. Note: Aliasing a helper replaces that instance anywhere that helper is used, including inside other Helpers. Using helper settings allows you to declaratively congure your helpers and keep conguration logic out of your controller actions. If you have conguration options that cannot be included as part of a class declaration, you can set those in your controllers beforeRender callback:
class PostsController extends AppController { public function beforeRender() { parent::beforeRender(); $this->helpers[CustomStuff] = $this->_getCustomStuffSettings(); } }

Using Helpers Once youve congured which helpers you want to use in your controller, each helper is exposed as a public property in the view. For example, if you were using the HtmlHelper you would be able to access it by doing the following:
echo $this->Html->css(styles);

The above would call the css method on the HtmlHelper. You can access any loaded helper using $this->{$helperName}. There may come a time where you need to dynamically load a helper from inside a view. You can use the views HelperCollection to do this:
$mediaHelper = $this->Helpers->load(Media, $mediaSettings);

The HelperCollection is a collection and supports the collection API used elsewhere in CakePHP. Callback methods Helpers feature several callbacks that allow you to augment the view rendering process. See the Helper API and the Collections documentation for more information.

More about Views

237

CakePHP Cookbook Documentation, Release 2.x

Creating Helpers If a core helper (or one showcased on github or the Bakery) doesnt t your needs, helpers are easy to create. Lets say we wanted to create a helper that could be used to output a specically crafted CSS-styled link you needed many different places in your application. In order to t your logic in to CakePHPs existing helper structure, youll need to create a new class in /app/View/Helper. Lets call our helper LinkHelper. The actual PHP class le would look something like this:
/* /app/View/Helper/LinkHelper.php */ App::uses(AppHelper, View/Helper); class LinkHelper extends AppHelper { public function makeEdit($title, $url) { // Logic to create specially formatted link goes here... } }

Note: Helpers must extend either AppHelper or Helper or implement all the callbacks in the Helper API .

Including other Helpers

You may wish to use some functionality already existing in another helper. To do so, you can specify helpers you wish to use with a $helpers array, formatted just as you would in a controller:
/* /app/View/Helper/LinkHelper.php (using other helpers) */ App::uses(AppHelper, View/Helper); class LinkHelper extends AppHelper { public $helpers = array(Html); public function makeEdit($title, $url) { // Use the HTML helper to output // formatted data: $link = $this->Html->link($title, $url, array(class => edit)); return <div class="editOuter"> . $link . </div>; } }

Using your Helper

Once youve created your helper and placed it in /app/View/Helper/, youll be able to include it in your controllers using the special variable $helpers:

238

Chapter 5. Views

CakePHP Cookbook Documentation, Release 2.x

class PostsController extends AppController { public $helpers = array(Link); }

Once your controller has been made aware of this new class, you can use it in your views by accessing an object named after the helper:
 <?php echo $this->Link->makeEdit(Change this Recipe, /recipes/edit/5); ?>

Creating Functionality for All Helpers All helpers extend a special class, AppHelper (just like models extend AppModel and controllers extend AppController). To create functionality that would be available to all helpers, create /app/View/Helper/AppHelper.php:
App::uses(Helper, View); class AppHelper extends Helper { public function customMethod() { } }

Helper API class Helper The base class for Helpers. It provides a number of utility methods and features for loading other helpers. Helper::webroot($le) Resolve a le name to the webroot of the application. If a theme is active and the le exists in the current themes webroot, the path to the themed le will be returned. Helper::url($url, $full = false) Generates an HTML escaped URL, delegates to Router::url(). Helper::value($options = array(), $eld = null, $key = value) Get the value for a given input name. Helper::domId($options = null, $id = id) Generate a CamelCased id value for the currently selected eld. Overriding this method in your AppHelper will allow you to change how CakePHP generates ID attributes.
Callbacks

Helper::beforeRenderFile($viewFile) Is called before each view le is rendered. This includes elements, views, parent views and layouts.

More about Views

239

CakePHP Cookbook Documentation, Release 2.x

Helper::afterRenderFile($viewFile, $content) Is called after each view le is rendered. This includes elements, views, parent views and layouts. A callback can modify and return $content to change how the rendered content will be displayed in the browser. Helper::beforeRender($viewFile) The beforeRender method is called after the controllers beforeRender method but before the controller renders view and layout. Receives the le being rendered as an argument. Helper::afterRender($viewFile) Is called after the view has been rendered but before layout rendering has started. Helper::beforeLayout($layoutFile) Is called before layout rendering starts. Receives the layout lename as an argument. Helper::afterLayout($layoutFile) Is called after layout rendering is complete. Receives the layout lename as an argument.

240

Chapter 5. Views

CHAPTER 6

Models

Models are the classes that sit as the business layer in your application. This means that they should be responsible for managing almost everything that happens regarding your data, its validity, interactions and evolution of the information workow in your domain of work. Usually model classes represent data and are used in CakePHP applications for data access, more specically they represent a database table but they are not limited to this, but can be used to access anything that manipulates data such as les, external web services, iCal events, or rows in a CSV le. A model can be associated with other models. For example, a Recipe may be associated with the Author of the recipe as well as the Ingredient in the recipe. This section will explain what features of the model can be automated, how to override those features, and what methods and properties a model can have. Itll explain the different ways to associate your data. Itll describe how to nd, save, and delete data. Finally, itll look at Datasources.

Understanding Models
A Model represents your data model. In object-oriented programming a data model is an object that represents a thing, like a car, a person, or a house. A blog, for example, may have many blog posts and each blog post may have many comments. The Blog, Post, and Comment are all examples of models, each associated with another. Here is a simple example of a model denition in CakePHP:
App::uses(AppModel, Model); class Ingredient extends AppModel { public $name = Ingredient; }

With just this simple declaration, the Ingredient model is bestowed with all the functionality you need to create queries along with saving and deleting data. These magic methods come from CakePHPs Model class by the magic of inheritance. The Ingredient model extends the application model, AppModel, which extends CakePHPs internal Model class. It is this core Model class that bestows the functionality onto

241

CakePHP Cookbook Documentation, Release 2.x

your Ingredient model. App::uses(AppModel, Model) ensures that the model is lazy loaded in every instance of its usage. This intermediate class, AppModel, is empty and if you havent created your own, is taken from within the CakePHP core folder. Overriding the AppModel allows you to dene functionality that should be made available to all models within your application. To do so, you need to create your own AppModel.php le that resides in the Model folder, as all other models in your application. Creating a project using Bake will automatically generate this le for you. See also Behaviors for more information on how to apply similar logic to multiple models. Back to our Ingredient model, in order to work on it, create the PHP le in the /app/Model/ directory. By convention it should have the same name as the class; for this example Ingredient.php. Note: CakePHP will dynamically create a model object for you if it cannot nd a corresponding le in /app/Model. This also means that if your model le isnt named correctly (i.e. ingredient.php or Ingredients.php) CakePHP will use an instance of AppModel rather than your missing (from CakePHPs perspective) model le. If youre trying to use a method youve dened in your model, or a behavior attached to your model and youre getting SQL errors that are the name of the method youre calling - its a sure sign CakePHP cant nd your model and you either need to check the le names, your application cache, or both.

Note: Some class names are not usable for model names. For instance File cannot be used as File is a class already existing in the CakePHP core. With your model dened, it can be accessed from within your Controller. CakePHP will automatically make the model available for access when its name matches that of the controller. For example, a controller named IngredientsController will automatically initialize the Ingredient model and attach it to the controller at $this->Ingredient:
class IngredientsController extends AppController { public function index() { //grab all ingredients and pass it to the view: $ingredients = $this->Ingredient->find(all); $this->set(ingredients, $ingredients); } }

Associated models are available through the main model. In the following example, Recipe has an association with the Ingredient model:
class Recipe extends AppModel { public function steakRecipes() { $ingredient = $this->Ingredient->findByName(Steak); return $this->findAllByMainIngredient($ingredient[Ingredient][id]); } }

This shows how to use models that are already linked. To understand how associations are dened take a look at the Associations section 242 Chapter 6. Models

CakePHP Cookbook Documentation, Release 2.x

More on models
Associations: Linking Models Together
One of the most powerful features of CakePHP is the ability to link relational mapping provided by the model. In CakePHP, the links between models are handled through associations. Dening relations between different objects in your application should be a natural process. For example: in a recipe database, a recipe may have many reviews, reviews have a single author, and authors may have many recipes. Dening the way these relations work allows you to access your data in an intuitive and powerful way. The purpose of this section is to show you how to plan for, dene, and utilize associations between models in CakePHP. While data can come from a variety of sources, the most common form of storage in web applications is a relational database. Most of what this section covers will be in that context. For information on associations with Plugin models, see Plugin Models. Relationship Types The four association types in CakePHP are: hasOne, hasMany, belongsTo, and hasAndBelongsToMany (HABTM). Relationship one to one one to many many to one many to many Association Type hasOne hasMany belongsTo hasAndBelongsToMany Example A user has one prole. A user can have multiple recipes. Many recipes belong to a user. Recipes have, and belong to many ingredients.

Associations are dened by creating a class variable named after the association you are dening. The class variable can sometimes be as simple as a string, but can be as complete as a multidimensional array used to dene association specics.
class User extends AppModel { public $hasOne = Profile; public $hasMany = array( Recipe => array( className => Recipe, conditions => array(Recipe.approved => 1), order => Recipe.created DESC ) ); }

In the above example, the rst instance of the word Recipe is what is termed an Alias. This is an identier for the relationship and can be anything you choose. Usually, you will choose the same name as the class that it references. However, aliases for each model must be unique app wide. For example it is appropriate to have:

CakePHP Cookbook Documentation, Release 2.x

class User extends AppModel { public $hasMany = array( MyRecipe => array( className => Recipe, ) ); public $hasAndBelongsToMany = array( MemberOf => array( className => Group, ) ); } class Group extends AppModel { public $hasMany = array( MyRecipe => array( className => Recipe, ) ); public $hasAndBelongsToMany = array( Member => array( className => User, ) ); }

but the following will not work well in all circumstances:

class User extends AppModel { public $hasMany = array( MyRecipe => array( className => Recipe, ) ); public $hasAndBelongsToMany = array( Member => array( className => Group, ) ); } class Group extends AppModel { public $hasMany = array( MyRecipe => array( className => Recipe, ) ); public $hasAndBelongsToMany = array( Member => array( className => User, ) ); }

244

Chapter 6. Models

CakePHP Cookbook Documentation, Release 2.x

because here we have the alias Member referring to both the User (in Group) and the Group (in User) model in the HABTM associations. Choosing non-unique names for model aliases across models can cause unexpected behavior. Cake will automatically create links between associated model objects. So for example in your User model you can access the Recipe model as:
$this->Recipe->someFunction();

Similarly in your controller you can access an associated model simply by following your model associations:
$this->User->Recipe->someFunction();

Note: Remember that associations are dened one way. If you dene User hasMany Recipe that has no effect on the Recipe Model. You need to dene Recipe belongsTo User to be able to access the User model from your Recipe model

hasOne Lets set up a User model with a hasOne relationship to a Prole model. First, your database tables need to be keyed correctly. For a hasOne relationship to work, one table has to contain a foreign key that points to a record in the other. In this case the proles table will contain a eld called user_id. The basic pattern is: hasOne: the other model contains the foreign key. Relation Apple hasOne Banana User hasOne Prole Doctor hasOne Mentor Schema bananas.apple_id proles.user_id mentors.doctor_id

Note: It is not mandatory to follow CakePHP conventions, you can easily override the use of any foreignKey in your associations denitions. Nevertheless sticking to conventions will make your code less repetitive, easier to read and to maintain. The User model le will be saved in /app/Model/User.php. To dene the User hasOne Prole association, add the $hasOne property to the model class. Remember to have a Prole model in /app/Model/Prole.php, or the association wont work:
class User extends AppModel { public $hasOne = Profile; }

There are two ways to describe this relationship in your model les. The simplest method is to set the $hasOne attribute to a string containing the classname of the associated model, as weve done above. If you need more control, you can dene your associations using array syntax. For example, you might want to limit the association to include only certain records. More on models 245

CakePHP Cookbook Documentation, Release 2.x

class User extends AppModel { public $hasOne = array( Profile => array( className => Profile, conditions => array(Profile.published => 1), dependent => true ) ); }

Possible keys for hasOne association arrays include: className: the classname of the model being associated to the current model. If youre dening a User hasOne Prole relationship, the className key should equal Prole. foreignKey: the name of the foreign key found in the other model. This is especially handy if you need to dene multiple hasOne relationships. The default value for this key is the underscored, singular name of the current model, sufxed with _id. In the example above it would default to user_id. conditions: an array of nd() compatible conditions or SQL strings such as array(Prole.approved => true) elds: A list of elds to be retrieved when the associated model data is fetched. Returns all elds by default. order: an array of nd() compatible order clauses or SQL strings such as array(Prole.last_name => ASC) dependent: When the dependent key is set to true, and the models delete() method is called with the cascade parameter set to true, associated model records are also deleted. In this case we set it true so that deleting a User will also delete her associated Prole. Once this association has been dened, nd operations on the User model will also fetch a related Prole record if it exists:
//Sample results from a $this->User->find() call. Array ( [User] => Array ( [id] => 121 [name] => Gwoo the Kungwoo [created] => 2007-05-01 10:31:01 ) [Profile] => Array ( [id] => 12 [user_id] => 121 [skill] => Baking Cakes [created] => 2007-05-01 10:31:01 ) )

246

Chapter 6. Models

CakePHP Cookbook Documentation, Release 2.x

belongsTo Now that we have Prole data access from the User model, lets dene a belongsTo association in the Prole model in order to get access to related User data. The belongsTo association is a natural complement to the hasOne and hasMany associations: it allows us to see the data from the other direction. When keying your database tables for a belongsTo relationship, follow this convention: belongsTo: the current model contains the foreign key. Relation Banana belongsTo Apple Prole belongsTo User Mentor belongsTo Doctor Schema bananas.apple_id proles.user_id mentors.doctor_id

Tip: If a model(table) contains a foreign key, it belongsTo the other model(table). We can dene the belongsTo association in our Prole model at /app/Model/Prole.php using the string syntax as follows:
class Profile extends AppModel { public $belongsTo = User; }

We can also dene a more specic relationship using array syntax:

class Profile extends AppModel { public $belongsTo = array( User => array( className => User, foreignKey => user_id ) ); }

Possible keys for belongsTo association arrays include: className: the classname of the model being associated to the current model. If youre dening a Prole belongsTo User relationship, the className key should equal User. foreignKey: the name of the foreign key found in the current model. This is especially handy if you need to dene multiple belongsTo relationships. The default value for this key is the underscored, singular name of the other model, sufxed with _id. conditions: an array of nd() compatible array(User.active => true) conditions or SQL strings such as

type: the type of the join to use in the SQL query, default is LEFT which may not t your needs in all situations, INNER may be helpful when you want everything from your main and associated models or nothing at all! (effective when used with some conditions of course). (NB: type value is in lower case - i.e. left, inner) elds: A list of elds to be retrieved when the associated model data is fetched. Returns all elds by default. More on models 247

CakePHP Cookbook Documentation, Release 2.x

order: an array of nd() compatible array(User.username => ASC)

order

clauses

SQL

strings

such

counterCache: If set to true the associated Model will automatically increase or decrease the [singular_model_name]_count eld in the foreign table whenever you do a save() or delete(). If its a string then its the eld name to use. The value in the counter eld represents the number of related rows. You can also specify multiple counter caches by dening an array, see Multiple counterCache counterScope: Optional conditions array to use for updating counter cache eld. Once this association has been dened, nd operations on the Prole model will also fetch a related User record if it exists:
//Sample results from a $this->Profile->find() call. Array ( [Profile] => Array ( [id] => 12 [user_id] => 121 [skill] => Baking Cakes [created] => 2007-05-01 10:31:01 ) [User] => Array ( [id] => 121 [name] => Gwoo the Kungwoo [created] => 2007-05-01 10:31:01 ) )

hasMany Next step: dening a User hasMany Comment association. A hasMany association will allow us to fetch a users comments whe