![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 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 default, so you may just need to remove the leading
# symbols.
After you make changes, restart Apache to make sure the settings are active.
Verify that your .htaccess files are actually in the right directories. Some operating systems treat files
that start with ‘.’ as hidden and therefore won’t copy them.
3. Make sure your copy of CakePHP comes from the downloads section of the site or our Git repository,
and has been unpacked correctly, by checking for .htaccess files.
CakePHP root directory (must be copied to your document; redirects everything to your CakePHP
app):
<IfModule mod_rewrite.c>
RewriteEngine on
RewriteRule ^ $ app/webroot/ [L]
RewriteRule (.*) app/webroot/ $ 1 [L]
</IfModule>
CakePHP app directory (will be copied to the top directory of your application by bake):
<IfModule mod_rewrite.c>
RewriteEngine on
RewriteRule ^ $ webroot/ [L]
RewriteRule (.*) webroot/ $ 1 [L]
</IfModule>
CakePHP webroot directory (will be copied to your application’s web root by bake):
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^(.*) $ index.php [QSA,L]
</IfModule>
If your CakePHP site still has problems with mod_rewrite, you might want to try modifying settings
for Virtual Hosts. On Ubuntu, edit the file /etc/apache2/sites-available/default (location is distribution-
dependent). In this file, ensure that AllowOverride None is changed to AllowOverride
A Note on mod_rewrite 7](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-13-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
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>
On Mac OSX, another solution is to use the tool virtualhostx2 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 direc-
tory (http://example.com/~username/cakephp/), or any other URL structure that already utilizes
mod_rewrite, you’ll need to add RewriteBase statements to the .htaccess files CakePHP uses (/.htac-
cess, /app/.htaccess, /app/webroot/.htaccess).
This can be added to the same section with the RewriteEngine directive, so for example, your webroot
.htaccess file 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
related to CakePHP. Please refer to Apache’s 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
webserver’s 404 page.
Additionally you can create a matching HTML 404 page, or use the default built-in CakePHP 404 by
adding an ErrorDocument directive:
2
http://clickontyler.com/virtualhostx/
8 Chapter 2. Blog Tutorial](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-14-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
2. Create a new file called web.config in your CakePHP root folder.
3. Using Notepad or any XML-safe editor, copy the following code into your new web.config file...
<?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)"
stopProcessing="true">
<match url="^(img|css|files|js|favicon.ico)(.*)$" />
<action type="Rewrite" url="app/webroot/{R:1}{R:2}"
appendQueryString="false" />
</rule>
<rule name="Rewrite requested file/folder to index.php"
stopProcessing="true">
<match url="^(.*)$" ignoreCase="false" />
<action type="Rewrite" url="index.php"
appendQueryString="true" />
</rule>
</rules>
</rewrite>
</system.webServer>
</configuration>
Once the web.config file is created with the correct IIS-friendly rewrite rules, CakePHP’s links, CSS, JavaS-
cipt, and rerouting should work correctly.
URL-Rewriting on lighttpd
Lighttpd does not support .htaccess functions, so you can remove all .htaccess files. In the lighttpd configu-
ration, make sure you’ve activated “mod_rewrite”. Add a line:
url.rewrite-if-not-file =(
"^([^?]*)(?(.+))?$" => "/index.php?url=$1&$3"
)
URL rewrite rules for Hiawatha
The required UrlToolkit rule (for URL rewriting) to use CakePHP with Hiawatha is:
10 Chapter 2. Blog Tutorial](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-16-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
(
[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] =>
)
)
)
CakePHP’s view files are stored in /app/View inside a folder named after the controller to which they
correspond. (We’ll have to create a folder named ‘Posts’ in this case.) To format this post data into a nice
table, our view code might look something like this
<!-- File: /app/View/Posts/index.ctp -->
<h1>Blog posts</h1>
<table>
<tr>
<th>Id</th>
<th>Title</th>
<th>Created</th>
</tr>
<!-- Here is where we loop through our $posts array, printing out post info -->
<?php foreach ($posts as $post): ?>
Creating Post Views 15](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-21-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
<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>
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 what’s important to
note here is that the link() method will generate an HTML link with the given title (the first parameter)
and URL (the second parameter).
When specifying URLs in CakePHP, 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
CakePHP’s 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 (which link a post’s title to a URL
/posts/view/some_id), you were probably informed by CakePHP that the action hadn’t yet been defined. If
you were not so informed, either something has gone wrong, or you actually did define it already, in which
case you are very sneaky. Otherwise, we’ll create it in the PostsController now:
// File: /app/Controller/PostsController.php
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 we’re using findById() rather than find(’all’) be-
16 Chapter 3. Blog Tutorial - Adding a layer](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-22-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
cause we only want a single post’s information.
Notice that our view action takes a parameter: the ID of the post we’d 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 that 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 let’s create the view for our new ‘view’ action and place it in /app/View/Posts/view.ctp
<!-- File: /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 let’s allow for adding new posts.
First, start by creating an add() action in the PostsController:
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)) {
Adding Posts 17](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-23-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
<?php
echo $this->Form->create(’Post’);
echo $this->Form->input(’title’);
echo $this->Form->input(’body’, array(’rows’ => ’3’));
echo $this->Form->input(’id’, array(’type’ => ’hidden’));
echo $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’ field is present in the
data array. If no ‘id’ is present (look back at our add view), CakePHP will assume that you are inserting a
new model when save() is called.
You can now update your index view with links to edit specific posts:
<!-- File: /app/View/Posts/index.ctp (edit links added) -->
<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>
<!-- Here’s where we loop through our $posts array, printing out post info -->
<?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’, $post[’Post’][’id’])
);
?>
</td>
<td>
<?php
echo $this->Html->link(
’Edit’,
array(’action’ => ’edit’, $post[’Post’][’id’])
);
?>
</td>
<td>
<?php echo $post[’Post’][’created’]; ?>
</td>
</tr>
Editing Posts 21](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-27-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
<?php endforeach; ?>
</table>
Deleting Posts
Next, let’s 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 specified by $id, and uses $this->Session->setFlash() to show the
user a confirmation 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 CakePHP’s 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 we’re 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:
<!-- File: /app/View/Posts/index.ctp -->
<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>
<!-- Here’s where we loop through our $posts array, printing out post info -->
<?php foreach ($posts as $post): ?>
<tr>
<td><?php echo $post[’Post’][’id’]; ?></td>
<td>
<?php
echo $this->Html->link(
$post[’Post’][’title’],
22 Chapter 3. Blog Tutorial - Adding a layer](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-28-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
array(’action’ => ’view’, $post[’Post’][’id’])
);
?>
</td>
<td>
<?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’][’id’])
);
?>
</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 to delete our post. Al-
lowing 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 confirmation dialog
before they attempt to delete a post.
Routes
For some, CakePHP’s default routing works well enough. Developers who are sensitive to user-friendliness
and general search engine compatibility will appreciate the way that CakePHP’s URLs map to specific
actions. So we’ll just make a quick change to routes in this tutorial.
For more information on advanced routing techniques, see Routes Configuration.
By default, CakePHP responds to a request for the root of your site (e.g., http://www.example.com) using
its PagesController, rendering a view called “home”. Instead, we’ll replace this with our PostsController by
creating a routing rule.
CakePHP’s routing is found in /app/Config/routes.php. You’ll want to comment out or remove the
line that defines the default root route. It looks like this:
Router::connect(
’/’,
Routes 23](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-29-320.jpg)
![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 archived 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” link.
All current releases of CakePHP are hosted on GitHub1. GitHub houses both CakePHP itself as well as
many other plugins for CakePHP. The CakePHP releases are available at GitHub tags2.
Alternatively you can get fresh off the press code, with all the bug-fixes and up to the minute enhancements.
These can be accessed from GitHub by cloning the GitHub3 repository:
git clone git://github.com/cakephp/cakephp.git
Permissions
CakePHP uses the app/tmp directory for a number of different operations. A few examples would be
Model descriptions, cached views and session information.
As such, make sure the directory app/tmp and all its subdirectories in your CakePHP installation are
writable by the web server user.
One common issue is that the app/tmp directories and subdirectories must be writable both by the web server
and the command line user. On a UNIX system, if your web server user is different from your command
line user, you can run the following commands just once in your project to ensure that permissions will be
setup properly:
HTTPDUSER=‘ps aux | grep -E ’[a]pache|[h]ttpd|[_]www|[w]ww-data|[n]ginx’ | grep -v root | h
setfacl -R -m u: $ {HTTPDUSER}:rwx app/tmp
setfacl -R -d -m u: $ {HTTPDUSER}:rwx app/tmp
Setup
Setting up CakePHP can be as simple as slapping it in your web server’s document root, or as complex and
flexible 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 configure the web server’s document root, clean URLs, very se-
cure.
1
http://github.com/cakephp/cakephp
2
https://github.com/cakephp/cakephp/tags
3
http://github.com/cakephp/cakephp
34 Chapter 4. Installation](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-40-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
#
<Directory />
Options FollowSymLinks
AllowOverride All
# Order deny,allow
# Deny from all
</Directory>
2. Make sure you are loading 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 default, so you may just need to remove the leading
# symbols.
After you make changes, restart Apache to make sure the settings are active.
Verify that your .htaccess files are actually in the right directories. Some operating systems treat files
that start with ‘.’ as hidden and therefore won’t copy them.
3. Make sure your copy of CakePHP comes from the downloads section of the site or our Git repository,
and has been unpacked correctly, by checking for .htaccess files.
CakePHP root directory (must be copied to your document; redirects everything to your CakePHP
app):
<IfModule mod_rewrite.c>
RewriteEngine on
RewriteRule ^ $ app/webroot/ [L]
RewriteRule (.*) app/webroot/ $ 1 [L]
</IfModule>
CakePHP app directory (will be copied to the top directory of your application by bake):
<IfModule mod_rewrite.c>
RewriteEngine on
RewriteRule ^ $ webroot/ [L]
RewriteRule (.*) webroot/ $ 1 [L]
</IfModule>
CakePHP webroot directory (will be copied to your application’s web root by bake):
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^(.*) $ index.php [QSA,L]
</IfModule>
If your CakePHP site still has problems with mod_rewrite, you might want to try modifying settings
for Virtual Hosts. On Ubuntu, edit the file /etc/apache2/sites-available/default (location is distribution-
dependent). In this file, ensure that AllowOverride None is changed to AllowOverride
All, so you have:
40 Chapter 4. Installation](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-46-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
<Directory />
Options FollowSymLinks
AllowOverride All
</Directory>
<Directory /var/www>
Options Indexes FollowSymLinks MultiViews
AllowOverride All
Order Allow,Deny
Allow from all
</Directory>
On Mac OSX, another solution is to use the tool virtualhostx5 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 direc-
tory (http://example.com/~username/cakephp/), or any other URL structure that already utilizes
mod_rewrite, you’ll need to add RewriteBase statements to the .htaccess files CakePHP uses (/.htac-
cess, /app/.htaccess, /app/webroot/.htaccess).
This can be added to the same section with the RewriteEngine directive, so for example, your webroot
.htaccess file 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
related to CakePHP. Please refer to Apache’s 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
webserver’s 404 page.
Additionally you can create a matching HTML 404 page, or use the default built-in CakePHP 404 by
adding an ErrorDocument directive:
5
http://clickontyler.com/virtualhostx/
Advanced Installation and URL Rewriting 41](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-47-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
2. Create a new file called web.config in your CakePHP root folder.
3. Using Notepad or any XML-safe editor, copy the following code into your new web.config file...
<?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)"
stopProcessing="true">
<match url="^(img|css|files|js|favicon.ico)(.*)$" />
<action type="Rewrite" url="app/webroot/{R:1}{R:2}"
appendQueryString="false" />
</rule>
<rule name="Rewrite requested file/folder to index.php"
stopProcessing="true">
<match url="^(.*)$" ignoreCase="false" />
<action type="Rewrite" url="index.php"
appendQueryString="true" />
</rule>
</rules>
</rewrite>
</system.webServer>
</configuration>
Once the web.config file is created with the correct IIS-friendly rewrite rules, CakePHP’s links, CSS, JavaS-
cipt, and rerouting should work correctly.
URL-Rewriting on lighttpd
Lighttpd does not support .htaccess functions, so you can remove all .htaccess files. In the lighttpd configu-
ration, make sure you’ve activated “mod_rewrite”. Add a line:
url.rewrite-if-not-file =(
"^([^?]*)(?(.+))?$" => "/index.php?url=$1&$3"
)
URL rewrite rules for Hiawatha
The required UrlToolkit rule (for URL rewriting) to use CakePHP with Hiawatha is:
Advanced Installation and URL Rewriting 43](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-49-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
}
public function search($query) {
//action logic goes here..
}
}
The view files for these actions would be app/View/Recipes/view.ctp,
app/View/Recipes/share.ctp, and app/View/Recipes/search.ctp. The conventional
view file name is the lowercased 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 don’t 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 you’d like to skip the default behavior, both of the following techniques will bypass 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 you use controller methods with requestAction(), you will often want to return data that isn’t
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 nor-
mal requests. Returning array data to a non-requestAction request will cause errors and should be avoided.
See the section on requestAction() for more tips on using requestAction()
In order for you to use a controller effectively in your own application, we’ll cover some of the core attributes
and methods provided by CakePHP’s controllers.
Request Life-cycle callbacks
class Controller
CakePHP controllers come fitted 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. It’s a handy place to check for an active
Request Life-cycle callbacks 53](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-59-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
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() != ’/’) {
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 user’s 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 find 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 CakePHP’s FormHelper and HtmlHelper to create a quick form
58 Chapter 6. Controllers](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-64-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
based on the Order model. Then a controller action can use the data posted from that form to craft
find 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->find() 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(
’Order’ => array(
’num_items’ => ’4’,
’referrer’ => ’Ye Olde’
)
)
*/
// Let’s 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 find
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, fields 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
find 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 controller’s 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.
Controller Methods 59](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-65-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
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. Let’s 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’, ’limit’ => 10)
);
}
}
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 it’s
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 file exists and is valid.
In addition, requestAction() now takes array based cake style URLs:
echo $this->requestAction(
array(’controller’ => ’articles’, ’action’ => ’featured’),
array(’return’)
);
60 Chapter 6. Controllers](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-66-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
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 client’s
IP address, and the subdomain/domain information about the application the server is running on.
• Provide access to request parameters both as array indexes and object properties.
Accessing request parameters
CakeRequest exposes several interfaces for accessing request parameters. The first uses object properties,
the second uses array indexes, and the third uses $this->request->params:
$this->request->controller;
$this->request[’controller’];
$this->request->params[’controller’];
All of the above will access the same value. Multiple ways of accessing the parameters have been provided
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’];
All of these will provide you access to the passed arguments and named parameters. There are several im-
portant/useful parameters that CakePHP uses internally. These are also all found in the request parameters:
• plugin The plugin handling the request. Will be null when there is no plugin.
• controller The controller handling the current request.
• action The action handling the current request.
• prefix The prefix for the current action. See Prefix 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().
64 Chapter 6. Controllers](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-70-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
Accessing Querystring parameters
Querystring parameters can be read using CakeRequest::$query:
// URL is /posts/index?page=1&sort=title
$this->request->query[’page’];
// You can also access it via an array
// Note: BC accessor, will be deprecated in future versions
$this->request[’url’][’page’];
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 prefix
will have that data prefix 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 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’);
More on controllers 65](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-71-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
CakeRequest::input($callback[, $options])
Retrieve the input data for a request, and optionally pass it through a decoding function. Useful when
interacting with XML or JSON request body content. Additional parameters for the decoding function
can be passed as arguments to input():
$this->request->input(’json_decode’);
CakeRequest::data($name)
Provides dot notation access to request data. Allows request data to be read and modified. Calls can
be chained together as well:
// 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 criterion. Uses the built-in detection rules as well
as any additional rules defined with CakeRequest::addDetector().
CakeRequest::addDetector($name, $options)
Add a detector to be used with CakeRequest::is(). See Inspecting the request for more infor-
mation.
CakeRequest::accepts($type = null)
Find out which content types the client accepts, or check whether it accepts 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 all the languages accepted by the client, or check whether a specific language is accepted.
Get the list of accepted languages:
CakeRequest::acceptLanguage();
Check whether a specific language is accepted:
More on controllers 69](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-75-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
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 application’s responses with CakeResponse::type(). If
your application needs to deal with content types that are not built into CakeResponse, you can map
them with CakeResponse::type() as well:
// Add a vCard type
$this->response->type(array(’vcf’ => ’text/v-card’));
// Set the response Content-Type to vcard.
$this->response->type(’vcf’);
Usually, you’ll want to map additional content types in your controller’s beforeFilter() callback,
so you can leverage the automatic view switching features of RequestHandlerComponent if you are
using it.
Sending files
There are times when you want to send files as responses for your requests. Prior to version 2.3, you could
use MediaView. As of 2.3, MediaView is deprecated and you can use CakeResponse::file() to
send a file as response:
public function sendFile($id) {
$file = $this->Attachment->getFile($id);
$this->response->file($file[’path’]);
// Return response object to prevent controller from trying to render
// a view
return $this->response;
}
As shown in the above example, you must pass the file path to the method. CakePHP will send a proper
content type header if it’s a known file type listed in CakeResponse::$_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 file to be downloaded instead of displayed in the browser by specifying the
options:
$this->response->file(
$file[’path’],
array(’download’ => true, ’name’ => ’foo’)
);
Sending a string as file
You can respond with a file that does not exist on the disk, such as a pdf or an ics generated on the fly from
a string:
More on controllers 71](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-77-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
The Last Modified header
New in version 2.1.
Under the HTTP cache validation model, you can also set the Last-Modified header to indicate the
date and time at which the resource was modified for the last time. Setting this header helps CakePHP tell
caching clients whether the response was modified or not based on their cache.
To take advantage of this header, you must either call the CakeResponse::checkNotModified()
method manually or include the RequestHandlerComponent 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 content using the same URL. This is often the case if
you have a multilingual page or respond with different HTML depending on the browser. Under such
circumstances you can 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 having methods spread across several objects, you only have to mock a single
object, since controllers and components delegate to CakeResponse. This helps you to 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 run tests from the command line more easily, as you can use mocks to avoid the
‘headers sent’ errors that can occur when trying to set headers in CLI.
More on controllers 75](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-81-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
• layouts: view files that contain presentational code that wraps many interfaces in your application.
Most views are rendered inside 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 specific view being rendered. By extending a common view file, you can avoid repeating
the common markup for your sidebar, and only define 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 file could be used as a parent view. It expects that the view extending it will define the
sidebar and title blocks. The content block is a special block that CakePHP creates. It will contain
all the uncaptured content from the extending view. Assuming our view file has a $post variable with the
data about our post, the 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’]);
86 Chapter 7. Views](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-92-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
)
);
Element caching is facilitated through the Cache class. You can configure elements to be stored in any
Cache configuration you’ve set up. This gives you a great amount of flexibility 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(), which 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, 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 five 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 configuration. Otherwise, you can set which cache configuration
Elements 93](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-99-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
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 files should be put in App/View. For example: App/View/PdfView.php
• View classes should be suffixed with View. For example: PdfView.
• When referencing view class names you should omit the View suffix. For example:
$this->viewClass = ’Pdf’;.
You’ll also want to extend View to ensure things work correctly:
// in App/View/PdfView.php
App::uses(’View’, ’View’);
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 files. To call any view method use
$this->method()
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 file 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 file you can do:
$this->set(’activeMenuButton’, ’posts’);
Then, in your layout, the $activeMenuButton variable will be available and contain the value
‘posts’.
View::get(string $var, $default = null)
Get the value of a viewVar with the name $var.
As of 2.5, you can provide a default value in case the variable is not already set.
Creating your own view classes 95](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-101-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
Using a data view with view files
You should use view files if you need to do some manipulation of your view content before creating the final
output. For example if we had posts, that had a field containing generated HTML, we would probably want
to omit that from a JSON response. This is a situation where a view file 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 complex manipulations, or use helpers to do formatting as well.
Note: The data view classes don’t support layouts. They assume that the view file 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 appli-
cation.
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 appli-
cation.
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 parameter
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 presen-
tational logic that is shared between many views, elements, or layouts. This chapter will show you how to
102 Chapter 7. Views](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-108-320.jpg)
![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
modified. 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 you’ve
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 files. If you need to clear the cached view files, 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 flexible
- it will do almost everything for you using conventions, or you can use specific methods to get only what
you need.
Creating Forms
The first method you’ll 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, I’d 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.
More about Views 105](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-111-320.jpg)
![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 form’s context.
All fields are assumed to belong to this model (unless otherwise specified), 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 prop-
erty to automatically detect whether to create an add or edit form. If $this->request->data
contains an array element named after the form’s model, and that array contains a non-empty value of
the model’s 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 field 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 configuration 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().
106 Chapter 7. Views](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-112-320.jpg)
![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’, ‘file’, ‘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 ‘file’ 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 file elements inside the
form. The absence of the proper enctype attribute will cause the file 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 specific action in your
current controller. For example, if you’d 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 isn’t 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’,
More about Views 107](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-113-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
’type’ => ’get’
));
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 form’s 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 form’s 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
// has a label element
echo $this->Form->input(
’username’,
array(’label’ => ’Username’)
);
Closing the Form
FormHelper::end($options = null, $secureAttributes = array())
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(); ?>
<!-- Form elements go here -->
<?php echo $this->Form->end(); ?>
If a string is supplied as the first parameter to end(), the FormHelper outputs a submit button named
accordingly along with the closing form tag:
<?php echo $this->Form->end(’Finish’); ?>
108 Chapter 7. Views](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-114-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
•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 field name with the
form helper methods, it’ll 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.fieldname as the
first parameter:
echo $this->Form->input(’Modelname.fieldname’);
If you need to specify multiple fields using the same field name, thus creating an array that can be saved in
one shot with saveAll(), use the following convention:
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 field-suffixes internally for datetime input creation. If you are using fields 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 specific to FormHelper::input().
• $options[’type’] You can force the type of an input, overriding model introspection, by spec-
ifying a type. In addition to the field types found in the Creating form elements, you can also create
‘file’, ‘password’, and any type supported by HTML5:
echo $this->Form->input(’field’, array(’type’ => ’file’));
echo $this->Form->input(’email’, array(’type’ => ’email’));
Output:
112 Chapter 7. Views](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-118-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
<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 input’s containing div. Using a string
value will set the div’s class name. An array will set the div’s attributes to those specified by the
array’s 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:
<div class="class_name">
<label for="UserName">Name</label>
<input name="data[User][name]" type="text" value="" id="UserName" />
</div>
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:
More about Views 113](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-119-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
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>
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 & field classes set the error key to false:
$this->Form->input(’Model.field’, array(’error’ => false));
To disable only the error message, but retain the field 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:
114 Chapter 7. Views](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-120-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
$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
• $options[’before’], $options[’between’], $options[’separator’], and
$options[’after’]
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--’,
More about Views 115](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-121-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
’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 by 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 find yourself repeating the same options in multiple in-
put() calls, you can use inputDefaults‘ to keep your code dry:
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 specific types of inputs
In addition to the generic input() method, FormHelper has specific 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.
116 Chapter 7. Views](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-122-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
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 class name 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 field. The value is used if the
data passed to the form does not contain a value for the field (or if no data is passed at all).
Example usage:
echo $this->Form->input(’ingredient’, array(’default’ => ’Sugar’));
Example with select field (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 fields’ default values can be set by using the ‘selected’ key.
Beware of using false to assign a default value. A false value is used to disable/exclude options of
an input field, 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.
More about Views 117](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-123-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
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 field to blank, use ‘value’ => ‘’ instead.
Options can also supplied as key-value pairs.
• $options[’hiddenField’] For certain input types (checkboxes, radios) a hidden input is cre-
ated so that the key in $this->request->data will exist even without a value specified:
<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 first. If the hidden input is on the page in multiple places, only
the last group of input’s 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" />
118 Chapter 7. Views](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-124-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
<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 field 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
in the order defined by the dateFormat option.
• $options[’minYear’], $options[’maxYear’] Used in combination with a
date/datetime input. Defines the lower and/or upper end of values shown in the years select
field.
• $options[’orderYear’] Used in combination with a date/datetime input. Defines the order in
which the year values will be set. Valid values include ‘asc’, ‘desc’. The default value is ‘desc’.
• $options[’interval’] This option specifies 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.
More about Views 119](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-125-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
• $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-Specific Methods
All elements are created under a form for the User model as in the examples above. For this
reason, the HTML code generated will contain attributes that reference to the User model. Ex:
name=data[User][username], id=UserUsername
FormHelper::label(string $fieldName, string $text, array $options)
Create a label element. $fieldName is used for generating the DOM id. If $text is undefined,
$fieldName will be used to inflect the label’s 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 class name:
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 specific 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’));
Will output:
<input name="data[User][username]" type="text" class="users"
id="UserUsername" />
FormHelper::password(string $fieldName, array $options)
Creates a password field.:
echo $this->Form->password(’password’);
Will output:
120 Chapter 7. Views](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-126-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
<input name="data[User][password]" value="" id="UserPassword"
type="password" />
FormHelper::hidden(string $fieldName, array $options)
Creates a hidden form input. Example:
echo $this->Form->hidden(’id’);
Will output:
<input name="data[User][id]" id="UserId" type="hidden" />
If the form is edited (that is, the array $this->request->data will contain the information
saved for the User model), the value corresponding to id field will automatically be added to the
HTML generated. Example for data[User][id] = 10:
<input name="data[User][id]" id="UserId" type="hidden" />
Changed in version 2.0: Hidden fields no longer remove the class attribute. This means that if there
are validation errors on hidden fields, the error-field class name will be applied.
FormHelper::textarea(string $fieldName, array $options)
Creates a textarea input field.:
echo $this->Form->textarea(’notes’);
Will output:
<textarea name="data[User][notes]" id="UserNotes"></textarea>
If the form is edited (that is, the array $this->request->data will contain the information
saved for the User model), the value corresponding to notes field will automatically be added to
the HTML generated. Example:
<textarea name="data[User][notes]" id="UserNotes">
This text is to be edited.
</textarea>
Note: The textarea input type allows for the $options attribute of ’escape’ which deter-
mines 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 specific options:
•$options[’rows’], $options[’cols’] These two keys specify the number of rows
and columns:
More about Views 121](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-127-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
echo $this->Form->textarea(
’textarea’,
array(’rows’ => ’5’, ’cols’ => ’5’)
);
Output:
<textarea name="data[Form][textarea]" cols="5" rows="5" id="FormTextarea">
</textarea>
FormHelper::checkbox(string $fieldName, array $options)
Creates a checkbox form element. This method also generates an associated hidden form input to
force the submission of data for the specified field.:
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 don’t 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 $fieldName, 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
first 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 legend and fieldset by de-
fault. Set $attributes[’legend’] to false to remove them.:
122 Chapter 7. Views](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-128-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
$options = array(’M’ => ’Male’, ’F’ => ’Female’);
$attributes = array(’legend’ => false);
echo $this->Form->radio(’gender’, $options, $attributes);
Will output:
<input name="data[User][gender]" id="UserGender_" value=""
type="hidden" />
<input name="data[User][gender]" id="UserGenderM" value="M"
type="radio" />
<label for="UserGenderM">Male</label>
<input name="data[User][gender]" id="UserGenderF" value="F"
type="radio" />
<label for="UserGenderF">Female</label>
If for some reason you don’t 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 $fieldName, array $options, array $attributes)
Creates a select element, populated with the items in $options, with the option specified
by $attributes[’value’] shown as selected by default. Set the ‘empty’ key in the
$attributes variable to false 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 specified 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>
More about Views 123](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-129-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
<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’,
’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
fieldsets:
$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’,
124 Chapter 7. Views](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-130-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
$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’
));
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="checkbox">
<label for="ModelField1">Label 1</label>
</div>
<div class="checkbox">
<input name="data[Model][field][]" value="Value 2"
id="ModelField2" type="checkbox">
<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="ModelField1" type="checkbox">
<label for="ModelField1">Label 1</label>
More about Views 125](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-131-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
</div>
<div class="checkbox">
<input name="data[Model][field][]" value="Value 2"
id="ModelField2" type="checkbox">
<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 $fieldName, array $options)
To add a file upload field to a form, you must first 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 file:
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 fields of type
‘file’. Each time the form is displayed, the value inside will be empty.
Upon submission, file fields 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 file
fields read the PHP manual section on file uploads2.
2
http://php.net/features.file-upload
126 Chapter 7. Views](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-132-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
Validating Uploads Below is an example validation method you could define in your model to validate
whether a file 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 file 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">
Note: When using $this->Form->file(), remember to set the form encoding-type, by setting the
type option to ‘file’ 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 specified title and a default type of “button”. Setting
More about Views 127](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-133-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
$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 $this->Form->button(’A Button’);
echo $this->Form->button(’Another Button’, array(’type’ => ’button’));
echo $this->Form->button(’Reset the Form’, array(’type’ => ’reset’));
echo $this->Form->button(’Submit Form’, array(’type’ => ’submit’));
Will output:
<button type="submit">A Button</button>
<button type="button">Another Button</button>
<button type="reset">Reset the Form</button>
<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:
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 $con-
firmMessage = 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.
Changed in version 2.5: The inline and block options were added. They allow buffering the
generated form tag, instead of returning with the link. This helps avoiding nested form tags. Setting
’inline’ => true will add the form tag to postLink content block or you can use option
block to specify a custom block.
128 Chapter 7. Views](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-134-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
Creating date and time inputs
FormHelper::dateTime($fieldName, $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 fields with the current datetime.
FormHelper::year(string $fieldName, 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>
FormHelper::month(string $fieldName, 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>
More about Views 129](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-135-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
<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’, array(’monthNames’ => false));
FormHelper::day(string $fieldName, 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 first option is ‘Day’), you can
supply the text as the final 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 $fieldName, boolean $format24Hours, array $attributes)
Creates a select element populated with the hours of the day.
FormHelper::minute(string $fieldName, array $attributes)
Creates a select element populated with the minutes of the hour.
FormHelper::meridian(string $fieldName, array $attributes)
Creates a select element populated with ‘am’ and ‘pm’.
Displaying and checking errors
FormHelper::error(string $fieldName, mixed $text, array $options)
Shows a validation error message, specified by $text, for the given field, 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 class name for the error message
FormHelper::isFieldError(string $fieldName)
Returns true if the supplied $fieldName has an active validation error.:
130 Chapter 7. Views](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-136-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
$this->Form->unlockField(’User.id’);
FormHelper::secure(array $fields = array())
Generates a hidden field with a security hash based on the fields 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
simplifies 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 pa-
rameters. You can override this default by supplying $options[’url’] in the second parameter of
$this->Form->create()
FormHelper::hidden()
Hidden fields no longer remove the class attribute. This means that if there are validation errors on hidden
fields, the error-field class name will be applied.
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 flexible 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:
132 Chapter 7. Views](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-138-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
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.
HtmlHelper::media(string|array $path, array $options)
Parameters
• $path (string|array) – Path to the video file, relative to the web-
root/{$options[’pathPrefix’]} 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 file’s mime type.
– text Text to include inside the video tag
– pathPrefix Path prefix to use for relative URLs, defaults to ‘files/’
– 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
140 Chapter 7. Views](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-146-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
<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=’theora, vorbis’"
)
),
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.
Returns text wrapped in a specified tag. If no text is specified 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
More about Views 141](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-147-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
• $class (string) – The class name 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 first parameter specifies 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 specified, 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 class name for the paragraph.
• $text (string) – The content inside the paragraph.
• $options (array) – An array of html attributes.
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 file, or an array of strings for
multiple files.
• $options (array) – An array of html attributes.
Include a script file(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.
142 Chapter 7. Views](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-148-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
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 defined 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:
$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 = ar-
ray(), 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’,
144 Chapter 7. Views](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-150-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
The JsHelper by default buffers almost all script code generated, allowing you to collect scripts through-
out 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 JavaScript libraries can change, a common
set of options is supported by JsHelper, these common options will be mapped out to the library specific
options 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 file 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 files.
JsHelper::writeBuffer($options = array())
Writes all JavaScript generated so far to a code block or caches them to a file 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 file 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)
More about Views 153](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-159-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
Event Options
•complete - Callback to fire on complete.
•success - Callback to fire on success.
•before - Callback to fire on request initialization.
•error - Callback to fire 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 eval’ed.
•dataExpression - Should the data key be treated as a callback. Useful for supplying
$options[’data’] as another JavaScript expression.
Example use:
$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.
156 Chapter 7. Views](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-162-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
•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 fired when the drag starts
•drag - Event fired on every step of the drag
•stop - Event fired 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
$("#element").draggable({
containment:"#content",
drag:onDrag,
grid:[10,10],
start:onStart,
stop:onStop
});
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 fired when an element is dropped into the drop zone.
•hover - Event fired when a drag enters a drop zone.
•leave - Event fired 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’,
More about Views 157](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-163-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
$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 being paginated, defaults to
PaginatorHelper::defaultModel().
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 configuration 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’)
));
Configuring the PaginatorHelper to use a JavaScript helper By default the PaginatorHelper uses
JsHelper to do AJAX features. However, if you don’t 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
It’s 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 doesn’t
always need to be restricted as such.
See the details on PaginatorHelper4 in the API. As mentioned, the PaginatorHelper also offers sorting fea-
tures which can be easily integrated into your table column headers:
// app/View/Posts/index.ctp
<table>
<tr>
<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>
4
http://api.cakephp.org/2.4/class-PaginatorHelper.html
More about Views 177](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-183-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
<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 field.
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 final 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}’
));
178 Chapter 7. Views](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-184-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
Other Methods
PaginatorHelper::link($title, $url = array(), $options = array())
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 Would create a link pointing at
‘/posts/index/page:5/sort:title/direction:desc’
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
More about Views 179](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-185-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
[nextPage] => 3
[pageCount] => 3
[order] =>
[limit] => 20
[options] => Array
(
[page] => 2
[conditions] => Array
(
)
)
[paramType] => named
)
*/
PaginatorHelper::param(string $key, string $model = null)
Gets the specific 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 we’ve 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, first we need to edit the controller to add in the rss-specific
code.
180 Chapter 7. Views](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-186-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
Controller Code It is a good idea to add RequestHandler to your PostsController’s $components array.
This will allow a lot of automagic to occur:
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 DESC’)
);
return $this->set(compact(’posts’));
}
// this is not an Rss request, so deliver
// data used by website’s 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, put the following contents in
app/View/Layouts/rss/default.ctp:
if (!isset($documentData)) {
$documentData = array();
}
if (!isset($channelData)) {
$channelData = array();
}
if (!isset($channelData[’title’])) {
$channelData[’title’] = $this->fetch(’title’);
More about Views 181](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-187-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
}
$channel = $this->Rss->channel(array(), $channelData, $this->fetch(’content’));
echo $this->Rss->document($documentData, $channel);
It doesn’t look like much but thanks to the power in the RssHelper it’s doing a lot of lifting for us. We
haven’t 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.
Next up is view file for my posts/index. Much like the layout file we created, we need to create a
View/Posts/rss/ directory and create a new index.ctp inside that folder. The contents of the file
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 Con-
troller::set() method. Here though we are passing the channel’s 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 ar-
ray 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.
182 Chapter 7. Views](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-188-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
$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’],
’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 filter 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 configuration 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 field
property RssHelper::$helpers
Helpers used by the RSS Helper
property RssHelper::$here
URL to current action
More about Views 183](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-189-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
When outputting this message, you can choose the element used to display the 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.
The failure element would contain something like this:
<div class="flash flash-failure">
<?php echo h($message); ?>
</div>
You can also pass additional parameters into the flash() method, which allows 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 escape the HTML in flash messages. If you are using any
request or user data in your flash messages, you should escape it with h when formatting your mes-
sages.
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 gracefully truncating long stretches of text.
Changed in version 2.1: Several TextHelper methods have been moved into the String class to allow
easier use outside of the View layer. Within a view, these methods are accessible via the TextHelper class.
You can call one 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.
186 Chapter 7. Views](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-192-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
contact info@example.com’;
$formattedText = $this->Text->autoParagraph($myText);
Output:
<p>For more information<br />
regarding our world-famous pastries and desserts.<p>
<p>contact info@example.com</p>
New in version 2.4.
TextHelper::highlight(string $haystack, string $needle, array $options = array())
Parameters
• $haystack (string) – The string to search.
• $needle (string) – The string to find.
• $options (array) – An array of options, see below.
Highlights $needle in $haystack using the $options[’format’] string specified or a de-
fault 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="highlight">1</span>’)
);
// called as String
App::uses(’String’, ’Utility’);
echo String::highlight(
$lastSentence,
’using’,
array(’format’ => ’<span class="highlight">1</span>’)
);
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)
188 Chapter 7. Views](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-194-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
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 user’s 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 appli-
cation’s time zone is set to GMT+0.
Next add a time zone field to your users table and make the necessary modifications 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 h:i A’,
$post[’Post’][’created’],
null,
$user[’User’][’time_zone’]
);
// Will display August 22nd, 2011 11:53 PM for a user in GMT+0
// August 22nd, 2011 03:53 PM for a user in GMT-8
// and August 23rd, 2011 09:53 AM GMT+10
Most of the Time Helper methods have a $timezone parameter. The $timezone parameter accepts a valid
timezone identifier string or an instance of DateTimeZone class.
Formatting
TimeHelper::convert($serverTime, $timezone = NULL)
Return type integer
Converts given time (in server’s time zone) to user’s 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
192 Chapter 7. Views](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-198-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
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: $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
More about Views 197](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-203-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
// 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 Configuring 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 controller’s $helpers array:
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 to the
other actions in the controller. This saves processing power for the other actions that do not use the helper
and helps 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 it 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:
More about Views 199](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-205-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
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(
’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 configure your helpers and keep configuration logic out
of your controller actions. If you have configuration options that cannot be included as part of a class
declaration, you can set those in your controller’s beforeRender callback:
class PostsController extends AppController {
public function beforeRender() {
parent::beforeRender();
$this->helpers[’CustomStuff’] = $this->_getCustomStuffSettings();
}
}
Using Helpers
Once you’ve configured 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
200 Chapter 7. Views](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-206-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
CakePHP’s internal Model class. It is this core Model class that bestows the functionality onto your In-
gredient model. App::uses(’AppModel’, ’Model’) ensures that the model is loaded when it is
needed.
The intermediate class, AppModel, is empty. If you haven’t created your own, it is taken from the CakePHP
core folder. Overriding the AppModel allows you to define functionality that should be made available to all
models within your application. To do so, you need to create your own AppModel.php file that resides in
the Model folder, as do all other models in your application. Creating a project using Bake will automatically
generate this file 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 file in the /app/Model/ directory. By
convention, it should have the same name as the class, which for this example will be Ingredient.php.
Note: CakePHP will dynamically create a model object for you if it cannot find a corresponding file in
/app/Model. This also means that if your model file isn’t named correctly (for instance, if it is named
ingredient.php or Ingredients.php rather than Ingredient.php), CakePHP will use an instance of AppModel
rather than your model file (which CakePHP assumes is missing). If you’re trying to use a method you’ve
defined in your model, or a behavior attached to your model, and you’re getting SQL errors that are the name
of the method you’re calling, it’s a sure sign that CakePHP can’t find your model and you need to check the
file names, your application cache, or both.
Note: Some class names are not usable for model names. For instance, “File” cannot be used, since “File”
is a class that already exists in the CakePHP core.
When your model is defined, 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 associa-
tion 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 defined, take a
206 Chapter 8. Models](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-212-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
If you need more control, you can define your associations using array syntax. For example, you might want
to limit the association to include only certain records.
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 class name of the model being associated to the current model. If you’re defining a
‘User hasOne Profile’ relationship, the className key should equal ‘Profile’.
• foreignKey: the name of the foreign key found in the other model. This is especially handy if you need
to define multiple hasOne relationships. The default value for this key is the underscored, singular
name of the current model, suffixed with ‘_id’. In the example above, it would default to ‘user_id’.
• conditions: an array of find()-compatible conditions or SQL strings such as array(‘Profile.approved’
=> true)
• fields: A list of fields to be retrieved when the associated model data is fetched. Returns all fields by
default.
• order: an array of find()-compatible order clauses or SQL strings such as array(‘Profile.last_name’
=> ‘ASC’)
• dependent: When the dependent key is set to true, and the model’s 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 Profile.
Once this association has been defined, find operations on the User model will also fetch a related Profile
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
210 Chapter 8. Models](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-216-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
• fields: A list of fields to be retrieved when the associated model data is fetched. Returns all fields by
default.
• order: an array of find() compatible order clauses or SQL strings such as
array(’User.username’ => ’ASC’)
• counterCache: If set to true, the associated Model will automatically increase or decrease the “[sin-
gular_model_name]_count” field in the foreign table whenever you do a save() or delete().
If it’s a string, then it’s the field name to use. The value in the counter field represents the number
of related rows. You can also specify multiple counter caches by defining an array. See Multiple
counterCache.
• counterScope: Optional conditions array to use for updating counter cache field.
Once this association has been defined, find operations on the Profile 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
)
)
counterCache - Cache your count()
This feature helps you cache the count of related data. Instead of counting the records manually via
find(’count’), the model itself tracks any addition/deletion towards the associated $hasMany model
and increases/decreases a dedicated integer field within the parent model table.
The name of the field consists of the singular model name followed by a underscore and the word “count”:
my_model_count
Let’s say you have a model called ImageComment and a model called Image. You would add a new
INT-field to the images table and name it image_comment_count.
Here are some more examples:
212 Chapter 8. Models](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-218-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
• foreignKey: the name of the foreign key found in the other model. This is especially handy if you
need to define multiple hasMany relationships. The default value for this key is the underscored,
singular name of the actual model, suffixed with ‘_id’.
• conditions: an array of find() compatible conditions or SQL strings such as array(‘Comment.visible’
=> true)
• order: an array of find() compatible order clauses or SQL strings such as array(‘Profile.last_name’
=> ‘ASC’)
• limit: The maximum number of associated rows you want returned.
• offset: The number of associated rows to skip over (given the current conditions and order) before
fetching and associating.
• dependent: When dependent is set to true, recursive model deletion is possible. In this example,
Comment records will be deleted when their associated User record has been deleted.
• exclusive: When exclusive is set to true, recursive model deletion does the delete with a deleteAll()
call, instead of deleting each entity separately. This greatly improves performance, but may not be
ideal for all circumstances.
• finderQuery: A complete SQL query CakePHP can use to fetch associated model records. This
should be used in situations that require highly customized results. If a query you’re building re-
quires a reference to the associated model ID, use the special {$__cakeID__$} marker in the
query. For example, if your Apple model hasMany Orange, the query should look something
like this: SELECT Orange.* from oranges as Orange WHERE Orange.apple_id
= {$__cakeID__$};
Once this association has been defined, find operations on the User model will also fetch related Comment
records if they exist:
//Sample results from a $this->User->find() call.
Array
(
[User] => Array
(
[id] => 121
[name] => Gwoo the Kungwoo
[created] => 2007-05-01 10:31:01
)
[Comment] => Array
(
[0] => Array
(
[id] => 123
[user_id] => 121
[title] => On Gwoo the Kungwoo
[body] => The Kungwooness is not so Gwooish
[created] => 2006-05-01 10:31:01
)
[1] => Array
(
More on models 215](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-221-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
[id] => 124
[user_id] => 121
[title] => More on Gwoo
[body] => But what of the ’ Nut?
[created] => 2006-05-01 10:41:01
)
)
)
One thing to remember is that you’ll need a complementary Comment belongsTo User association in order
to get the data from both directions. What we’ve outlined in this section empowers you to get Comment
data from the User. Adding the Comment belongsTo User association in the Comment model enables you
to get User data from the Comment model, completing the connection and allowing the flow of information
from either model’s perspective.
hasAndBelongsToMany (HABTM)
All right. At this point, you can already call yourself a CakePHP model associations professional. You’re
already well versed in the three associations that take up the bulk of object relations.
Let’s tackle the final relationship type: hasAndBelongsToMany, or HABTM. This association is used when
you have two models that need to be joined up, repeatedly, many times, in many different ways.
The main difference between hasMany and HABTM is that a link between models in HABTM is not exclu-
sive. For example, we’re about to join up our Recipe model with an Ingredient model using HABTM. Using
tomatoes as an Ingredient for my grandma’s spaghetti recipe doesn’t “use up” the ingredient. I can also use
it for a salad Recipe.
Links between hasMany associated objects are exclusive. If my User hasMany Comments, a comment is
only linked to a specific user. It’s not up for grabs.
Moving on. We’ll need to set up an extra table in the database to handle HABTM associations. This new join
table’s name needs to include the names of both models involved, in alphabetical order, and separated with
an underscore ( _ ). The contents of the table should be two fields that are foreign keys (which should be
integers) pointing to the primary keys of the involved models. To avoid any issues, don’t define a combined
primary key for these two fields. If your application requires a unique index, you can define one. If you plan
to add any extra information to this table, or use a ‘with’ model, you should add an additional primary key
field (by convention ‘id’).
HABTM requires a separate join table that includes both model names.
Relationship HABTM Table Fields
Recipe HABTM
Ingredient
ingredients_recipes.id, ingredients_recipes.ingredient_id,
ingredients_recipes.recipe_id
Cake HABTM Fan cakes_fans.id, cakes_fans.cake_id, cakes_fans.fan_id
Foo HABTM Bar bars_foos.id, bars_foos.foo_id, bars_foos.bar_id
Note: Table names are in alphabetical order by convention. It is possible to define a custom table name in
association definition.
216 Chapter 8. Models](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-222-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
– When false, CakePHP will insert the specified new relationship records and leave any ex-
isting relationship records in place, possibly resulting in duplicate relationship records.
– When set to keepExisting, the behavior is similar to true, but with an additional check
so that if any of the records to be added are duplicates of an existing relationship record, the
existing relationship record is not deleted, and the duplicate is ignored. This can be useful
if, for example, the join table has additional data in it that needs to be retained.
• conditions: an array of find()-compatible conditions or SQL string. If you have conditions on an
associated table, you should use a ‘with’ model, and define the necessary belongsTo associations on
it.
• fields: A list of fields to be retrieved when the associated model data is fetched. Returns all fields by
default.
• order: an array of find()-compatible order clauses or SQL strings
• limit: The maximum number of associated rows you want returned.
• offset: The number of associated rows to skip over (given the current conditions and order) before
fetching and associating.
• finderQuery: A complete SQL query CakePHP can use to fetch associated model records. This
should be used in situations that require highly customized results.
Once this association has been defined, find operations on the Recipe model will also fetch related Tag
records if they exist:
// Sample results from a $this->Recipe->find() call.
Array
(
[Recipe] => Array
(
[id] => 2745
[name] => Chocolate Frosted Sugar Bombs
[created] => 2007-05-01 10:31:01
[user_id] => 2346
)
[Ingredient] => Array
(
[0] => Array
(
[id] => 123
[name] => Chocolate
)
[1] => Array
(
[id] => 124
[name] => Sugar
)
[2] => Array
(
[id] => 125
[name] => Bombs
218 Chapter 8. Models](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-224-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
’foreignKey’ => ’user_id’
),
’MessageReceived’ => array(
’className’ => ’Message’,
’foreignKey’ => ’recipient_id’
)
);
}
It is also possible to create self associations as shown below:
class Post extends AppModel {
public $belongsTo = array(
’Parent’ => array(
’className’ => ’Post’,
’foreignKey’ => ’parent_id’
)
);
public $hasMany = array(
’Children’ => array(
’className’ => ’Post’,
’foreignKey’ => ’parent_id’
)
);
}
Fetching a nested array of associated records:
If your table has a parent_id field, you can also use find(‘threaded’) to fetch a nested array of records
using a single query without setting up any associations.
Joining tables
In SQL, you can combine related tables using the JOIN statement. This allows you to perform complex
searches across multiple tables (for example, search posts given several tags).
In CakePHP, some associations (belongsTo and hasOne) perform automatic joins to retrieve data, so you
can issue queries to retrieve models based on data in the related one.
But this is not the case with hasMany and hasAndBelongsToMany associations. Here is where forcing joins
comes to the rescue. You only have to define the necessary joins to combine tables and get the desired results
for your query.
Note: Remember that you need to set the recursion to -1 for this to work: $this->Channel->recursive = -1;
To force a join between tables, you need to use the “modern” syntax for Model::find(), adding a ‘joins’ key
to the $options array. For example:
$options[’joins’] = array(
array(’table’ => ’channels’,
More on models 223](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-229-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
’alias’ => ’Channel’,
’type’ => ’LEFT’,
’conditions’ => array(
’Channel.id = Item.channel_id’,
)
)
);
$Item->find(’all’, $options);
Note: Note that the ‘join’ arrays are not keyed.
In the above example, a model called Item is left-joined to the channels table. You can alias the table with
the Model name, so the retrieved data complies with the CakePHP data structure.
The keys that define the join are the following:
• table: The table for the join.
• alias: An alias to the table. The name of the model associated with the table is the best bet.
• type: The type of join: inner, left or right.
• conditions: The conditions to perform the join.
With joins, you could add conditions based on Related model fields:
$options[’joins’] = array(
array(’table’ => ’channels’,
’alias’ => ’Channel’,
’type’ => ’LEFT’,
’conditions’ => array(
’Channel.id = Item.channel_id’,
)
)
);
$options[’conditions’] = array(
’Channel.private’ => 1
);
$privateItems = $Item->find(’all’, $options);
You could perform several joins as needed in hasAndBelongsToMany:
Suppose there is a Book hasAndBelongsToMany Tag association. This relation uses a books_tags table as a
join table, so you need to join the books table to the books_tags table, and this with the tags table:
$options[’joins’] = array(
array(’table’ => ’books_tags’,
’alias’ => ’BooksTag’,
’type’ => ’inner’,
’conditions’ => array(
’Book.id = BooksTag.book_id’
224 Chapter 8. Models](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-230-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
)
),
array(’table’ => ’tags’,
’alias’ => ’Tag’,
’type’ => ’inner’,
’conditions’ => array(
’BooksTag.tag_id = Tag.id’
)
)
);
$options[’conditions’] = array(
’Tag.tag’ => ’Novel’
);
$books = $Book->find(’all’, $options);
Using joins allows you to have maximum flexibility in how CakePHP handles associations and fetches the
data. However, in most cases, you can use other tools to achieve the same results such as correctly defining
associations, binding models on the fly and using the Containable behavior. This feature should be used
with care because it could lead, in a few cases, into ill-formed SQL queries if combined with any of the
former techniques described for associating models.
Retrieving Your Data
As stated before, one of the roles of the Model layer is to get data from multiple types of storage. The
CakePHP Model class comes with some functions that will help you search for this data, sort it, paginate it,
and filter it. The most common function you will use in models is Model::find()
find
find(string $type = ’first’, array $params = array())
Find is the multifunctional workhorse of all model data-retrieval functions. $type can be ’all’,
’first’, ’count’, ’list’, ’neighbors’ or ’threaded’, or any custom finder you can de-
fine. Keep in mind that $type is case-sensitive. Using an upper case character (for example, All) will not
produce the expected results.
$params is used to pass all parameters to the various types of find(), and has the following possible keys
by default, all of which are optional:
array(
’conditions’ => array(’Model.field’ => $thisValue), //array of conditions
’recursive’ => 1, //int
//array of field names
’fields’ => array(’Model.field1’, ’DISTINCT Model.field2’),
//string or array defining order
’order’ => array(’Model.created’, ’Model.field3 DESC’),
’group’ => array(’Model.field’), //fields to GROUP BY
’limit’ => n, //int
More on models 225](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-231-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
’page’ => n, //int
’offset’ => n, //int
’callbacks’ => true //other possible values are false, ’before’, ’after’
)
It’s also possible to add and use other parameters. Some types of find() and behaviors make use of this
ability, and your own model methods can, too.
If your find() operation fails to match any records, you will get an empty array.
find(‘first’)
find(’first’, $params) will return one result. You’d use this for any case where you expect only
one result. Below are a couple of simple (controller code) examples:
public function some_function() {
// ...
$semiRandomArticle = $this->Article->find(’first’);
$lastCreated = $this->Article->find(’first’, array(
’order’ => array(’Article.created’ => ’desc’)
));
$specificallyThisOne = $this->Article->find(’first’, array(
’conditions’ => array(’Article.id’ => 1)
));
// ...
}
In the first example, no parameters at all are passed to find, so no conditions or sort order will be used. The
format returned from find(’first’) call is of the form:
Array
(
[ModelName] => Array
(
[id] => 83
[field1] => value1
[field2] => value2
[field3] => value3
)
[AssociatedModelName] => Array
(
[id] => 1
[field1] => value1
[field2] => value2
[field3] => value3
)
)
226 Chapter 8. Models](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-232-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
find(‘count’)
find(’count’, $params) returns an integer value. Below are a couple of simple (controller code)
examples:
public function some_function() {
// ...
$total = $this->Article->find(’count’);
$pending = $this->Article->find(’count’, array(
’conditions’ => array(’Article.status’ => ’pending’)
));
$authors = $this->Article->User->find(’count’);
$publishedAuthors = $this->Article->find(’count’, array(
’fields’ => ’DISTINCT Article.user_id’,
’conditions’ => array(’Article.status !=’ => ’pending’)
));
// ...
}
Note: Don’t pass fields as an array to find(’count’). You would only need to specify fields for a
DISTINCT count (since otherwise, the count is always the same, dictated by the conditions).
find(‘all’)
find(’all’, $params) returns an array of potentially multiple results. It is, in fact, the mechanism
used by all find() variants, as well as paginate. Below are a couple of simple (controller code)
examples:
public function some_function() {
// ...
$allArticles = $this->Article->find(’all’);
$pending = $this->Article->find(’all’, array(
’conditions’ => array(’Article.status’ => ’pending’)
));
$allAuthors = $this->Article->User->find(’all’);
$allPublishedAuthors = $this->Article->User->find(’all’, array(
’conditions’ => array(’Article.status !=’ => ’pending’)
));
// ...
}
Note: In the above example, $allAuthors will contain every user in the users table. There will be no
condition applied to the find, since none were passed.
The results of a call to find(’all’) will be of the following form:
Array
(
[0] => Array
(
More on models 227](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-233-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
[ModelName] => Array
(
[id] => 83
[field1] => value1
[field2] => value2
[field3] => value3
)
[AssociatedModelName] => Array
(
[id] => 1
[field1] => value1
[field2] => value2
[field3] => value3
)
)
)
find(‘list’)
find(’list’, $params) returns an indexed array, useful for any place where you would want a list,
such as for populating input select boxes. Below are a couple of simple (controller code) examples:
public function some_function() {
// ...
$allArticles = $this->Article->find(’list’);
$pending = $this->Article->find(’list’, array(
’conditions’ => array(’Article.status’ => ’pending’)
));
$allAuthors = $this->Article->User->find(’list’);
$allPublishedAuthors = $this->Article->find(’list’, array(
’fields’ => array(’User.id’, ’User.name’),
’conditions’ => array(’Article.status !=’ => ’pending’),
’recursive’ => 0
));
// ...
}
Note: In the above example, $allAuthors will contain every user in the users table. There will be no
condition applied to the find, since none were passed.
The results of a call to find(’list’) will be in the following form:
Array
(
//[id] => ’displayValue’,
[1] => ’displayValue1’,
[2] => ’displayValue2’,
[4] => ’displayValue4’,
[5] => ’displayValue5’,
228 Chapter 8. Models](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-234-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
[6] => ’displayValue6’,
[3] => ’displayValue3’,
)
When calling find(’list’), the fields passed are used to determine what should be used as the array
key and value, and optionally what to group the results by. By default, the primary key for the model is used
for the key, and the display field (which can be configured using the model attribute displayField) is used
for the value. Some further examples to clarify:
public function some_function() {
// ...
$justusernames = $this->Article->User->find(’list’, array(
’fields’ => array(’User.username’)
));
$usernameMap = $this->Article->User->find(’list’, array(
’fields’ => array(’User.username’, ’User.first_name’)
));
$usernameGroups = $this->Article->User->find(’list’, array(
’fields’ => array(’User.username’, ’User.first_name’, ’User.group’)
));
// ...
}
With the above code example, the resultant vars would look something like this:
$justusernames = Array
(
//[id] => ’username’,
[213] => ’AD7six’,
[25] => ’_psychic_’,
[1] => ’PHPNut’,
[2] => ’gwoo’,
[400] => ’jperras’,
)
$usernameMap = Array
(
//[username] => ’firstname’,
[’AD7six’] => ’Andy’,
[’_psychic_’] => ’John’,
[’PHPNut’] => ’Larry’,
[’gwoo’] => ’Gwoo’,
[’jperras’] => ’Joël’,
)
$usernameGroups = Array
(
[’User’] => Array
(
[’PHPNut’] => ’Larry’,
[’gwoo’] => ’Gwoo’,
)
More on models 229](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-235-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
[’Admin’] => Array
(
[’_psychic_’] => ’John’,
[’AD7six’] => ’Andy’,
[’jperras’] => ’Joël’,
)
)
find(‘threaded’)
find(’threaded’, $params) returns a nested array, and is appropriate if you want to use the
parent_id field of your model data to build nested results. Below are a couple of simple (controller
code) examples:
public function some_function() {
// ...
$allCategories = $this->Category->find(’threaded’);
$comments = $this->Comment->find(’threaded’, array(
’conditions’ => array(’article_id’ => 50)
));
// ...
}
Tip: A better way to deal with nested data is using the Tree behavior
In the above code example, $allCategories will contain a nested array representing the whole category
structure. The results of a call to find(’threaded’) will be of the following form:
Array
(
[0] => Array
(
[ModelName] => Array
(
[id] => 83
[parent_id] => null
[field1] => value1
[field2] => value2
[field3] => value3
)
[AssociatedModelName] => Array
(
[id] => 1
[field1] => value1
[field2] => value2
[field3] => value3
)
[children] => Array
230 Chapter 8. Models](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-236-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
(
[0] => Array
(
[ModelName] => Array
(
[id] => 42
[parent_id] => 83
[field1] => value1
[field2] => value2
[field3] => value3
)
[AssociatedModelName] => Array
(
[id] => 2
[field1] => value1
[field2] => value2
[field3] => value3
)
[children] => Array
(
)
)
...
)
)
)
The order in which results appear can be changed, as it is influenced by the order of processing. For example,
if ’order’ => ’name ASC’ is passed in the params to find(’threaded’), the results will appear
in name order. Any order can be used; there is no built-in requirement of this method for the top result to be
returned first.
Warning: If you specify fields, you need to always include the id and parent_id (or their current
aliases):
public function some_function() {
$categories = $this->Category->find(’threaded’, array(
’fields’ => array(’id’, ’name’, ’parent_id’)
));
}
Otherwise, the returned array will not be of the expected nested structure from above.
find(‘neighbors’)
find(’neighbors’, $params) will perform a find similar to ‘first’, but will return the row before
and after the one you request. Below is a simple (controller code) example:
More on models 231](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-237-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
public function some_function() {
$neighbors = $this->Article->find(
’neighbors’,
array(’field’ => ’id’, ’value’ => 3)
);
}
You can see in this example the two required elements of the $params array: field and value. Other
elements are still allowed as with any other find. (For example: If your model acts as containable, then you
can specify ‘contain’ in $params.) The result returned from a find(’neighbors’) call is in the form:
Array
(
[prev] => Array
(
[ModelName] => Array
(
[id] => 2
[field1] => value1
[field2] => value2
...
)
[AssociatedModelName] => Array
(
[id] => 151
[field1] => value1
[field2] => value2
...
)
)
[next] => Array
(
[ModelName] => Array
(
[id] => 4
[field1] => value1
[field2] => value2
...
)
[AssociatedModelName] => Array
(
[id] => 122
[field1] => value1
[field2] => value2
...
)
)
)
Note: Note how the result always contains only two root elements: prev and next. This function does not
honor a model’s default recursive var. The recursive setting must be passed in the parameters on each call.
232 Chapter 8. Models](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-238-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
Creating custom find types
The find method is flexible enough to accept your custom finders. This is done by declaring your own
types in a model variable and by implementing a special function in your model class.
A Model Find Type is a shortcut to find() options. For example, the following two finds are equivalent
$this->User->find(’first’);
$this->User->find(’all’, array(’limit’ => 1));
The following are core find types:
• first
• all
• count
• list
• threaded
• neighbors
But what about other types? Let’s say you want a finder for all published articles in your database. The first
change you need to do is add your type to the Model::$findMethods variable in the model
class Article extends AppModel {
public $findMethods = array(’available’ => true);
}
Basically this is just telling CakePHP to accept the value available as the first argument of the find
function. The next step is to implement the function _findAvailable. This is done by convention. If
you wanted to implement a finder called myFancySearch, then the method to implement would be named
_findMyFancySearch.
class Article extends AppModel {
public $findMethods = array(’available’ => true);
protected function _findAvailable($state, $query, $results = array()) {
if ($state === ’before’) {
$query[’conditions’][’Article.published’] = true;
return $query;
}
return $results;
}
}
This all comes together in the following example (controller code):
class ArticlesController extends AppController {
// Will find all published articles and order them by the created column
public function index() {
$articles = $this->Article->find(’available’, array(
’order’ => array(’created’ => ’desc’)
More on models 233](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-239-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
));
}
}
The special _find[Type] methods receive three arguments as shown above. The first one means the state
of the query execution, which could be either before or after. It is done this way because this function
is just a sort of callback function that has the ability to modify the query before it is done, or to modify the
results after they are fetched.
Typically the first thing to check in our custom find function is the state of the query. The before state
is the moment to modify the query, bind new associations, apply more behaviors, and interpret any special
key that is passed in the second argument of find. This state requires you to return the $query argument
(modified or not).
The after state is the perfect place to inspect the results, inject new data, process it in order to return it
in another format, or do whatever you like to the recently fetched data. This state requires you to return the
$results array (modified or not).
You can create as many custom finders as you like, and they are a great way of reusing code in your
application across models.
It is also possible to paginate via a custom find type as follows:
class ArticlesController extends AppController {
// Will paginate all published articles
public function index() {
$this->paginate = array(’available’);
$articles = $this->paginate();
$this->set(compact(’articles’));
}
}
Setting the $this->paginate property as above on the controller will result in the type of the find
becoming available, and will also allow you to continue to modify the find results.
To simply return the count of a custom find type, call count like you normally would, but pass in the find
type in an array for the second argument.
class ArticlesController extends AppController {
// Will find the count of all published articles (using the available find defined abov
public function index() {
$count = $this->Article->find(’count’, array(
’type’ => ’available’
));
}
}
If your pagination page count is becoming corrupt, it may be necessary to add the following code to your
AppModel, which should fix the pagination count:
234 Chapter 8. Models](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-240-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
class AppModel extends Model {
/**
* Removes ’fields’ key from count query on custom finds when it is an array,
* as it will completely break the Model::_findCount() call
*
* @param string $state Either "before" or "after"
* @param array $query
* @param array $results
* @return int The number of records found, or false
* @access protected
* @see Model::find()
*/
protected function _findCount($state, $query, $results = array()) {
if ($state === ’before’) {
if (isset($query[’type’]) &&
isset($this->findMethods[$query[’type’]])) {
$query = $this->{
’_find’ . ucfirst($query[’type’])
}(’before’, $query);
if (!empty($query[’fields’]) && is_array($query[’fields’])) {
if (!preg_match(’/^count/i’, current($query[’fields’]))) {
unset($query[’fields’]);
}
}
}
}
return parent::_findCount($state, $query, $results);
}
}
?>
Changed in version 2.2.
You no longer need to override _findCount for fixing incorrect count results. The ’before’ state of your
custom finder will now be called again with $query[’operation’] = ‘count’. The returned $query will be
used in _findCount() If necessary, you can distinguish by checking the ’operation’ key and return
a different $query:
protected function _findAvailable($state, $query, $results = array()) {
if ($state === ’before’) {
$query[’conditions’][’Article.published’] = true;
if (!empty($query[’operation’]) && $query[’operation’] === ’count’) {
return $query;
}
$query[’joins’] = array(
//array of required joins
);
return $query;
}
return $results;
}
More on models 235](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-241-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
Magic Find Types
These magic functions can be used as a shortcut to search your tables by a certain field. Just add the name
of the field (in CamelCase format) to the end of these functions, and supply the criteria for that field as the
first parameter.
findAllBy() functions will return results in a format like find(’all’), while findBy() return in the same
format as find(’first’)
findAllBy
findAllBy<fieldName>(string $value, array $fields, array $order, int
$limit, int $page, int $recursive)
findAllBy<x> Example Corresponding SQL Fragment
$this->Product->findAllByOrderStatus(’3’); Product.order_status = 3
$this->Recipe->findAllByType(’Cookie’); Recipe.type = ’Cookie’
$this->User->findAllByLastName(’Anderson’);User.last_name =
’Anderson’
$this->Cake->findAllById(7); Cake.id = 7
$this->User->findAllByEmailOrUsername(’jhon’,
’jhon’);
User.email = ’jhon’ OR
User.username = ’jhon’;
$this->User->findAllByUsernameAndPassword(’jhon’,
’123’);
User.username = ’jhon’ AND
User.password = ’123’;
$this->User->findAllByLastName(’psychic’,
array(), array(’User.user_name =>
’asc’));
User.last_name = ’psychic’
ORDER BY User.user_name
ASC
The returned result is an array formatted just as it would be from find(’all’).
findBy
findBy<fieldName>(string $value);
The findBy magic functions also accept some optional parameters:
findBy<fieldName>(string $value[, mixed $fields[, mixed $order]]);
findBy<x> Example Corresponding SQL Fragment
$this->Product->findByOrderStatus(’3’);Product.order_status = 3
$this->Recipe->findByType(’Cookie’); Recipe.type = ’Cookie’
$this->User->findByLastName(’Anderson’);User.last_name = ’Anderson’;
$this->User->findByEmailOrUsername(’jhon’,
’jhon’);
User.email = ’jhon’ OR
User.username = ’jhon’;
$this->User->findByUsernameAndPassword(’jhon’,
’123’);
User.username = ’jhon’ AND
User.password = ’123’;
$this->Cake->findById(7); Cake.id = 7
findBy() functions return results like find(’first’)
236 Chapter 8. Models](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-242-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
Model::query()
query(string $query)
SQL calls that you can’t or don’t want to make via other model methods can be made using the model’s
query() method (though this should only rarely be necessary).
If you use this method, be sure to properly escape all parameters using the value() method on the database
driver. Failing to escape parameters will create SQL injection vulnerabilities.
Note: query() does not honor $Model->cacheQueries as its functionality is inherently disjoint from
that of the calling model. To avoid caching calls to query, supply a second argument of false, ie:
query($query, $cachequeries = false)
query() uses the table name in the query as the array key for the returned data, rather than the model
name. For example:
$this->Picture->query("SELECT * FROM pictures LIMIT 2;");
might return:
Array
(
[0] => Array
(
[pictures] => Array
(
[id] => 1304
[user_id] => 759
)
)
[1] => Array
(
[pictures] => Array
(
[id] => 1305
[user_id] => 759
)
)
)
To use the model name as the array key, and get a result consistent with that returned by the Find methods,
the query can be rewritten:
$this->Picture->query("SELECT * FROM pictures AS Picture LIMIT 2;");
which returns:
Array
(
[0] => Array
(
More on models 237](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-243-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
[Picture] => Array
(
[id] => 1304
[user_id] => 759
)
)
[1] => Array
(
[Picture] => Array
(
[id] => 1305
[user_id] => 759
)
)
)
Note: This syntax and the corresponding array structure is valid for MySQL only. CakePHP does not
provide any data abstraction when running queries manually, so exact results will vary between databases.
Model::field()
field(string $name, array $conditions = null, string $order = null)
Returns the value of a single field, specified as $name, from the first record matched by $conditions as
ordered by $order. If no conditions are passed and the model id is set, it will return the field value for the
current model result. If no matching record is found, it returns false.
$this->Post->id = 22;
echo $this->Post->field(’name’); // echo the name for row id 22
// echo the name of the last created instance
echo $this->Post->field(
’name’,
array(’created <’ => date(’Y-m-d H:i:s’)),
’created DESC’
);
Model::read()
read($fields, $id)
read() is a method used to set the current model data (Model::$data)–such as during edits–but it can
also be used in other circumstances to retrieve a single record from the database.
$fields is used to pass a single field name, as a string, or an array of field names; if left empty, all fields
will be fetched.
$id specifies the ID of the record to be read. By default, the currently selected record, as specified by
Model::$id, is used. Passing a different value to $id will cause that record to be selected.
238 Chapter 8. Models](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-244-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
array(’OR’ => array(
array(’Post.title LIKE’ => ’%one%’),
array(’Post.title LIKE’ => ’%two%’)
))
CakePHP can also check for null fields. In this example, the query will return records where the post title is
not null:
array("NOT" => array(
"Post.title" => null
)
)
To handle BETWEEN queries, you can use the following:
array(’Post.read_count BETWEEN ? AND ?’ => array(1,10))
Note: CakePHP will quote the numeric values depending on the field type in your DB.
How about GROUP BY?:
array(
’fields’ => array(
’Product.type’,
’MIN(Product.price) as price’
),
’group’ => ’Product.type’
)
The data returned for this would be in the following format:
Array
(
[0] => Array
(
[Product] => Array
(
[type] => Clothing
)
[0] => Array
(
[price] => 32
)
)
[1] => Array
...
A quick example of doing a DISTINCT query. You can use other operators, such as MIN(), MAX(), etc., in
a similar fashion:
array(
’fields’ => array(’DISTINCT (User.name) AS my_column_name’),
’order’ = >array(’User.id DESC’)
)
More on models 241](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-247-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
You can create very complex conditions by nesting multiple condition arrays:
array(
’OR’ => array(
array(’Company.name’ => ’Future Holdings’),
array(’Company.city’ => ’CA’)
),
’AND’ => array(
array(
’OR’ => array(
array(’Company.status’ => ’active’),
’NOT’ => array(
array(’Company.status’ => array(’inactive’, ’suspended’))
)
)
)
)
)
which produces the following SQL:
SELECT ‘Company‘.‘id‘, ‘Company‘.‘name‘,
‘Company‘.‘description‘, ‘Company‘.‘location‘,
‘Company‘.‘created‘, ‘Company‘.‘status‘, ‘Company‘.‘size‘
FROM
‘companies‘ AS ‘Company‘
WHERE
((‘Company‘.‘name‘ = ’Future Holdings’)
OR
(‘Company‘.‘city‘ = ’CA’))
AND
((‘Company‘.‘status‘ = ’active’)
OR (NOT (‘Company‘.‘status‘ IN (’inactive’, ’suspended’))))
Sub-queries
For this example, imagine that we have a “users” table with “id”, “name” and “status”. The status can be
“A”, “B” or “C”. We want to retrieve all the users that have status other than “B” using a sub-query.
In order to achieve that, we are going to get the model data source and ask it to build the query as if we were
calling a find() method, but it will just return the SQL statement. After that we make an expression and add
it to the conditions array:
$conditionsSubQuery[’"User2"."status"’] = ’B’;
$db = $this->User->getDataSource();
$subQuery = $db->buildStatement(
array(
’fields’ => array(’"User2"."id"’),
242 Chapter 8. Models](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-248-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
’table’ => $db->fullTableName($this->User),
’alias’ => ’User2’,
’limit’ => null,
’offset’ => null,
’joins’ => array(),
’conditions’ => $conditionsSubQuery,
’order’ => null,
’group’ => null
),
$this->User
);
$subQuery = ’ "User"."id" NOT IN (’ . $subQuery . ’) ’;
$subQueryExpression = $db->expression($subQuery);
$conditions[] = $subQueryExpression;
$this->User->find(’all’, compact(’conditions’));
This should generate the following SQL:
SELECT
"User"."id" AS "User__id",
"User"."name" AS "User__name",
"User"."status" AS "User__status"
FROM
"users" AS "User"
WHERE
"User"."id" NOT IN (
SELECT
"User2"."id"
FROM
"users" AS "User2"
WHERE
"User2"."status" = ’B’
)
Also, if you need to pass just part of your query as raw SQL as above, datasource expressions with raw
SQL work for any part of the find query.
Prepared Statements
Should you need even more control over your queries, you can make use of prepared statements. This allows
you to talk directly to the database driver and send any custom query you like:
$db = $this->getDataSource();
$db->fetchAll(
’SELECT * from users where username = ? AND password = ?’,
array(’jhon’, ’12345’)
);
$db->fetchAll(
’SELECT * from users where username = :username AND password = :password’,
More on models 243](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-249-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
array(’username’ => ’jhon’,’password’ => ’12345’)
);
Saving Your Data
CakePHP makes saving model data a snap. Data ready to be saved should be passed to the model’s save()
method using the following basic format:
Array
(
[ModelName] => Array
(
[fieldname1] => ’value’
[fieldname2] => ’value’
)
)
Most of the time you won’t even need to worry about this format: CakePHP’s FormHelper, and model
find methods all package data in this format. If you’re using FormHelper, the data is also conveniently
available in $this->request->data for quick usage.
Here’s a quick example of a controller action that uses a CakePHP model to save data to a database table:
public function edit($id) {
// Has any form data been POSTed?
if ($this->request->is(’post’)) {
// If the form data can be validated and saved...
if ($this->Recipe->save($this->request->data)) {
// Set a session flash message and redirect.
$this->Session->setFlash(’Recipe Saved!’);
return $this->redirect(’/recipes’);
}
}
// If no form data, find the recipe to be edited
// and hand it to the view.
$this->set(’recipe’, $this->Recipe->findById($id));
}
When save is called, the data passed to it in the first parameter is validated using CakePHP’s validation
mechanism (see Data Validation chapter for more information). If for some reason your data isn’t saving,
be sure to check to see if some validation rules are being broken. You can debug this situation by outputting
Model::$validationErrors:
if ($this->Recipe->save($this->request->data)) {
// handle the success.
}
debug($this->Recipe->validationErrors);
There are a few other save-related methods in the model that you’ll find useful:
244 Chapter 8. Models](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-250-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
array(’Article’ => array(’title’ => ’title 2’)),
);
To save also associated data with $options[’deep’] = true (since 2.1), the two above examples
would look like:
$data = array(
array(’title’ => ’title 1’, ’Assoc’ => array(’field’ => ’value’)),
array(’title’ => ’title 2’),
);
$data = array(
array(
’Article’ => array(’title’ => ’title 1’),
’Assoc’ => array(’field’ => ’value’)
),
array(’Article’ => array(’title’ => ’title 2’)),
);
$Model->saveMany($data, array(’deep’ => true));
Keep in mind that if you want to update a record instead of creating a new one you just need to add the
primary key index to the data row:
$data = array(
array(
// This creates a new row
’Article’ => array(’title’ => ’New article’)),
array(
// This updates an existing row
’Article’ => array(’id’ => 2, ’title’ => ’title 2’)),
);
Model::saveAssociated(array $data = null, array $options = array())
Method used to save multiple model associations at once. The following options may be used:
• validate: Set to false to disable validation, true to validate each record before saving, ‘first’ to
validate all records before any are saved (default),
• atomic: If true (default), will attempt to save all records in a single transaction. Should be set to
false if database/table does not support transactions.
• fieldList: Equivalent to the $fieldList parameter in Model::save()
• deep: (since 2.1) If set to true, not only directly associated data is saved, but deeper nested associated
data as well. Defaults to false.
• counterCache (since 2.4) Boolean to control updating of counter caches (if any)
For saving a record along with its related record having a hasOne or belongsTo association, the data array
should be like this:
$data = array(
’User’ => array(’username’ => ’billy’),
More on models 249](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-255-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
’Profile’ => array(’sex’ => ’Male’, ’occupation’ => ’Programmer’),
);
For saving a record along with its related records having hasMany association, the data array should be like
this:
$data = array(
’Article’ => array(’title’ => ’My first article’),
’Comment’ => array(
array(’body’ => ’Comment 1’, ’user_id’ => 1),
array(’body’ => ’Comment 2’, ’user_id’ => 12),
array(’body’ => ’Comment 3’, ’user_id’ => 40),
),
);
And for saving a record along with its related records having hasMany with more than two levels deep
associations, the data array should be as follow:
$data = array(
’User’ => array(’email’ => ’john-doe@cakephp.org’),
’Cart’ => array(
array(
’payment_status_id’ => 2,
’total_cost’ => 250,
’CartItem’ => array(
array(
’cart_product_id’ => 3,
’quantity’ => 1,
’cost’ => 100,
),
array(
’cart_product_id’ => 5,
’quantity’ => 1,
’cost’ => 150,
)
)
)
)
);
Note: If successful, the foreign key of the main model will be stored in the related models’ id field, i.e.
$this->RelatedModel->id.
Warning: Be careful when checking saveAssociated calls with atomic option set to false. It returns an
array instead of boolean.
Changed in version 2.1: You can now save deeper associated data as well with setting
$options[’deep’] = true;
For saving a record along with its related records having hasMany association and deeper associated Com-
ment belongsTo User data as well, the data array should be like this:
250 Chapter 8. Models](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-256-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
public function add() {
if (!empty($this->request->data)) {
// We can save the User data:
// it should be in $this->request->data[’User’]
$user = $this->User->save($this->request->data);
// If the user was saved, Now we add this information to the data
// and save the Profile.
if (!empty($user)) {
// The ID of the newly created user has been set
// as $this->User->id.
$this->request->data[’Profile’][’user_id’] = $this->User->id;
// Because our User hasOne Profile, we can access
// the Profile model through the User model:
$this->User->Profile->save($this->request->data);
}
}
}
As a rule, when working with hasOne, hasMany, and belongsTo associations, it’s all about keying. The
basic idea is to get the key from one model and place it in the foreign key field on the other. Sometimes
this might involve using the $id attribute of the model class after a save(), but other times it might just
involve gathering the ID from a hidden input on a form that’s just been POSTed to a controller action.
To supplement the basic approach used above, CakePHP also offers a very handy method
saveAssociated(), which allows you to validate and save multiple models in one shot. In addition,
saveAssociated() provides transactional support to ensure data integrity in your database (i.e. if one
model fails to save, the other models will not be saved either).
Note: For transactions to work correctly in MySQL your tables must use InnoDB engine. Remember that
MyISAM tables do not support transactions.
Let’s see how we can use saveAssociated() to save Company and Account models at the same time.
First, you need to build your form for both Company and Account models (we’ll assume that Company
hasMany Account):
echo $this->Form->create(’Company’, array(’action’ => ’add’));
echo $this->Form->input(’Company.name’, array(’label’ => ’Company name’));
echo $this->Form->input(’Company.description’);
echo $this->Form->input(’Company.location’);
echo $this->Form->input(’Account.0.name’, array(’label’ => ’Account name’));
echo $this->Form->input(’Account.0.username’);
echo $this->Form->input(’Account.0.email’);
echo $this->Form->end(’Add’);
Take a look at the way we named the form fields for the Account model. If Company is our main model,
252 Chapter 8. Models](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-258-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
saveAssociated() will expect the related model’s (Account) data to arrive in a specific format. And
having Account.0.fieldName is exactly what we need.
Note: The above field naming is required for a hasMany association. If the association between the models
is hasOne, you have to use ModelName.fieldName notation for the associated model.
Now, in our CompaniesController we can create an add() action:
public function add() {
if (!empty($this->request->data)) {
// Use the following to avoid validation errors:
unset($this->Company->Account->validate[’company_id’]);
$this->Company->saveAssociated($this->request->data);
}
}
That’s all there is to it. Now our Company and Account models will be validated and saved all at the same
time. By default saveAssociated will validate all values passed and then try to perform a save for each.
Saving hasMany through data
Let’s see how data stored in a join table for two models is saved. As shown in the hasMany through (The
Join Model) section, the join table is associated to each model using a hasMany type of relationship. Our
example involves the Head of Cake School asking us to write an application that allows him to log a student’s
attendance on a course with days attended and grade. Take a look at the following code.:
// Controller/CourseMembershipController.php
class CourseMembershipsController extends AppController {
public $uses = array(’CourseMembership’);
public function index() {
$this->set(
’courseMembershipsList’,
$this->CourseMembership->find(’all’)
);
}
public function add() {
if ($this->request->is(’post’)) {
if ($this->CourseMembership->saveAssociated($this->request->data)) {
return $this->redirect(array(’action’ => ’index’));
}
}
}
}
// View/CourseMemberships/add.ctp
<?php echo $this->Form->create(’CourseMembership’); ?>
<?php echo $this->Form->input(’Student.first_name’); ?>
<?php echo $this->Form->input(’Student.last_name’); ?>
More on models 253](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-259-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
<?php echo $this->Form->input(’Course.name’); ?>
<?php echo $this->Form->input(’CourseMembership.days_attended’); ?>
<?php echo $this->Form->input(’CourseMembership.grade’); ?>
<button type="submit">Save</button>
<?php echo $this->Form->end(); ?>
The data array will look like this when submitted.:
Array
(
[Student] => Array
(
[first_name] => Joe
[last_name] => Bloggs
)
[Course] => Array
(
[name] => Cake
)
[CourseMembership] => Array
(
[days_attended] => 5
[grade] => A
)
)
CakePHP will happily be able to save the lot together and assign the foreign keys of the Student and Course
into CourseMembership with a saveAssociated call with this data structure. If we run the index action of
our CourseMembershipsController the data structure received now from a find(‘all’) is:
Array
(
[0] => Array
(
[CourseMembership] => Array
(
[id] => 1
[student_id] => 1
[course_id] => 1
[days_attended] => 5
[grade] => A
)
[Student] => Array
(
[id] => 1
[first_name] => Joe
[last_name] => Bloggs
)
[Course] => Array
254 Chapter 8. Models](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-260-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
(
[id] => 1
[name] => Cake
)
)
)
There are of course many ways to work with a join model. The version above assumes you want to save
everything at-once. There will be cases where you want to create the Student and Course independently and
at a later point associate the two together with a CourseMembership. So you might have a form that allows
selection of existing students and courses from pick lists or ID entry and then the two meta-fields for the
CourseMembership, e.g.:
// View/CourseMemberships/add.ctp
<?php echo $this->Form->create(’CourseMembership’); ?>
<?php
echo $this->Form->input(
’Student.id’,
array(
’type’ => ’text’,
’label’ => ’Student ID’,
’default’ => 1
)
);
?>
<?php
echo $this->Form->input(
’Course.id’,
array(
’type’ => ’text’,
’label’ => ’Course ID’,
’default’ => 1
)
);
?>
<?php echo $this->Form->input(’CourseMembership.days_attended’); ?>
<?php echo $this->Form->input(’CourseMembership.grade’); ?>
<button type="submit">Save</button>
<?php echo $this->Form->end(); ?>
And the resultant POST:
Array
(
[Student] => Array
(
[id] => 1
)
[Course] => Array
(
[id] => 1
More on models 255](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-261-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
)
[CourseMembership] => Array
(
[days_attended] => 10
[grade] => 5
)
)
Again CakePHP is good to us and pulls the Student id and Course id into the CourseMembership with the
saveAssociated.
Saving Related Model Data (HABTM)
Saving models that are associated by hasOne, belongsTo, and hasMany is pretty simple: you just populate
the foreign key field with the ID of the associated model. Once that’s done, you just call the save()
method on the model, and everything gets linked up correctly. An example of the required format for the
data array passed to save() for the Tag model is shown below:
Array
(
[Recipe] => Array
(
[id] => 42
)
[Tag] => Array
(
[name] => Italian
)
)
You can also use this format to save several records and their HABTM associations with saveAll(),
using an array like the following:
Array
(
[0] => Array
(
[Recipe] => Array
(
[id] => 42
)
[Tag] => Array
(
[name] => Italian
)
)
[1] => Array
(
[Recipe] => Array
(
[id] => 43
256 Chapter 8. Models](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-262-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
)
[Tag] => Array
(
[name] => Pasta
)
)
[2] => Array
(
[Recipe] => Array
(
[id] => 51
)
[Tag] => Array
(
[name] => Mexican
)
)
[3] => Array
(
[Recipe] => Array
(
[id] => 17
)
[Tag] => Array
(
[name] => American (new)
)
)
)
Passing the above array to saveAll() will create the contained tags, each associated with their respective
recipes.
Another example that is helpful is when you need to save many Tags to a Post. You need to pass the
associated HABTM data in the following HABTM array format. Note you only need to pass in the id’s of
the associated HABTM model however it needs to be nested again:
Array
(
[0] => Array
(
[Post] => Array
(
[title] => ’Saving HABTM arrays’
)
[Tag] => Array
(
[Tag] => Array(1, 2, 5, 9)
)
)
[1] => Array
(
[Post] => Array
More on models 257](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-263-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
(
[title] => ’Dr Who’s Name is Revealed’
)
[Tag] => Array
(
[Tag] => Array(7, 9, 15, 19)
)
)
[2] => Array
(
[Post] => Array
(
[title] => ’I Came, I Saw and I Conquered’
)
[Tag] => Array
(
[Tag] => Array(11, 12, 15, 19)
)
)
[3] => Array
(
[Post] => Array
(
[title] => ’Simplicity is the Ultimate Sophistication ’
)
[Tag] => Array
(
[Tag] => Array(12, 22, 25, 29)
)
)
)
Passing the above array to saveAll($data, array(’deep’ => true)) will populate the
posts_tags join table with the Tag to Post associations.
As an example, we’ll build a form that creates a new tag and generates the proper data array to associate it
on the fly with some recipe.
The simplest form might look something like this (we’ll assume that $recipe_id is already set to some-
thing):
<?php echo $this->Form->create(’Tag’); ?>
<?php echo $this->Form->input(
’Recipe.id’,
array(’type’ => ’hidden’, ’value’ => $recipe_id)
); ?>
<?php echo $this->Form->input(’Tag.name’); ?>
<?php echo $this->Form->end(’Add Tag’); ?>
In this example, you can see the Recipe.id hidden field whose value is set to the ID of the recipe we
want to link the tag to.
When the save() method is invoked within the controller, it’ll automatically save the HABTM data to the
database:
258 Chapter 8. Models](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-264-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
public function add() {
// Save the association
if ($this->Tag->save($this->request->data)) {
// do something on success
}
}
With the preceding code, our new Tag is created and associated with a Recipe, whose ID was set in
$this->request->data[’Recipe’][’id’].
Other ways we might want to present our associated data can include a select drop down list. The data can
be pulled from the model using the find(’list’) method and assigned to a view variable of the model
name. An input with the same name will automatically pull in this data into a <select>:
// in the controller:
$this->set(’tags’, $this->Recipe->Tag->find(’list’));
// in the view:
$this->Form->input(’tags’);
A more likely scenario with a HABTM relationship would include a <select> set to allow multiple
selections. For example, a Recipe can have multiple Tags assigned to it. In this case, the data is pulled out
of the model the same way, but the form input is declared slightly different. The tag name is defined using
the ModelName convention:
// in the controller:
$this->set(’tags’, $this->Recipe->Tag->find(’list’));
// in the view:
$this->Form->input(’Tag’);
Using the preceding code, a multiple select drop down is created, allowing for multiple choices to automat-
ically be saved to the existing Recipe being added or saved to the database.
Self HABTM Normally HABTM is used to bring 2 models together but it can also be used with only 1
model, though it requires some extra attention.
The key is in the model setup the className. Simply adding a Project HABTM Project relation
causes issues saving data. By setting the className to the models name and use the alias as key we avoid
those issues.:
class Project extends AppModel {
public $hasAndBelongsToMany = array(
’RelatedProject’ => array(
’className’ => ’Project’,
’foreignKey’ => ’projects_a_id’,
’associationForeignKey’ => ’projects_b_id’,
),
);
}
Creating form elements and saving the data works the same as before but you use the alias instead. This:
More on models 259](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-265-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
will inspect your tables to determine the data type of each field and uses this information to automate various
features such as outputting form fields in the view. Field names are by convention lowercase and separated
by underscores.
Using created and modified
By defining a created and/or modified field in your database table as datetime fields (default null),
CakePHP will recognize those fields and populate them automatically whenever a record is created or saved
to the database (unless the data being saved already contains a value for these fields).
The created and modified fields will be set to the current date and time when the record is initially
added. The modified field will be updated with the current date and time whenever the existing record is
saved.
If you have created or modified data in your $this->data (e.g. from a Model::read or Model::set)
before a Model::save() then the values will be taken from $this->data and not automagically updated. If you
don’t want that you can use unset($this->data[’Model’][’modified’]), etc. Alternatively
you can override the Model::save() to always do it for you:
class AppModel extends Model {
public function save($data = null, $validate = true, $fieldList = array()) {
// Clear modified field value before each save
$this->set($data);
if (isset($this->data[$this->alias][’modified’])) {
unset($this->data[$this->alias][’modified’]);
}
return parent::save($this->data, $validate, $fieldList);
}
}
Deleting Data
CakePHP’s Model class offers a few ways to delete records from your database.
delete
delete(integer $id = null, boolean $cascade = true);
Deletes the record identified by $id. By default, also deletes records dependent on the record specified to be
deleted.
For example, when deleting a User record that is tied to many Recipe records (User ‘hasMany’ or ‘hasAnd-
BelongsToMany’ Recipes):
• if $cascade is set to true, the related Recipe records are also deleted if the model’s dependent-value is
set to true.
• if $cascade is set to false, the Recipe records will remain after the User has been deleted.
More on models 261](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-267-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
’message’ => ’Minimum length of 8 characters’
)
)
);
When specifying validation rules in this array form it’s possible to avoid providing the message key.
Consider this example:
public $validate = array(
’login’ => array(
’Only alphabets and numbers allowed’ => array(
’rule’ => ’alphaNumeric’,
),
)
);
If the alphaNumeric rules fails the array key for this rule ‘Only alphabets and numbers allowed’ will be
returned as error message since the message key is not set.
Custom Validation Rules
If you haven’t found what you need thus far, you can always create your own validation rules. There are two
ways you can do this: by defining custom regular expressions, or by creating custom validation methods.
Custom Regular Expression Validation
If the validation technique you need to use can be completed by using regular expression matching, you can
define a custom expression as a field validation rule:
public $validate = array(
’login’ => array(
’rule’ => ’/^[a-z0-9]{3,}$/i’,
’message’ => ’Only letters and integers, min 3 characters’
)
);
The example above checks if the login contains only letters and integers, with a minimum of three characters.
The regular expression in the rule must be delimited by slashes. The optional trailing ‘i’ after the last slash
means the reg-exp is case insensitive.
Adding your own Validation Methods
Sometimes checking data with regular expression patterns is not enough. For example, if you want to ensure
that a promotional code can only be used 25 times, you need to add your own validation function, as shown
below:
268 Chapter 8. Models](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-274-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
class User extends AppModel {
public $validate = array(
’promotion_code’ => array(
’rule’ => array(’limitDuplicates’, 25),
’message’ => ’This code has been used too many times.’
)
);
public function limitDuplicates($check, $limit) {
// $check will have value: array(’promotion_code’ => ’some-value’)
// $limit will have value: 25
$existingPromoCount = $this->find(’count’, array(
’conditions’ => $check,
’recursive’ => -1
));
return $existingPromoCount < $limit;
}
}
The current field to be validated is passed into the function as first parameter as an associated array with
field name as key and posted data as value.
If you want to pass extra parameters to your validation function, add elements onto the ‘rule’ array, and
handle them as extra params (after the main $check param) in your function.
Your validation function can be in the model (as in the example above), or in a behavior that the model
implements. This includes mapped methods.
Model/behavior methods are checked first, before looking for a method on the Validation class. This
means that you can override existing validation methods (such as alphaNumeric()) at an application
level (by adding the method to AppModel), or at model level.
When writing a validation rule which can be used by multiple fields, take care to extract the field value from
the $check array. The $check array is passed with the form field name as its key and the field value as its
value. The full record being validated is stored in $this->data member variable:
class Post extends AppModel {
public $validate = array(
’slug’ => array(
’rule’ => ’alphaNumericDashUnderscore’,
’message’ => ’Slug can only be letters,’ .
’ numbers, dash and underscore’
)
);
public function alphaNumericDashUnderscore($check) {
// $data array is passed using the form field name as the key
// have to extract the value to make the function generic
$value = array_values($check);
$value = $value[0];
return preg_match(’|^[0-9a-zA-Z_-]*$|’, $value);
More on models 269](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-275-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
$this->validator()->add(’password’, array(
’required’ => array(
’rule’ => ’notEmpty’,
’required’ => ’create’
),
’size’ => array(
’rule’ => array(’between’, 8, 20),
’message’ => ’Password should be at least 8 chars long’
)
));
Alternatively, you can use the validator object to set rules directly to fields using the array interface:
$validator = $this->validator();
$validator[’username’] = array(
’unique’ => array(
’rule’ => ’isUnique’,
’required’ => ’create’
),
’alphanumeric’ => array(
’rule’ => ’alphanumeric’
)
);
Modifying current validation rules
New in version 2.2.
Modifying current validation rules is also possible using the validator object, there are several ways in which
you can alter current rules, append methods to a field or completely remove a rule from a field rule set:
// In a model class
$this->validator()->getField(’password’)->setRule(’required’, array(
’rule’ => ’required’,
’required’ => true
));
You can also completely replace all the rules for a field using a similar method:
// In a model class
$this->validator()->getField(’password’)->setRules(array(
’required’ => array(...),
’otherRule’ => array(...)
));
If you wish to just modify a single property in a rule you can set properties directly into the
CakeValidationRule object:
// In a model class
$this->validator()->getField(’password’)
->getRule(’required’)->message = ’This field cannot be left blank’;
More on models 271](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-277-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
Properties in any CakeValidationRule get their name from the array keys one is allowed to use when
defining a validation rule’s properties, such as the array keys ‘message’ and ‘allowEmpty’ for example.
As with adding new rule to the set, it is also possible to modify existing rules using the array interface:
$validator = $this->validator();
$validator[’username’][’unique’] = array(
’rule’ => ’isUnique’,
’required’ => ’create’
);
$validator[’username’][’unique’]->last = true;
$validator[’username’][’unique’]->message = ’Name already taken’;
Removing rules from the set
New in version 2.2.
It is possible to both completely remove all rules for a field and to delete a single rule in a field’s rule set:
// Completely remove all rules for a field
$this->validator()->remove(’username’);
// Remove ’required’ rule from password
$this->validator()->remove(’password’, ’required’);
Optionally, you can use the array interface to delete rules from the set:
$validator = $this->validator();
// Completely remove all rules for a field
unset($validator[’username’]);
// Remove ’required’ rule from password
unset($validator[’password’][’required’]);
Core Validation Rules
class Validation
The Validation class in CakePHP contains many validation rules that can make model data validation much
easier. This class contains many oft-used validation techniques you won’t need to write on your own. Below,
you’ll find a complete list of all the rules, along with usage examples.
static Validation::alphaNumeric(mixed $check)
The data for the field must only contain letters and numbers.:
public $validate = array(
’login’ => array(
’rule’ => ’alphaNumeric’,
’message’ => ’Usernames must only contain letters and numbers.’
)
);
272 Chapter 8. Models](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-278-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
)
);
static Validation::range(string $check, integer $lower = null, integer $upper = null)
This rule ensures that the value is in a given range. If no range is supplied, the rule will check to
ensure the value is a legal finite on the current platform.
public $validate = array(
’number’ => array(
’rule’ => array(’range’, -1, 11),
’message’ => ’Please enter a number between -1 and 11’
)
);
The above example will accept any value which is larger than -1 (e.g., -0.99) and less than 11 (e.g.,
10.99).
Note: The range lower/upper are not inclusive
static Validation::ssn(mixed $check, string $regex = null, string $country = null)
Ssn validates social security numbers from the U.S. (us), Denmark (dk), and the Netherlands (nl). For
other social security number formats, you may provide a regular expression.
public $validate = array(
’ssn’ => array(
’rule’ => array(’ssn’, null, ’us’)
)
);
static Validation::time(string $check)
Time validation, determines if the string passed is a valid time. Validates time as 24hr (HH:MM) or
am/pm ([H]H:MM[a|p]m) Does not allow/validate seconds.
static Validation::uploadError(mixed $check)
New in version 2.2.
This rule checks if a file upload has an error.
public $validate = array(
’image’ => array(
’rule’ => ’uploadError’,
’message’ => ’Something went wrong with the upload.’
),
);
static Validation::url(string $check, boolean $strict = false)
This rule checks for valid URL formats. Supports http(s), ftp(s), file, news, and gopher protocols:
public $validate = array(
’website’ => array(
’rule’ => ’url’
)
);
More on models 281](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-287-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
),
);
The return value for this callback should be the (possibly modified) results for the find operation that trig-
gered this callback.
The $primary parameter indicates whether or not the current model was the model that the query origi-
nated on or whether or not this model was queried as an association. If a model is queried as an association
the format of $results can differ; instead of the result you would normally get from a find operation, you
may get this:
$results = array(
’field_1’ => ’value1’,
’field_2’ => ’value2’
);
Warning: Code expecting $primary to be true will probably get a “Cannot use string offset as an
array” fatal error from PHP if a recursive find is used.
Below is an example of how afterfind can be used for date formatting:
public function afterFind($results, $primary = false) {
foreach ($results as $key => $val) {
if (isset($val[’Event’][’begindate’])) {
$results[$key][’Event’][’begindate’] = $this->dateFormatAfterFind(
$val[’Event’][’begindate’]
);
}
}
return $results;
}
public function dateFormatAfterFind($dateString) {
return date(’d-m-Y’, strtotime($dateString));
}
beforeValidate
beforeValidate(array $options = array())
Use this callback to modify model data before it is validated, or to modify validation rules if required. This
function must also return true, otherwise the current save() execution will abort.
afterValidate
afterValidate()
Called after data has been checked for errors. Use this callback to perform any data cleanup or preparation
if needed.
More on models 285](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-291-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
beforeSave
beforeSave(array $options = array())
Place any pre-save logic in this function. This function executes immediately after model data has been
successfully validated, but just before the data is saved. This function should also return true if you want the
save operation to continue.
This callback is especially handy for any data-massaging logic that needs to happen before your data is
stored. If your storage engine needs dates in a specific format, access it at $this->data and modify it.
Below is an example of how beforeSave can be used for date conversion. The code in the example is used
for an application with a begindate formatted like YYYY-MM-DD in the database and is displayed like
DD-MM-YYYY in the application. Of course this can be changed very easily. Use the code below in the
appropriate model.
public function beforeSave($options = array()) {
if (!empty($this->data[’Event’][’begindate’]) &&
!empty($this->data[’Event’][’enddate’])
) {
$this->data[’Event’][’begindate’] = $this->dateFormatBeforeSave(
$this->data[’Event’][’begindate’]
);
$this->data[’Event’][’enddate’] = $this->dateFormatBeforeSave(
$this->data[’Event’][’enddate’]
);
}
return true;
}
public function dateFormatBeforeSave($dateString) {
return date(’Y-m-d’, strtotime($dateString));
}
Tip: Be sure that beforeSave() returns true, or your save is going to fail.
afterSave
afterSave(boolean $created, array $options = array())
If you have logic you need to be executed just after every save operation, place it in this callback method.
The saved data will be available in $this->data.
The value of $created will be true if a new record was created (rather than an update).
The $options array is the same one passed to Model::save().
beforeDelete
beforeDelete(boolean $cascade = true)
286 Chapter 8. Models](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-292-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
Place any pre-deletion logic in this function. This function should return true if you want the deletion to
continue, and false if you want to abort.
The value of $cascade will be true if records that depend on this record will also be deleted.
Tip: Be sure that beforeDelete() returns true, or your delete is going to fail.
// using app/Model/ProductCategory.php
// In the following example, do not let a product category be deleted if it
// still contains products.
// A call of $this->Product->delete($id) from ProductsController.php has set
// $this->id .
// Assuming ’ProductCategory hasMany Product’, we can access $this->Product
// in the model.
public function beforeDelete($cascade = true) {
$count = $this->Product->find("count", array(
"conditions" => array("product_category_id" => $this->id)
));
if ($count == 0) {
return true;
} else {
return false;
}
}
afterDelete
afterDelete()
Place any logic that you want to be executed after every deletion in this callback method.
// perhaps after deleting a record from the database, you also want to delete
// an associated file
public function afterDelete() {
$file = new File($this->data[’SomeModel’][’file_path’]);
$file->delete();
}
onError
onError()
Called if any problems occur.
Behaviors
Model behaviors are a way to organize some of the functionality defined in CakePHP models. They allow
us to separate and reuse logic that creates a type of behavior, and they do this without requiring inheritance.
For example creating tree structures. By providing a simple yet powerful way to enhance models, behaviors
More on models 287](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-293-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
$this->Post->Behaviors->load(’Acl’, array(’type’ => ’controlled’));
Changed in version 2.1: You can now safely attach AclBehavior to AppModel. Aco, Aro and AclNode now
extend Model instead of AppModel, which would cause an infinite loop. If your application depends on
having those models to extend AppModel for some reason, then copy AclNode to your application and have
it extend AppModel again.
Using the AclBehavior
Most of the AclBehavior works transparently on your Model’s afterSave(). However, using it requires that
your Model has a parentNode() method defined. This is used by the AclBehavior to determine parent->child
relationships. A model’s parentNode() method must return null or return a parent Model reference:
public function parentNode() {
return null;
}
If you want to set an ACO or ARO node as the parent for your Model, parentNode() must return the alias of
the ACO or ARO node:
public function parentNode() {
return ’root_node’;
}
A more complete example. Using an example User Model, where User belongsTo Group:
public function parentNode() {
if (!$this->id && empty($this->data)) {
return null;
}
$data = $this->data;
if (empty($this->data)) {
$data = $this->read();
}
if (!$data[’User’][’group_id’]) {
return null;
} else {
return array(’Group’ => array(’id’ => $data[’User’][’group_id’]));
}
}
In the above example the return is an array that looks similar to the results of a model find. It is important
to have the id value set or the parentNode relation will fail. The AclBehavior uses this data to construct its
tree structure.
node()
The AclBehavior also allows you to retrieve the Acl node associated with a model record. After setting
$model->id. You can use $model->node() to retrieve the associated Acl node.
More on models 289](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-295-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
The amount of data fetched in a normal find() call is rather extensive:
debug($this->Post->find(’all’));
[0] => Array
(
[Post] => Array
(
[id] => 1
[title] => First article
[content] => aaa
[created] => 2008-05-18 00:00:00
)
[Comment] => Array
(
[0] => Array
(
[id] => 1
[post_id] => 1
[author] => Daniel
[email] => dan@example.com
[website] => http://example.com
[comment] => First comment
[created] => 2008-05-18 00:00:00
)
[1] => Array
(
[id] => 2
[post_id] => 1
[author] => Sam
[email] => sam@example.net
[website] => http://example.net
[comment] => Second comment
[created] => 2008-05-18 00:00:00
)
)
[Tag] => Array
(
[0] => Array
(
[id] => 1
[name] => Awesome
)
[1] => Array
(
[id] => 2
[name] => Baking
)
)
)
[1] => Array
(
[Post] => Array
(...
More on models 291](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-297-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
For some interfaces in your application, you may not need that much information from the Post model. One
thing the ContainableBehavior does is help you cut down on what find() returns.
For example, to get only the post-related information, you can do the following:
$this->Post->contain();
$this->Post->find(’all’);
You can also invoke Containable’s magic from inside the find() call:
$this->Post->find(’all’, array(’contain’ => false));
Having done that, you end up with something a lot more concise:
[0] => Array
(
[Post] => Array
(
[id] => 1
[title] => First article
[content] => aaa
[created] => 2008-05-18 00:00:00
)
)
[1] => Array
(
[Post] => Array
(
[id] => 2
[title] => Second article
[content] => bbb
[created] => 2008-05-19 00:00:00
)
)
This sort of help isn’t new: in fact, you can do that without the ContainableBehavior doing something
like this:
$this->Post->recursive = -1;
$this->Post->find(’all’);
Containable really shines when you have complex associations, and you want to pare down things that sit
at the same level. The model’s $recursive property is helpful if you want to hack off an entire level of
recursion, but not when you want to pick and choose what to keep at each level. Let’s see how it works by
using the contain() method.
The contain method’s first argument accepts the name, or an array of names, of the models to keep in the
find operation. If we wanted to fetch all posts and their related tags (without any comment information),
we’d try something like this:
$this->Post->contain(’Tag’);
$this->Post->find(’all’);
Again, we can use the contain key inside a find() call:
292 Chapter 8. Models](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-298-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
$this->Post->find(’all’, array(’contain’ => ’Tag’));
Without Containable, you’d end up needing to use the unbindModel() method of the model, multiple
times if you’re paring off multiple models. Containable creates a cleaner way to accomplish this same task.
Containing deeper associations
Containable also goes a step deeper: you can filter the data of the associated models. If you look at the
results of the original find() call, notice the author field in the Comment model. If you are interested in
the posts and the names of the comment authors — and nothing else — you could do something like the
following:
$this->Post->contain(’Comment.author’);
$this->Post->find(’all’);
// or..
$this->Post->find(’all’, array(’contain’ => ’Comment.author’));
Here, we’ve told Containable to give us our post information, and just the author field of the associated
Comment model. The output of the find call might look something like this:
[0] => Array
(
[Post] => Array
(
[id] => 1
[title] => First article
[content] => aaa
[created] => 2008-05-18 00:00:00
)
[Comment] => Array
(
[0] => Array
(
[author] => Daniel
[post_id] => 1
)
[1] => Array
(
[author] => Sam
[post_id] => 1
)
)
)
[1] => Array
(...
As you can see, the Comment arrays only contain the author field (plus the post_id which is needed by
CakePHP to map the results).
You can also filter the associated Comment data by specifying a condition:
More on models 293](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-299-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
$this->Post->contain(’Comment.author = "Daniel"’);
$this->Post->find(’all’);
//or...
$this->Post->find(’all’, array(’contain’ => ’Comment.author = "Daniel"’));
This gives us a result that gives us posts with comments authored by Daniel:
[0] => Array
(
[Post] => Array
(
[id] => 1
[title] => First article
[content] => aaa
[created] => 2008-05-18 00:00:00
)
[Comment] => Array
(
[0] => Array
(
[id] => 1
[post_id] => 1
[author] => Daniel
[email] => dan@example.com
[website] => http://example.com
[comment] => First comment
[created] => 2008-05-18 00:00:00
)
)
)
There is an important caveat to using Containable when filtering on a deeper association. In the previous
example, assume you had 3 posts in your database and Daniel had commented on 2 of those posts. The
operation $this->Post->find(‘all’, array(‘contain’ => ‘Comment.author = “Daniel”’)); would return ALL
3 posts, not just the 2 posts that Daniel had commented on. It won’t return all comments however, just
comments by Daniel.:
[0] => Array
(
[Post] => Array
(
[id] => 1
[title] => First article
[content] => aaa
[created] => 2008-05-18 00:00:00
)
[Comment] => Array
(
[0] => Array
(
[id] => 1
294 Chapter 8. Models](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-300-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
[post_id] => 1
[author] => Daniel
[email] => dan@example.com
[website] => http://example.com
[comment] => First comment
[created] => 2008-05-18 00:00:00
)
)
)
[1] => Array
(
[Post] => Array
(
[id] => 2
[title] => Second article
[content] => bbb
[created] => 2008-05-18 00:00:00
)
[Comment] => Array
(
)
)
[2] => Array
(
[Post] => Array
(
[id] => 3
[title] => Third article
[content] => ccc
[created] => 2008-05-18 00:00:00
)
[Comment] => Array
(
[0] => Array
(
[id] => 22
[post_id] => 3
[author] => Daniel
[email] => dan@example.com
[website] => http://example.com
[comment] => Another comment
[created] => 2008-05-18 00:00:00
)
)
)
If you want to filter the posts by the comments, so that posts without a comment by Daniel won’t be returned,
the easiest way is to find all the comments by Daniel and contain the Posts.:
$this->Comment->find(’all’, array(
’conditions’ => ’Comment.author = "Daniel"’,
’contain’ => ’Post’
));
More on models 295](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-301-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
ContainableBehavior options
The ContainableBehavior has a number of options that can be set when the Behavior is attached to a
model. The settings allow you to fine tune the behavior of Containable and work with other behaviors more
easily.
• recursive (boolean, optional) set to true to allow containable to automatically determine the recur-
siveness level needed to fetch specified models, and set the model recursiveness to this level. setting
it to false disables this feature. The default value is true.
• notices (boolean, optional) issues E_NOTICES for bindings referenced in a containable call that are
not valid. The default value is true.
• autoFields: (boolean, optional) auto-add needed fields to fetch requested bindings. The default value
is true.
• order: (string, optional) the order of how the contained elements are sorted.
From the previous example, this is an example of how to force the posts to be ordered by the date when they
were last updated:
$this->User->find(’all’, array(
’contain’ => array(
’Profile’,
’Post’ => array(
’order’ => ’Post.updated DESC’
)
)
));
You can change ContainableBehavior settings at run time by reattaching the behavior as seen in Behaviors
(Using Behaviors).
ContainableBehavior can sometimes cause issues with other behaviors or queries that use aggregate func-
tions and/or GROUP BY statements. If you get invalid SQL errors due to mixing of aggregate and non-
aggregate fields, try disabling the autoFields setting.:
$this->Post->Behaviors->load(’Containable’, array(’autoFields’ => false));
Using Containable with pagination By including the ‘contain’ parameter in the $paginate property
it will apply to both the find(‘count’) and the find(‘all’) done on the model.
See the section Using Containable for further details.
Here’s an example of how to contain associations when paginating:
$this->paginate[’User’] = array(
’contain’ => array(’Profile’, ’Account’),
’order’ => ’User.username’
);
$users = $this->paginate(’User’);
More on models 297](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-303-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
Note: If you contained the associations through the model instead, it will not honor Containable’s recursive
option. So if you set recursive to -1 for example for the model, it won’t work:
$this->User->recursive = -1;
$this->User->contain(array(’Profile’, ’Account’));
$users = $this->paginate(’User’);
Translate
class TranslateBehavior
TranslateBehavior is actually quite easy to setup and works out of the box with very little configuration. In
this section, you will learn how to add and setup the behavior to use in any model.
If you are using TranslateBehavior in alongside containable issue, be sure to set the ‘fields’ key for your
queries. Otherwise you could end up with invalid SQL generated.
Initializing the i18n Database Tables
You can either use the CakePHP console or you can manually create it. It is advised to use the console for
this, because it might happen that the layout changes in future versions of CakePHP. Sticking to the console
will make sure that you have the correct layout.:
./cake i18n
Select [I] which will run the i18n database initialization script. You will be asked if you want to drop any
existing and if you want to create it. Answer with yes if you are sure there is no i18n table already, and
answer with yes again to create the table.
Attaching the Translate Behavior to your Models
Add it to your model by using the $actsAs property like in the following example.:
class Post extends AppModel {
public $actsAs = array(
’Translate’
);
}
This will do nothing yet, because it expects a couple of options before it begins to work. You need to define
which fields of the current model should be tracked in the translation table we’ve created in the first step.
Defining the Fields
You can set the fields by simply extending the ’Translate’ value with another array, like so:
298 Chapter 8. Models](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-304-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
Retrieve all translation records for a field If you want to have all translation records attached to the
current model record you simply extend the field array in your behavior setup as shown below. The naming
is completely up to you.:
class Post extends AppModel {
public $actsAs = array(
’Translate’ => array(
’title’ => ’titleTranslation’
)
);
}
With this setup the result of $this->Post->find() should look something like this:
Array
(
[Post] => Array
(
[id] => 1
[title] => Beispiel Eintrag
[body] => lorem ipsum...
[locale] => de_de
)
[titleTranslation] => Array
(
[0] => Array
(
[id] => 1
[locale] => en_us
[model] => Post
[foreign_key] => 1
[field] => title
[content] => Example entry
)
[1] => Array
(
[id] => 2
[locale] => de_de
[model] => Post
[foreign_key] => 1
[field] => title
[content] => Beispiel Eintrag
)
)
)
Note: The model record contains a virtual field called “locale”. It indicates which locale is used in this
result.
Note that only fields of the model you are directly doing ‘find‘ on will be translated. Models attached via as-
300 Chapter 8. Models](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-306-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
sociations won’t be translated because triggering callbacks on associated models is currently not supported.
Using the bindTranslation method You can also retrieve all translations, only when you need them, using
the bindTranslation method
TranslateBehavior::bindTranslation($fields, $reset)
$fields is a named-key array of field and association name, where the key is the translatable field and the
value is the fake association name.:
$this->Post->bindTranslation(array(’title’ => ’titleTranslation’));
// need at least recursive 1 for this to work.
$this->Post->find(’all’, array(’recursive’ => 1));
With this setup the result of your find() should look something like this:
Array
(
[Post] => Array
(
[id] => 1
[title] => Beispiel Eintrag
[body] => lorem ipsum...
[locale] => de_de
)
[titleTranslation] => Array
(
[0] => Array
(
[id] => 1
[locale] => en_us
[model] => Post
[foreign_key] => 1
[field] => title
[content] => Example entry
)
[1] => Array
(
[id] => 2
[locale] => de_de
[model] => Post
[foreign_key] => 1
[field] => title
[content] => Beispiel Eintrag
)
)
)
More on models 301](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-307-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
· International
Adding data In the previous section, we used existing data and checked that it looked hierarchal via the
method generateTreeList. However, usually you would add your data in exactly the same way as you
would for any model. For example:
// pseudo controller code
$data[’Category’][’parent_id’] = 3;
$data[’Category’][’name’] = ’Skating’;
$this->Category->save($data);
When using the tree behavior it’s not necessary to do any more than set the parent_id, and the tree behavior
will take care of the rest. If you don’t set the parent_id, the tree behavior will add to the tree making your
new addition a new top level entry:
// pseudo controller code
$data = array();
$data[’Category’][’name’] = ’Other People’s Categories’;
$this->Category->save($data);
Running the above two code snippets would alter your tree as follows:
• My Categories
– Fun
* Sport
· Surfing
· Extreme knitting
· Skating New
* Friends
· Gerald
· Gwendolyn
– Work
* Reports
· Annual
· Status
* Trips
· National
· International
• Other People’s Categories New
More on models 307](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-313-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
childCount($id = null, $direct = false)
As with the method children, childCount takes the primary key value (the id) of a row and
returns how many children it has. The second optional parameter defines whether or not only direct
children are counted. Using the example data from the previous section:
$totalChildren = $this->Category->childCount(1); // will output 11
// -- or --
$this->Category->id = 1;
$directChildren = $this->Category->childCount(); // will output 11
// Only counts the direct descendants of this category
$numChildren = $this->Category->childCount(1, true); // will output 2
generateTreeList($conditions=null, $keyPath=null, $valuePath=null, $spacer= ‘_’,
$recursive=null)
Parameters
• $conditions – Uses the same conditional options as find().
• $keyPath – Path to the field to use for the key.
• $valuePath – Path to the field to use for the label.
• $spacer – The string to use in front of each item to indicate depth.
• $recursive – The number of levels deep to fetch associated records
This method will return data similar to find(‘list’) but with a nested prefix that is specified in the
spacer option to show the structure of your data. Below is an example of what you can expect this
method to return:
$treelist = $this->Category->generateTreeList();
Output:
array(
[1] => "My Categories",
[2] => "_Fun",
[3] => "__Sport",
[4] => "___Surfing",
[16] => "___Skating",
[6] => "__Friends",
[7] => "___Gerald",
[8] => "___Gwendolyn",
[9] => "_Work",
[13] => "__Trips",
[14] => "___National",
[15] => "___International",
[17] => "Other People’s Categories",
[5] => "_Extreme fishing"
)
More on models 311](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-317-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
getParentNode()
This convenience function will, as the name suggests, return the parent node for any node, or false if
the node has no parent (it’s the root node). For example:
$parent = $this->Category->getParentNode(2); //<- id for fun
// $parent contains All categories
getPath($id = null, $fields = null, $recursive = null)
The ‘path’ when referring to hierarchal data is how you get from where you are to the top. So for
example the path from the category “International” is:
•My Categories
•...
•Work
–Trips
*...
*International
Using the id of “International” getPath will return each of the parents in turn (starting from the top).:
$parents = $this->Category->getPath(15);
// contents of $parents
array(
[0] => array(
’Category’ => array(’id’ => 1, ’name’ => ’My Categories’, ..)
),
[1] => array(
’Category’ => array(’id’ => 9, ’name’ => ’Work’, ..)
),
[2] => array(
’Category’ => array(’id’ => 13, ’name’ => ’Trips’, ..)
),
[3] => array(
’Category’ => array(’id’ => 15, ’name’ => ’International’, ..)
),
)
Advanced Usage
The tree behavior doesn’t only work in the background, there are a number of specific meth-
ods defined in the behavior to cater for all your hierarchical data needs, and any unexpected
problems that might arise in the process.
TreeBehavior::moveDown()
312 Chapter 8. Models](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-318-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
Example:
// Rebuild all the left and right fields based on the parent_id
$this->Category->recover();
// or
$this->Category->recover(’parent’);
// Rebuild all the parent_id’s based on the lft and rght fields
$this->Category->recover(’tree’);
TreeBehavior::reorder($options = array())
Reorders the nodes (and child nodes) of the tree according to the field and direction specified in
the parameters. This method does not change the parent of any node.
Reordering affects all nodes in the tree by default, however the following options can affect the
process:
• ’id’ - only reorder nodes below this node.
• ’field‘ - field to use for sorting, default is the displayField for the model.
• ’order’ - ’ASC’ for ascending, ’DESC’ for descending sort.
• ’verify’ - whether or not to verify the tree prior to resorting.
$options is used to pass all extra parameters, and has the following possible keys by default,
all of which are optional:
array(
’id’ => null,
’field’ => $model->displayField,
’order’ => ’ASC’,
’verify’ => true
)
TreeBehavior::verify()
Returns true if the tree is valid otherwise an array of errors, with fields for type, incorrect
index and message.
Each record in the output array is an array of the form (type, id, message)
• type is either ’index’ or ’node’
• ’id’ is the id of the erroneous node.
• ’message’ depends on the error
Example Use:
$this->Category->verify();
Example output:
Array
(
[0] => Array
316 Chapter 8. Models](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-322-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
(
[0] => node
[1] => 3
[2] => left and right values identical
)
[1] => Array
(
[0] => node
[1] => 2
[2] => The parent node 999 doesn ’ t exist
)
[10] => Array
(
[0] => index
[1] => 123
[2] => missing
)
[99] => Array
(
[0] => node
[1] => 163
[2] => left greater than right
)
)
Using Behaviors
Behaviors are attached to models through the $actsAs model class variable:
class Category extends AppModel {
public $actsAs = array(’Tree’);
}
This example shows how a Category model could be managed in a tree structure using the TreeBehavior.
Once a behavior has been specified, use the methods added by the behavior as if they always existed as part
of the original model:
// Set ID
$this->Category->id = 42;
// Use behavior method, children():
$kids = $this->Category->children();
Some behaviors may require or allow settings to be defined when the behavior is attached to the model.
Here, we tell our TreeBehavior the names of the “left” and “right” fields in the underlying database table:
class Category extends AppModel {
public $actsAs = array(’Tree’ => array(
’left’ => ’left_node’,
’right’ => ’right_node’
More on models 317](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-323-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
// We will change one setting from our already attached behavior
$this->Category->Behaviors->load(’Tree’, array(’left’ => ’new_left_node’));
There’s also a method to obtain the list of behaviors a model has attached. If we pass the name of a behavior
to the method, it will tell us if that behavior is attached to the model, otherwise it will give us the list of
attached behaviors:
// If the Translate behavior is not attached
if (!$this->Category->Behaviors->loaded(’Translate’)) {
// Get the list of all behaviors the model has attached
$behaviors = $this->Category->Behaviors->loaded();
}
Creating Behaviors
Behaviors that are attached to Models get their callbacks called automatically. The callbacks are sim-
ilar to those found in Models: beforeFind, afterFind, beforeValidate, afterValidate,
beforeSave, afterSave, beforeDelete, afterDelete and onError - see Callback Methods.
Your behaviors should be placed in app/Model/Behavior. They are named in CamelCase and postfixed
by Behavior, ex. NameBehavior.php. It’s often helpful to use a core behavior as a template when creating
your own. Find them in lib/Cake/Model/Behavior/.
Every callback and behavior method takes a reference to the model it is being called from as the first
parameter.
Besides implementing the callbacks, you can add settings per behavior and/or model behavior attachment.
Information about specifying settings can be found in the chapters about core behaviors and their configu-
ration.
A quick example that illustrates how behavior settings can be passed from the model to the behavior:
class Post extends AppModel {
public $actsAs = array(
’YourBehavior’ => array(
’option1_key’ => ’option1_value’
)
);
}
Since behaviors are shared across all the model instances that use them, it’s a good practice to store the
settings per alias/model name that is using the behavior. When created behaviors will have their setup()
method called:
public function setup(Model $Model, $settings = array()) {
if (!isset($this->settings[$Model->alias])) {
$this->settings[$Model->alias] = array(
’option1_key’ => ’option1_default_value’,
’option2_key’ => ’option2_default_value’,
’option3_key’ => ’option3_default_value’,
);
}
More on models 319](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-325-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
$this->settings[$Model->alias] = array_merge(
$this->settings[$Model->alias], (array)$settings);
}
Creating behavior methods
Behavior methods are automatically available on any model acting as the behavior. For example if you had:
class Duck extends AppModel {
public $actsAs = array(’Flying’);
}
You would be able to call FlyingBehavior methods as if they were methods on your Duck model.
When creating behavior methods you automatically get passed a reference of the calling model as the first
parameter. All other supplied parameters are shifted one place to the right. For example:
$this->Duck->fly(’toronto’, ’montreal’);
Although this method takes two parameters, the method signature should look like:
public function fly(Model $Model, $from, $to) {
// Do some flying.
}
Keep in mind that methods called in a $this->doIt() fashion from inside a behavior method will not
get the $model parameter automatically appended.
Mapped methods
In addition to providing ‘mixin’ methods, behaviors can also provide pattern matching methods. Behaviors
can also define mapped methods. Mapped methods use pattern matching for method invocation. This allows
you to create methods similar to Model::findAllByXXX methods on your behaviors. Mapped methods
need to be declared in your behaviors $mapMethods array. The method signature for a mapped method is
slightly different than a normal behavior mixin method:
class MyBehavior extends ModelBehavior {
public $mapMethods = array(’/do(w+)/’ => ’doSomething’);
public function doSomething(Model $model, $method, $arg1, $arg2) {
debug(func_get_args());
//do something
}
}
The above will map every doXXX() method call to the behavior. As you can see, the model is still the first
parameter, but the called method name will be the 2nd parameter. This allows you to munge the method
name for additional information, much like Model::findAllByXX. If the above behavior was attached
to a model the following would happen:
320 Chapter 8. Models](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-326-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
* datasource. If this is your case then set a ‘‘schema‘‘ property on your
* models and simply return ‘‘$model->schema‘‘ here instead.
*/
public function describe($model) {
return $this->_schema;
}
/**
* calculate() is for determining how we will count the records and is
* required to get ‘‘update()‘‘ and ‘‘delete()‘‘ to work.
*
* We don’t count the records here but return a string to be passed to
* ‘‘read()‘‘ which will do the actual counting. The easiest way is to just
* return the string ’COUNT’ and check for it in ‘‘read()‘‘ where
* ‘‘$data[’fields’] === ’COUNT’‘‘.
*/
public function calculate(Model $model, $func, $params = array()) {
return ’COUNT’;
}
/**
* Implement the R in CRUD. Calls to ‘‘Model::find()‘‘ arrive here.
*/
public function read(Model $model, $queryData = array(),
$recursive = null) {
/**
* Here we do the actual count as instructed by our calculate()
* method above. We could either check the remote source or some
* other way to get the record count. Here we’ll simply return 1 so
* ‘‘update()‘‘ and ‘‘delete()‘‘ will assume the record exists.
*/
if ($queryData[’fields’] === ’COUNT’) {
return array(array(array(’count’ => 1)));
}
/**
* Now we get, decode and return the remote data.
*/
$queryData[’conditions’][’apiKey’] = $this->config[’apiKey’];
$json = $this->Http->get(
’http://example.com/api/list.json’,
$queryData[’conditions’]
);
$res = json_decode($json, true);
if (is_null($res)) {
$error = json_last_error();
throw new CakeException($error);
}
return array($model->alias => $res);
}
/**
* Implement the C in CRUD. Calls to ‘‘Model::save()‘‘ without $model->id
* set arrive here.
More on models 325](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-331-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
*/
public function create(Model $model, $fields = null, $values = null) {
$data = array_combine($fields, $values);
$data[’apiKey’] = $this->config[’apiKey’];
$json = $this->Http->post(’http://example.com/api/set.json’, $data);
$res = json_decode($json, true);
if (is_null($res)) {
$error = json_last_error();
throw new CakeException($error);
}
return true;
}
/**
* Implement the U in CRUD. Calls to ‘‘Model::save()‘‘ with $Model->id
* set arrive here. Depending on the remote source you can just call
* ‘‘$this->create()‘‘.
*/
public function update(Model $model, $fields = null, $values = null,
$conditions = null) {
return $this->create($model, $fields, $values);
}
/**
* Implement the D in CRUD. Calls to ‘‘Model::delete()‘‘ arrive here.
*/
public function delete(Model $model, $id = null) {
$json = $this->Http->get(’http://example.com/api/remove.json’, array(
’id’ => $id[$model->alias . ’.id’],
’apiKey’ => $this->config[’apiKey’],
));
$res = json_decode($json, true);
if (is_null($res)) {
$error = json_last_error();
throw new CakeException($error);
}
return true;
}
}
We can then configure the datasource in our app/Config/database.php file by adding something
like this:
public $faraway = array(
’datasource’ => ’FarAwaySource’,
’apiKey’ => ’1234abcd’,
);
Then use the database config in our models like this:
class MyModel extends AppModel {
public $useDbConfig = ’faraway’;
}
326 Chapter 8. Models](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-332-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
We can retrieve data from our remote source using the familiar model methods:
// Get all messages from ’Some Person’
$messages = $this->MyModel->find(’all’, array(
’conditions’ => array(’name’ => ’Some Person’),
));
Tip: Using find types other than ’all’ can have unexpected results if the result of your read method is
not a numerically indexed array.
Similarly we can save a new message:
$this->MyModel->save(array(
’name’ => ’Some Person’,
’message’ => ’New Message’,
));
Update the previous message:
$this->MyModel->id = 42;
$this->MyModel->save(array(
’message’ => ’Updated message’,
));
And delete the message:
$this->MyModel->delete(42);
Plugin DataSources
You can also package Datasources into plugins.
Simply place your datasource file into Plugin/[YourPlugin]/Model/Datasource/[YourSource].php
and refer to it using the plugin notation:
public $faraway = array(
’datasource’ => ’MyPlugin.FarAwaySource’,
’apiKey’ => ’abcd1234’,
);
Connecting to SQL Server
The Sqlserver datasource depends on Microsoft’s PHP extension called pdo_sqlsrv. This PHP Extension is
not included in the base installation of PHP and must be installed separately.
Also the SQL Server Native Client must be installed for the extension to work. As the Native Client is
available only for Windows you will not be able to install it on Linux, Mac OS X or FreeBSD.
So if the Sqlserver Datasource errors out with:
More on models 327](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-333-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
Virtual fields and model aliases
When you are using virtualFields and models with aliases that are not the same as their name, you can run
into problems as virtualFields do not update to reflect the bound alias. If you are using virtualFields in
models that have more than one alias it is best to define the virtualFields in your model’s constructor:
public function __construct($id = false, $table = null, $ds = null) {
parent::__construct($id, $table, $ds);
$this->virtualFields[’name’] = sprintf(
’CONCAT(%s.first_name, " ", %s.last_name)’, $this->alias, $this->alias
);
}
This will allow your virtualFields to work for any alias you give a model.
Virtual fields in SQL queries
Using functions in direct SQL queries will prevent data from being returned in the same array as your
model’s data. For example this:
$this->Timelog->query(
"SELECT
project_id, SUM(id) as TotalHours
FROM
timelogs
AS
Timelog
GROUP BY
project_id;"
);
would return something like this:
Array
(
[0] => Array
(
[Timelog] => Array
(
[project_id] => 1234
)
[0] => Array
(
[TotalHours] => 25.5
)
)
)
If we want to group TotalHours into our Timelog array we should specify a virtual field for our aggregate
column. We can add this new virtual field on the fly rather than permanently declaring it in the model. We
will provide a default value of 0 in case another query attempts to use this virtual field. If that were to occur,
0 would be returned in the TotalHours column:
336 Chapter 8. Models](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-342-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
$this->Timelog->virtualFields[’TotalHours’] = 0;
In addition to adding the virtual field we also need to alias our column using the form of
MyModel__MyField like this:
$this->Timelog->query(
"SELECT
project_id, SUM(id) as Timelog__TotalHours
FROM
timelogs
AS
Timelog
GROUP BY
project_id;"
);
Running the query again after specifying the virtual field should result in a cleaner grouping of values:
Array
(
[0] => Array
(
[Timelog] => Array
(
[project_id] => 1234
[TotalHours] => 25.5
)
)
)
Limitations of virtualFields
The implementation of virtualFields has a few limitations. First you cannot use virtualFields
on associated models for conditions, order, or fields arrays. Doing so will generally result in an SQL error
as the fields are not replaced by the ORM. This is because it difficult to estimate the depth at which an
associated model might be found.
A common workaround for this implementation issue is to copy virtualFields from one model to
another at runtime when you need to access them:
$this->virtualFields[’name’] = $this->Author->virtualFields[’name’];
or:
$this->virtualFields += $this->Author->virtualFields;
Transactions
To perform a transaction, a model’s table must be of a datasource and type which supports transactions.
More on models 337](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-343-320.jpg)
![CHAPTER 9
Core Libraries
CakePHP comes with a plethora of built-in functions and classes. These classes and functions try to cover
some of the most common features required in web applications.
General Purpose
General purpose libraries are available and reused in many places across CakePHP.
General Purpose
Global Constants and Functions
While most of your day-to-day work in CakePHP will be utilizing core classes and methods, CakePHP
features a number of global convenience functions that may come in handy. Many of these functions are
for use with CakePHP classes (loading model or component classes), but many others make working with
arrays or strings a little easier.
We’ll also cover some of the constants available in CakePHP applications. Using these constants will help
make upgrades more smooth, but are also convenient ways to point to certain files or directories in your
CakePHP application.
Global Functions
Here are CakePHP’s globally available functions. Most of them are just convenience wrappers for other
CakePHP functionality, such as debugging and translating content.
__(string $string_id[, $formatArgs])
This function handles localization in CakePHP applications. The $string_id identifies the ID for
a translation. Strings used for translations are treated as format strings for sprintf(). You can
supply additional arguments to replace placeholders in your string:
339](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-345-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
// ...
}
In the previous example the order would not get saved if the event is stopped during the beforePlace
process.
Getting event results Every time a callback returns a value, it gets stored in the $result property of
the event object. This is useful when you want to allow callbacks to modify the event execution. Let’s take
again our beforePlace example and let callbacks modify the $order data.
Event results can be altered either using the event object result property directly or returning the value in the
callback itself:
// A listener callback
public function doSomething($event) {
// ...
$alteredData = $event->data[’order’] + $moreData;
return $alteredData;
}
// Another listener callback
public function doSomethingElse($event) {
// ...
$event->result[’order’] = $alteredData;
}
// Using the event result
public function place($order) {
$event = new CakeEvent(
’Model.Order.beforePlace’,
$this, array(’order’ => $order)
);
$this->getEventManager()->dispatch($event);
if (!empty($event->result[’order’])) {
$order = $event->result[’order’];
}
if ($this->Order->save($order)) {
// ...
}
// ...
}
It is possible to alter any event object property and have the new data passed to the next callback. In most of
the cases, providing objects as event data or result and directly altering the object is the best solution as the
reference is kept the same and modifications are shared across all callback calls.
Removing callbacks and listeners If for any reason you want to remove any callback from the event
manager just call the CakeEventManager::detach() method using as arguments the first two params
you used for attaching it:
General Purpose 357](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-363-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
$data = $this->data;
if (empty($this->data)) {
$data = $this->read();
}
if (!$data[’User’][’group_id’]) {
return null;
} else {
return array(’Group’ => array(’id’ => $data[’User’][’group_id’]));
}
}
In the above example the return is an array that looks similar to the results of a model find. It is important
to have the id value set or the parentNode relation will fail. The AclBehavior uses this data to construct its
tree structure.
node() The AclBehavior also allows you to retrieve the Acl node associated with a model record. After
setting $model->id. You can use $model->node() to retrieve the associated Acl node.
You can also retrieve the Acl Node for any row, by passing in a data array:
$this->User->id = 1;
$node = $this->User->node();
$user = array(’User’ => array(
’id’ => 1
));
$node = $this->User->node($user);
Will both return the same Acl Node information.
If you had setup AclBehavior to create both ACO and ARO nodes, you need to specify which node type you
want:
$this->User->id = 1;
$node = $this->User->node(null, ’Aro’);
$user = array(’User’ => array(
’id’ => 1
));
$node = $this->User->node($user, ’Aro’);
Containable
class ContainableBehavior
A new addition to the CakePHP 1.2 core is the ContainableBehavior. This model behavior allows
you to filter and limit model find operations. Using Containable will help you cut down on needless wear
and tear on your database, increasing the speed and overall performance of your application. The class will
also help you search and filter your data for your users in a clean and consistent way.
Containable allows you to streamline and simplify operations on your model bindings. It works by temporar-
ily or permanently altering the associations of your models. It does this by using supplied the containments
to generate a series of bindModel and unbindModel calls. Since Containable only modifies existing
General Purpose 363](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-369-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
relationships it will not allow you to restrict results by distant associations. Instead you should refer to
Joining tables.
To use the new behavior, you can add it to the $actsAs property of your model:
class Post extends AppModel {
public $actsAs = array(’Containable’);
}
You can also attach the behavior on the fly:
$this->Post->Behaviors->load(’Containable’);
Using Containable To see how Containable works, let’s look at a few examples. First, we’ll start off with
a find() call on a model named ‘Post’. Let’s say that ‘Post’ hasMany ‘Comment’, and ‘Post’ hasAndBe-
longsToMany ‘Tag’. The amount of data fetched in a normal find() call is rather extensive:
debug($this->Post->find(’all’));
[0] => Array
(
[Post] => Array
(
[id] => 1
[title] => First article
[content] => aaa
[created] => 2008-05-18 00:00:00
)
[Comment] => Array
(
[0] => Array
(
[id] => 1
[post_id] => 1
[author] => Daniel
[email] => dan@example.com
[website] => http://example.com
[comment] => First comment
[created] => 2008-05-18 00:00:00
)
[1] => Array
(
[id] => 2
[post_id] => 1
[author] => Sam
[email] => sam@example.net
[website] => http://example.net
[comment] => Second comment
[created] => 2008-05-18 00:00:00
)
)
[Tag] => Array
(
364 Chapter 9. Core Libraries](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-370-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
[0] => Array
(
[id] => 1
[name] => Awesome
)
[1] => Array
(
[id] => 2
[name] => Baking
)
)
)
[1] => Array
(
[Post] => Array
(...
For some interfaces in your application, you may not need that much information from the Post model. One
thing the ContainableBehavior does is help you cut down on what find() returns.
For example, to get only the post-related information, you can do the following:
$this->Post->contain();
$this->Post->find(’all’);
You can also invoke Containable’s magic from inside the find() call:
$this->Post->find(’all’, array(’contain’ => false));
Having done that, you end up with something a lot more concise:
[0] => Array
(
[Post] => Array
(
[id] => 1
[title] => First article
[content] => aaa
[created] => 2008-05-18 00:00:00
)
)
[1] => Array
(
[Post] => Array
(
[id] => 2
[title] => Second article
[content] => bbb
[created] => 2008-05-19 00:00:00
)
)
This sort of help isn’t new: in fact, you can do that without the ContainableBehavior doing something
like this:
General Purpose 365](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-371-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
$this->Post->recursive = -1;
$this->Post->find(’all’);
Containable really shines when you have complex associations, and you want to pare down things that sit
at the same level. The model’s $recursive property is helpful if you want to hack off an entire level of
recursion, but not when you want to pick and choose what to keep at each level. Let’s see how it works by
using the contain() method.
The contain method’s first argument accepts the name, or an array of names, of the models to keep in the
find operation. If we wanted to fetch all posts and their related tags (without any comment information),
we’d try something like this:
$this->Post->contain(’Tag’);
$this->Post->find(’all’);
Again, we can use the contain key inside a find() call:
$this->Post->find(’all’, array(’contain’ => ’Tag’));
Without Containable, you’d end up needing to use the unbindModel() method of the model, multiple
times if you’re paring off multiple models. Containable creates a cleaner way to accomplish this same task.
Containing deeper associations Containable also goes a step deeper: you can filter the data of the asso-
ciated models. If you look at the results of the original find() call, notice the author field in the Comment
model. If you are interested in the posts and the names of the comment authors — and nothing else — you
could do something like the following:
$this->Post->contain(’Comment.author’);
$this->Post->find(’all’);
// or..
$this->Post->find(’all’, array(’contain’ => ’Comment.author’));
Here, we’ve told Containable to give us our post information, and just the author field of the associated
Comment model. The output of the find call might look something like this:
[0] => Array
(
[Post] => Array
(
[id] => 1
[title] => First article
[content] => aaa
[created] => 2008-05-18 00:00:00
)
[Comment] => Array
(
[0] => Array
(
[author] => Daniel
[post_id] => 1
366 Chapter 9. Core Libraries](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-372-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
)
[1] => Array
(
[author] => Sam
[post_id] => 1
)
)
)
[1] => Array
(...
As you can see, the Comment arrays only contain the author field (plus the post_id which is needed by
CakePHP to map the results).
You can also filter the associated Comment data by specifying a condition:
$this->Post->contain(’Comment.author = "Daniel"’);
$this->Post->find(’all’);
//or...
$this->Post->find(’all’, array(’contain’ => ’Comment.author = "Daniel"’));
This gives us a result that gives us posts with comments authored by Daniel:
[0] => Array
(
[Post] => Array
(
[id] => 1
[title] => First article
[content] => aaa
[created] => 2008-05-18 00:00:00
)
[Comment] => Array
(
[0] => Array
(
[id] => 1
[post_id] => 1
[author] => Daniel
[email] => dan@example.com
[website] => http://example.com
[comment] => First comment
[created] => 2008-05-18 00:00:00
)
)
)
There is an important caveat to using Containable when filtering on a deeper association. In the previous
example, assume you had 3 posts in your database and Daniel had commented on 2 of those posts. The
operation $this->Post->find(‘all’, array(‘contain’ => ‘Comment.author = “Daniel”’)); would return ALL
3 posts, not just the 2 posts that Daniel had commented on. It won’t return all comments however, just
comments by Daniel.:
General Purpose 367](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-373-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
[0] => Array
(
[Post] => Array
(
[id] => 1
[title] => First article
[content] => aaa
[created] => 2008-05-18 00:00:00
)
[Comment] => Array
(
[0] => Array
(
[id] => 1
[post_id] => 1
[author] => Daniel
[email] => dan@example.com
[website] => http://example.com
[comment] => First comment
[created] => 2008-05-18 00:00:00
)
)
)
[1] => Array
(
[Post] => Array
(
[id] => 2
[title] => Second article
[content] => bbb
[created] => 2008-05-18 00:00:00
)
[Comment] => Array
(
)
)
[2] => Array
(
[Post] => Array
(
[id] => 3
[title] => Third article
[content] => ccc
[created] => 2008-05-18 00:00:00
)
[Comment] => Array
(
[0] => Array
(
[id] => 22
[post_id] => 3
[author] => Daniel
[email] => dan@example.com
368 Chapter 9. Core Libraries](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-374-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
[website] => http://example.com
[comment] => Another comment
[created] => 2008-05-18 00:00:00
)
)
)
If you want to filter the posts by the comments, so that posts without a comment by Daniel won’t be returned,
the easiest way is to find all the comments by Daniel and contain the Posts.:
$this->Comment->find(’all’, array(
’conditions’ => ’Comment.author = "Daniel"’,
’contain’ => ’Post’
));
Additional filtering can be performed by supplying the standard find options:
$this->Post->find(’all’, array(’contain’ => array(
’Comment’ => array(
’conditions’ => array(’Comment.author =’ => "Daniel"),
’order’ => ’Comment.created DESC’
)
)));
Here’s an example of using the ContainableBehavior when you’ve got deep and complex model
relationships.
Let’s consider the following model associations:
User->Profile
User->Account->AccountSummary
User->Post->PostAttachment->PostAttachmentHistory->HistoryNotes
User->Post->Tag
This is how we retrieve the above associations with Containable:
$this->User->find(’all’, array(
’contain’ => array(
’Profile’,
’Account’ => array(
’AccountSummary’
),
’Post’ => array(
’PostAttachment’ => array(
’fields’ => array(’id’, ’name’),
’PostAttachmentHistory’ => array(
’HistoryNotes’ => array(
’fields’ => array(’id’, ’note’)
)
)
),
’Tag’ => array(
’conditions’ => array(’Tag.name LIKE’ => ’%happy%’)
)
General Purpose 369](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-375-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
See the section Using Containable for further details.
Here’s an example of how to contain associations when paginating:
$this->paginate[’User’] = array(
’contain’ => array(’Profile’, ’Account’),
’order’ => ’User.username’
);
$users = $this->paginate(’User’);
Note: If you contained the associations through the model instead, it will not honor Containable’s recursive
option. So if you set recursive to -1 for example for the model, it won’t work:
$this->User->recursive = -1;
$this->User->contain(array(’Profile’, ’Account’));
$users = $this->paginate(’User’);
Translate
class TranslateBehavior
TranslateBehavior is actually quite easy to setup and works out of the box with very little configuration. In
this section, you will learn how to add and setup the behavior to use in any model.
If you are using TranslateBehavior in alongside containable issue, be sure to set the ‘fields’ key for your
queries. Otherwise you could end up with invalid SQL generated.
Initializing the i18n Database Tables You can either use the CakePHP console or you can manually
create it. It is advised to use the console for this, because it might happen that the layout changes in future
versions of CakePHP. Sticking to the console will make sure that you have the correct layout.:
./cake i18n
Select [I] which will run the i18n database initialization script. You will be asked if you want to drop any
existing and if you want to create it. Answer with yes if you are sure there is no i18n table already, and
answer with yes again to create the table.
Attaching the Translate Behavior to your Models Add it to your model by using the $actsAs property
like in the following example.:
class Post extends AppModel {
public $actsAs = array(
’Translate’
);
}
This will do nothing yet, because it expects a couple of options before it begins to work. You need to define
which fields of the current model should be tracked in the translation table we’ve created in the first step.
General Purpose 371](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-377-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
Retrieve all translation records for a field If you want to have all translation records attached to the
current model record you simply extend the field array in your behavior setup as shown below. The naming
is completely up to you.:
class Post extends AppModel {
public $actsAs = array(
’Translate’ => array(
’title’ => ’titleTranslation’
)
);
}
With this setup the result of $this->Post->find() should look something like this:
Array
(
[Post] => Array
(
[id] => 1
[title] => Beispiel Eintrag
[body] => lorem ipsum...
[locale] => de_de
)
[titleTranslation] => Array
(
[0] => Array
(
[id] => 1
[locale] => en_us
[model] => Post
[foreign_key] => 1
[field] => title
[content] => Example entry
)
[1] => Array
(
[id] => 2
[locale] => de_de
[model] => Post
[foreign_key] => 1
[field] => title
[content] => Beispiel Eintrag
)
)
)
Note: The model record contains a virtual field called “locale”. It indicates which locale is used in this
result.
Note that only fields of the model you are directly doing ‘find‘ on will be translated. Models attached via as-
General Purpose 373](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-379-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
sociations won’t be translated because triggering callbacks on associated models is currently not supported.
Using the bindTranslation method You can also retrieve all translations, only when you need them, using
the bindTranslation method
TranslateBehavior::bindTranslation($fields, $reset)
$fields is a named-key array of field and association name, where the key is the translatable field and the
value is the fake association name.:
$this->Post->bindTranslation(array(’title’ => ’titleTranslation’));
// need at least recursive 1 for this to work.
$this->Post->find(’all’, array(’recursive’ => 1));
With this setup the result of your find() should look something like this:
Array
(
[Post] => Array
(
[id] => 1
[title] => Beispiel Eintrag
[body] => lorem ipsum...
[locale] => de_de
)
[titleTranslation] => Array
(
[0] => Array
(
[id] => 1
[locale] => en_us
[model] => Post
[foreign_key] => 1
[field] => title
[content] => Example entry
)
[1] => Array
(
[id] => 2
[locale] => de_de
[model] => Post
[foreign_key] => 1
[field] => title
[content] => Beispiel Eintrag
)
)
)
Saving in another language You can force the model which is using the TranslateBehavior to save in a
language other than the one detected.
374 Chapter 9. Core Libraries](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-380-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
null,
null,
null,
’ ’
);
debug($data); die;
}
}
and an even simpler model definition:
// app/Model/Category.php
class Category extends AppModel {
public $actsAs = array(’Tree’);
}
We can check what our category tree data looks like by visiting /categories You should see something like
this:
• My Categories
– Fun
* Sport
· Surfing
· Extreme knitting
* Friends
· Gerald
· Gwendolyn
– Work
* Reports
· Annual
· Status
* Trips
· National
· International
Adding data In the previous section, we used existing data and checked that it looked hierarchal via the
method generateTreeList. However, usually you would add your data in exactly the same way as you
would for any model. For example:
// pseudo controller code
$data[’Category’][’parent_id’] = 3;
$data[’Category’][’name’] = ’Skating’;
$this->Category->save($data);
General Purpose 379](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-385-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
When using the tree behavior it’s not necessary to do any more than set the parent_id, and the tree behavior
will take care of the rest. If you don’t set the parent_id, the tree behavior will add to the tree making your
new addition a new top level entry:
// pseudo controller code
$data = array();
$data[’Category’][’name’] = ’Other People’s Categories’;
$this->Category->save($data);
Running the above two code snippets would alter your tree as follows:
• My Categories
– Fun
* Sport
· Surfing
· Extreme knitting
· Skating New
* Friends
· Gerald
· Gwendolyn
– Work
* Reports
· Annual
· Status
* Trips
· National
· International
• Other People’s Categories New
Modifying data Modifying data is as transparent as adding new data. If you modify something, but do
not change the parent_id field - the structure of your data will remain unchanged. For example:
// pseudo controller code
$this->Category->id = 5; // id of Extreme knitting
$this->Category->save(array(’name’ => ’Extreme fishing’));
The above code did not affect the parent_id field - even if the parent_id is included in the data that is passed
to save if the value doesn’t change, neither does the data structure. Therefore the tree of data would now
look like:
• My Categories
380 Chapter 9. Core Libraries](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-386-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
$directChildren = $this->Category->childCount(); // will output 11
// Only counts the direct descendants of this category
$numChildren = $this->Category->childCount(1, true); // will output 2
generateTreeList($conditions=null, $keyPath=null, $valuePath=null, $spacer= ‘_’,
$recursive=null)
Parameters
• $conditions – Uses the same conditional options as find().
• $keyPath – Path to the field to use for the key.
• $valuePath – Path to the field to use for the label.
• $spacer – The string to use in front of each item to indicate depth.
• $recursive – The number of levels deep to fetch associated records
This method will return data similar to find(‘list’) but with a nested prefix that is specified in the
spacer option to show the structure of your data. Below is an example of what you can expect this
method to return:
$treelist = $this->Category->generateTreeList();
Output:
array(
[1] => "My Categories",
[2] => "_Fun",
[3] => "__Sport",
[4] => "___Surfing",
[16] => "___Skating",
[6] => "__Friends",
[7] => "___Gerald",
[8] => "___Gwendolyn",
[9] => "_Work",
[13] => "__Trips",
[14] => "___National",
[15] => "___International",
[17] => "Other People’s Categories",
[5] => "_Extreme fishing"
)
getParentNode()
This convenience function will, as the name suggests, return the parent node for any node, or false if
the node has no parent (it’s the root node). For example:
$parent = $this->Category->getParentNode(2); //<- id for fun
// $parent contains All categories
getPath($id = null, $fields = null, $recursive = null)
384 Chapter 9. Core Libraries](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-390-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
The ‘path’ when referring to hierarchal data is how you get from where you are to the top. So for
example the path from the category “International” is:
•My Categories
•...
•Work
–Trips
*...
*International
Using the id of “International” getPath will return each of the parents in turn (starting from the top).:
$parents = $this->Category->getPath(15);
// contents of $parents
array(
[0] => array(
’Category’ => array(’id’ => 1, ’name’ => ’My Categories’, ..)
),
[1] => array(
’Category’ => array(’id’ => 9, ’name’ => ’Work’, ..)
),
[2] => array(
’Category’ => array(’id’ => 13, ’name’ => ’Trips’, ..)
),
[3] => array(
’Category’ => array(’id’ => 15, ’name’ => ’International’, ..)
),
)
Advanced Usage
The tree behavior doesn’t only work in the background, there are a number of specific meth-
ods defined in the behavior to cater for all your hierarchical data needs, and any unexpected
problems that might arise in the process.
TreeBehavior::moveDown()
Used to move a single node down the tree. You need to provide the ID of the element to be
moved and a positive number of how many positions the node should be moved down. All
child nodes for the specified node will also be moved.
Here is an example of a controller action (in a controller named Categories) that moves a spec-
ified node down the tree:
public function movedown($id = null, $delta = null) {
$this->Category->id = $id;
if (!$this->Category->exists()) {
throw new NotFoundException(__(’Invalid category’));
General Purpose 385](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-391-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
// Rebuild all the parent_id’s based on the lft and rght fields
$this->Category->recover(’tree’);
TreeBehavior::reorder($options = array())
Reorders the nodes (and child nodes) of the tree according to the field and direction specified in
the parameters. This method does not change the parent of any node.
Reordering affects all nodes in the tree by default, however the following options can affect the
process:
• ’id’ - only reorder nodes below this node.
• ’field‘ - field to use for sorting, default is the displayField for the model.
• ’order’ - ’ASC’ for ascending, ’DESC’ for descending sort.
• ’verify’ - whether or not to verify the tree prior to resorting.
$options is used to pass all extra parameters, and has the following possible keys by default,
all of which are optional:
array(
’id’ => null,
’field’ => $model->displayField,
’order’ => ’ASC’,
’verify’ => true
)
TreeBehavior::verify()
Returns true if the tree is valid otherwise an array of errors, with fields for type, incorrect
index and message.
Each record in the output array is an array of the form (type, id, message)
• type is either ’index’ or ’node’
• ’id’ is the id of the erroneous node.
• ’message’ depends on the error
Example Use:
$this->Category->verify();
Example output:
Array
(
[0] => Array
(
[0] => node
[1] => 3
[2] => left and right values identical
)
[1] => Array
General Purpose 389](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-395-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
(
[0] => node
[1] => 2
[2] => The parent node 999 doesn ’ t exist
)
[10] => Array
(
[0] => index
[1] => 123
[2] => missing
)
[99] => Array
(
[0] => node
[1] => 163
[2] => left greater than right
)
)
Using Behaviors Behaviors are attached to models through the $actsAs model class variable:
class Category extends AppModel {
public $actsAs = array(’Tree’);
}
This example shows how a Category model could be managed in a tree structure using the TreeBehavior.
Once a behavior has been specified, use the methods added by the behavior as if they always existed as part
of the original model:
// Set ID
$this->Category->id = 42;
// Use behavior method, children():
$kids = $this->Category->children();
Some behaviors may require or allow settings to be defined when the behavior is attached to the model.
Here, we tell our TreeBehavior the names of the “left” and “right” fields in the underlying database table:
class Category extends AppModel {
public $actsAs = array(’Tree’ => array(
’left’ => ’left_node’,
’right’ => ’right_node’
));
}
We can also attach several behaviors to a model. There’s no reason why, for example, our Category model
should only behave as a tree, it may also need internationalization support:
class Category extends AppModel {
public $actsAs = array(
’Tree’ => array(
390 Chapter 9. Core Libraries](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-396-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
// If the Translate behavior is not attached
if (!$this->Category->Behaviors->loaded(’Translate’)) {
// Get the list of all behaviors the model has attached
$behaviors = $this->Category->Behaviors->loaded();
}
Creating Behaviors Behaviors that are attached to Models get their callbacks called automatically.
The callbacks are similar to those found in Models: beforeFind, afterFind, beforeValidate,
afterValidate, beforeSave, afterSave, beforeDelete, afterDelete and onError -
see Callback Methods.
Your behaviors should be placed in app/Model/Behavior. They are named in CamelCase and postfixed
by Behavior, ex. NameBehavior.php. It’s often helpful to use a core behavior as a template when creating
your own. Find them in lib/Cake/Model/Behavior/.
Every callback and behavior method takes a reference to the model it is being called from as the first
parameter.
Besides implementing the callbacks, you can add settings per behavior and/or model behavior attachment.
Information about specifying settings can be found in the chapters about core behaviors and their configu-
ration.
A quick example that illustrates how behavior settings can be passed from the model to the behavior:
class Post extends AppModel {
public $actsAs = array(
’YourBehavior’ => array(
’option1_key’ => ’option1_value’
)
);
}
Since behaviors are shared across all the model instances that use them, it’s a good practice to store the
settings per alias/model name that is using the behavior. When created behaviors will have their setup()
method called:
public function setup(Model $Model, $settings = array()) {
if (!isset($this->settings[$Model->alias])) {
$this->settings[$Model->alias] = array(
’option1_key’ => ’option1_default_value’,
’option2_key’ => ’option2_default_value’,
’option3_key’ => ’option3_default_value’,
);
}
$this->settings[$Model->alias] = array_merge(
$this->settings[$Model->alias], (array)$settings);
}
Creating behavior methods Behavior methods are automatically available on any model acting as the
behavior. For example if you had:
392 Chapter 9. Core Libraries](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-398-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
create() inside a UsersController view, I’d 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.
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 form’s context.
All fields are assumed to belong to this model (unless otherwise specified), 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 prop-
erty to automatically detect whether to create an add or edit form. If $this->request->data
contains an array element named after the form’s model, and that array contains a non-empty value of
the model’s 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 field is generated to override the default HTTP
method.
402 Chapter 9. Core Libraries](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-408-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
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 configuration 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().
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’, ‘file’, ‘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 ‘file’ 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 file elements inside the
form. The absence of the proper enctype attribute will cause the file 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 specific action in your
current controller. For example, if you’d 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 isn’t 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:
General Purpose 403](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-409-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
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’
));
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 form’s 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 form’s 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
// has a label element
echo $this->Form->input(
’username’,
array(’label’ => ’Username’)
);
Closing the Form
FormHelper::end($options = null, $secureAttributes = array())
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:
404 Chapter 9. Core Libraries](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-410-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
echo $this->Form->inputs(array(
’name’ => array(’label’ => ’custom label’)
));
In addition to fields control, inputs() allows you to use a few additional options.
•fieldset Set to false to disable the fieldset. If a string is supplied it will be used as the class
name for the fieldset 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 field name with the
form helper methods, it’ll 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.fieldname as the
first parameter:
echo $this->Form->input(’Modelname.fieldname’);
If you need to specify multiple fields using the same field name, thus creating an array that can be saved in
one shot with saveAll(), use the following convention:
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 field-suffixes internally for datetime input creation. If you are using fields 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 specific to FormHelper::input().
408 Chapter 9. Core Libraries](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-414-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
• $options[’type’] You can force the type of an input, overriding model introspection, by spec-
ifying a type. In addition to the field types found in the Creating form elements, you can also create
‘file’, ‘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 input’s containing div. Using a string
value will set the div’s class name. An array will set the div’s attributes to those specified by the
array’s 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:
<div class="class_name">
<label for="UserName">Name</label>
<input name="data[User][name]" type="text" value="" id="UserName" />
</div>
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:
General Purpose 409](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-415-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
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>
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 & field classes set the error key to false:
410 Chapter 9. Core Libraries](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-416-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
$this->Form->input(’Model.field’, array(’error’ => false));
To disable only the error message, but retain the field 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
• $options[’before’], $options[’between’], $options[’separator’], and
$options[’after’]
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>
General Purpose 411](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-417-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
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 by 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 find yourself repeating the same options in multiple in-
put() calls, you can use inputDefaults‘ to keep your code dry:
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 specific types of inputs In addition to the generic input() method, FormHelper has
specific methods for generating a number of different types of inputs. These can be used to generate just
412 Chapter 9. Core Libraries](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-418-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
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 class name 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 field. The value is used if the
data passed to the form does not contain a value for the field (or if no data is passed at all).
Example usage:
echo $this->Form->input(’ingredient’, array(’default’ => ’Sugar’));
Example with select field (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 fields’ default values can be set by using the ‘selected’ key.
Beware of using false to assign a default value. A false value is used to disable/exclude options of
an input field, 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’
));
General Purpose 413](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-419-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
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 field to blank, use ‘value’ => ‘’ instead.
Options can also supplied as key-value pairs.
• $options[’hiddenField’] For certain input types (checkboxes, radios) a hidden input is cre-
ated so that the key in $this->request->data will exist even without a value specified:
<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 first. If the hidden input is on the page in multiple places, only
the last group of input’s values will be saved
In this example, only the tertiary colors would be passed, and the primary colors would be overridden:
414 Chapter 9. Core Libraries](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-420-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
<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 field 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
in the order defined by the dateFormat option.
• $options[’minYear’], $options[’maxYear’] Used in combination with a
date/datetime input. Defines the lower and/or upper end of values shown in the years select
field.
• $options[’orderYear’] Used in combination with a date/datetime input. Defines the order in
which the year values will be set. Valid values include ‘asc’, ‘desc’. The default value is ‘desc’.
• $options[’interval’] This option specifies the number of minutes between each option in the
minutes select box:
General Purpose 415](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-421-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
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-Specific Methods All elements are created under a form for the User model as in the
examples above. For this reason, the HTML code generated will contain attributes that reference to the User
model. Ex: name=data[User][username], id=UserUsername
FormHelper::label(string $fieldName, string $text, array $options)
Create a label element. $fieldName is used for generating the DOM id. If $text is undefined,
$fieldName will be used to inflect the label’s 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 class name:
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 specific 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’));
Will output:
<input name="data[User][username]" type="text" class="users"
id="UserUsername" />
FormHelper::password(string $fieldName, array $options)
Creates a password field.:
416 Chapter 9. Core Libraries](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-422-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
echo $this->Form->password(’password’);
Will output:
<input name="data[User][password]" value="" id="UserPassword"
type="password" />
FormHelper::hidden(string $fieldName, array $options)
Creates a hidden form input. Example:
echo $this->Form->hidden(’id’);
Will output:
<input name="data[User][id]" id="UserId" type="hidden" />
If the form is edited (that is, the array $this->request->data will contain the information
saved for the User model), the value corresponding to id field will automatically be added to the
HTML generated. Example for data[User][id] = 10:
<input name="data[User][id]" id="UserId" type="hidden" />
Changed in version 2.0: Hidden fields no longer remove the class attribute. This means that if there
are validation errors on hidden fields, the error-field class name will be applied.
FormHelper::textarea(string $fieldName, array $options)
Creates a textarea input field.:
echo $this->Form->textarea(’notes’);
Will output:
<textarea name="data[User][notes]" id="UserNotes"></textarea>
If the form is edited (that is, the array $this->request->data will contain the information
saved for the User model), the value corresponding to notes field will automatically be added to
the HTML generated. Example:
<textarea name="data[User][notes]" id="UserNotes">
This text is to be edited.
</textarea>
Note: The textarea input type allows for the $options attribute of ’escape’ which deter-
mines 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
General Purpose 417](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-423-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
In addition to the Common options, textarea() supports a few specific 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:
<textarea name="data[Form][textarea]" cols="5" rows="5" id="FormTextarea">
</textarea>
FormHelper::checkbox(string $fieldName, array $options)
Creates a checkbox form element. This method also generates an associated hidden form input to
force the submission of data for the specified field.:
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 don’t 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 $fieldName, 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
first element.
•$attributes[’disabled’] Setting this to true or ’disabled’ will disable all of the
generated radio buttons.
418 Chapter 9. Core Libraries](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-424-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
•$attributes[’legend’] Radio elements are wrapped with a legend and fieldset by de-
fault. 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:
<input name="data[User][gender]" id="UserGender_" value=""
type="hidden" />
<input name="data[User][gender]" id="UserGenderM" value="M"
type="radio" />
<label for="UserGenderM">Male</label>
<input name="data[User][gender]" id="UserGenderF" value="F"
type="radio" />
<label for="UserGenderF">Female</label>
If for some reason you don’t 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 $fieldName, array $options, array $attributes)
Creates a select element, populated with the items in $options, with the option specified
by $attributes[’value’] shown as selected by default. Set the ‘empty’ key in the
$attributes variable to false 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 specified 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:
General Purpose 419](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-425-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
<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’,
’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
fieldsets:
$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:
420 Chapter 9. Core Libraries](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-426-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
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’
));
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="checkbox">
<label for="ModelField1">Label 1</label>
</div>
<div class="checkbox">
<input name="data[Model][field][]" value="Value 2"
id="ModelField2" type="checkbox">
<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"
General Purpose 421](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-427-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
value="Value 1" id="ModelField1" type="checkbox">
<label for="ModelField1">Label 1</label>
</div>
<div class="checkbox">
<input name="data[Model][field][]" value="Value 2"
id="ModelField2" type="checkbox">
<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 $fieldName, array $options)
To add a file upload field to a form, you must first 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 file:
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 fields of type
‘file’. Each time the form is displayed, the value inside will be empty.
Upon submission, file fields 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 file
fields read the PHP manual section on file uploads4.
4
http://php.net/features.file-upload
422 Chapter 9. Core Libraries](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-428-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
Validating Uploads Below is an example validation method you could define in your model to validate
whether a file 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 file 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">
Note: When using $this->Form->file(), remember to set the form encoding-type, by setting the
type option to ‘file’ 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 specified title and a default type of “button”. Setting
$options[’type’] will output one of the three possible button types:
General Purpose 423](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-429-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
You can specify not to display empty values by setting “array(‘empty’ => false)” in the attributes
parameter. It will also pre-select the fields with the current datetime.
FormHelper::year(string $fieldName, 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>
FormHelper::month(string $fieldName, 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.):
General Purpose 425](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-431-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
echo $this->Form->month(’mob’, array(’monthNames’ => false));
FormHelper::day(string $fieldName, 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 first option is ‘Day’), you can
supply the text as the final 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 $fieldName, boolean $format24Hours, array $attributes)
Creates a select element populated with the hours of the day.
FormHelper::minute(string $fieldName, array $attributes)
Creates a select element populated with the minutes of the hour.
FormHelper::meridian(string $fieldName, array $attributes)
Creates a select element populated with ‘am’ and ‘pm’.
Displaying and checking errors
FormHelper::error(string $fieldName, mixed $text, array $options)
Shows a validation error message, specified by $text, for the given field, 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 class name for the error message
FormHelper::isFieldError(string $fieldName)
Returns true if the supplied $fieldName 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.
426 Chapter 9. Core Libraries](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-432-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
FormHelper::tagIsInvalid()
Returns false if given form field described by the current entity has no errors. Otherwise it returns the
validation message.
Setting Defaults for all fields 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’
// has a label element same defaults
echo $this->Form->input(
’username’,
array(’label’ => ’Username’)
);
Working with SecurityComponent SecurityComponent offers several features that make your
forms safer and more secure. By simply including the SecurityComponent in your controller, you’ll
automatically benefit 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 field making it exempt from the SecurityComponent field hashing. This also allows
the fields to be manipulated by JavaScript. The $name parameter should be the entity name for the
input:
$this->Form->unlockField(’User.id’);
FormHelper::secure(array $fields = array())
Generates a hidden field with a security hash based on the fields 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
simplifies the FormHelper methods, reducing the number of arguments, and reduces the duplication that
$selected created. The effected methods are:
• FormHelper::select()
General Purpose 427](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-433-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
• 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 pa-
rameters. You can override this default by supplying $options[’url’] in the second parameter of
$this->Form->create()
FormHelper::hidden()
Hidden fields no longer remove the class attribute. This means that if there are validation errors on hidden
fields, the error-field class name will be applied.
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 flexible 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 you’re getting an error informing you that
it isn’t there, it’s usually due to its name being missing from a manually configured $helpers controller
variable.
Inserting Well-Formatted elements The most important task the HtmlHelper accomplishes is creating
well formed markup. Don’t 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
428 Chapter 9. Core Libraries](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-434-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
’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.
HtmlHelper::media(string|array $path, array $options)
Parameters
• $path (string|array) – Path to the video file, relative to the web-
root/{$options[’pathPrefix’]} directory. Or an array where each item itself can
be a path string or an associate array containing keys src and type.
General Purpose 435](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-441-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
• $options (array) – An array of html attributes.
Returns text wrapped in a specified tag. If no text is specified 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 class name 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 first parameter specifies 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 specified, 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 class name for the paragraph.
• $text (string) – The content inside the paragraph.
• $options (array) – An array of html attributes.
General Purpose 437](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-443-320.jpg)
![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 file, or an array of strings for
multiple files.
• $options (array) – An array of html attributes.
Include a script file(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 file inclusion assumes that the JavaScript file specified 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 files with absolute paths as well to link files 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 first parameter can be an array to include multiple files.:
438 Chapter 9. Core Libraries](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-444-320.jpg)
![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 specific 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 files 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 file 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 defined 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:
General Purpose 439](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-445-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
place $this->Js->writeBuffer() at the bottom of your layout file 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 files.
JsHelper::writeBuffer($options = array())
Writes all JavaScript generated so far to a code block or caches them to a file 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 file 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 file 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
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.
General Purpose 449](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-455-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
’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,
stop:onStop
});
JsHelper::request($url, $options = array())
Generate a JavaScript snippet to create an XmlHttpRequest or ‘AJAX’ request.
Event Options
•complete - Callback to fire on complete.
•success - Callback to fire on success.
•before - Callback to fire on request initialization.
•error - Callback to fire 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 eval’ed.
•dataExpression - Should the data key be treated as a callback. Useful for supplying
$options[’data’] as another JavaScript expression.
Example use:
$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
General Purpose 451](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-457-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
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 fired when the drag starts
•drag - Event fired on every step of the drag
•stop - Event fired 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
$("#element").draggable({
containment:"#content",
drag:onDrag,
grid:[10,10],
start:onStart,
stop:onStop
});
JsHelper::drop($options = array())
Make an element accept draggable elements and act as a dropzone for dragged elements.
Options
452 Chapter 9. Core Libraries](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-458-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
• update The CSS selector of the element to update with the results of AJAX pagination calls. If not
specified, 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 being paginated, defaults to
PaginatorHelper::defaultModel().
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 configuration 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’)
));
Configuring the PaginatorHelper to use a JavaScript helper By default the PaginatorHelper uses
JsHelper to do AJAX features. However, if you don’t 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 It’s 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 doesn’t always need to be restricted as such.
See the details on PaginatorHelper6 in the API. As mentioned, the PaginatorHelper also offers sorting fea-
tures which can be easily integrated into your table column headers:
// app/View/Posts/index.ctp
<table>
<tr>
<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>
6
http://api.cakephp.org/2.4/class-PaginatorHelper.html
472 Chapter 9. Core Libraries](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-478-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
<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 field.
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 final 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}’
));
General Purpose 473](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-479-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
Other Methods
PaginatorHelper::link($title, $url = array(), $options = array())
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 Would create a link pointing at
‘/posts/index/page:5/sort:title/direction:desc’
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
474 Chapter 9. Core Libraries](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-480-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
[order] =>
[limit] => 20
[options] => Array
(
[page] => 2
[conditions] => Array
(
)
)
[paramType] => named
)
*/
PaginatorHelper::param(string $key, string $model = null)
Gets the specific 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 we’ve 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, first we need to edit the controller to add in the rss-specific
code.
Controller Code It is a good idea to add RequestHandler to your PostsController’s $components array.
This will allow a lot of automagic to occur:
public $components = array(’RequestHandler’);
Our view will also use the TextHelper for formatting, so that should be added to the controller as well:
General Purpose 475](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-481-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
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 DESC’)
);
return $this->set(compact(’posts’));
}
// this is not an Rss request, so deliver
// data used by website’s 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, put the following contents in
app/View/Layouts/rss/default.ctp:
if (!isset($documentData)) {
$documentData = array();
}
if (!isset($channelData)) {
$channelData = array();
}
if (!isset($channelData[’title’])) {
$channelData[’title’] = $this->fetch(’title’);
}
$channel = $this->Rss->channel(array(), $channelData, $this->fetch(’content’));
echo $this->Rss->document($documentData, $channel);
It doesn’t look like much but thanks to the power in the RssHelper it’s doing a lot of lifting for us. We
haven’t set $documentData or $channelData in the controller, however in CakePHP your views can
476 Chapter 9. Core Libraries](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-482-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
pass variables back to the layout. Which is where our $channelData array will come from setting all of
the meta data for our feed.
Next up is view file for my posts/index. Much like the layout file we created, we need to create a
View/Posts/rss/ directory and create a new index.ctp inside that folder. The contents of the file
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 Con-
troller::set() method. Here though we are passing the channel’s 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 ar-
ray 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,
));
General Purpose 477](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-483-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
echo $this->Rss->item(array(), array(
’title’ => $post[’Post’][’title’],
’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 filter 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 configuration 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 field
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.
478 Chapter 9. Core Libraries](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-484-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
You can also pass additional parameters into the flash() method, which allows 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 escape the HTML in flash messages. If you are using any
request or user data in your flash messages, you should escape it with h when formatting your mes-
sages.
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 gracefully truncating long stretches of text.
Changed in version 2.1: Several TextHelper methods have been moved into the String class to allow
easier use outside of the View layer. Within a view, these methods are accessible via the TextHelper class.
You can call one 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 defined in
$htmlOptions (see HtmlHelper::link()).:
$myText = ’For more information regarding our world-famous ’ .
’pastries and desserts, contact info@example.com’;
$linkedText = $this->Text->autoLinkEmails($myText);
Output:
For more information regarding our world-famous pastries and desserts,
contact <a href="mailto:info@example.com">info@example.com</a>
Changed in version 2.1: In 2.1 this method automatically escapes its input. Use the escape option
to disable this if necessary.
General Purpose 481](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-487-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
Highlights $needle in $haystack using the $options[’format’] string specified or a de-
fault 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="highlight">1</span>’)
);
// called as String
App::uses(’String’, ’Utility’);
echo String::highlight(
$lastSentence,
’using’,
array(’format’ => ’<span class="highlight">1</span>’)
);
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, in characters, beyond which the text should be trun-
cated.
• $options (array) – An array of options to use.
If $text is longer than $length characters, this method truncates it at $length and adds a prefix
consisting of ’ellipsis’, if defined. If ’exact’ is passed as false, the truncation will occur
at the first whitespace after the point at which $length is exceeded. 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,
General Purpose 483](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-489-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
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’.:
// 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 user’s 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. Un-
comment the line date_default_timezone_set(’UTC’); in app/Config/core.php to en-
sure your application’s time zone is set to GMT+0.
Next add a time zone field to your users table and make the necessary modifications 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 h:i A’,
$post[’Post’][’created’],
null,
486 Chapter 9. Core Libraries](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-492-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
$user[’User’][’time_zone’]
);
// Will display August 22nd, 2011 11:53 PM for a user in GMT+0
// August 22nd, 2011 03:53 PM for a user in GMT-8
// and August 23rd, 2011 09:53 AM GMT+10
Most of the Time Helper methods have a $timezone parameter. The $timezone parameter accepts a valid
timezone identifier string or an instance of DateTimeZone class.
Formatting
TimeHelper::convert($serverTime, $timezone = NULL)
Return type integer
Converts given time (in server’s time zone) to user’s 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, $field_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, $fieldName, $timezone = NULL)
General Purpose 487](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-493-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
/*
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 server’s timezone.
TimeHelper::timezone($timezone = NULL)
Return type DateTimeZone
New in version 2.2: Returns a timezone object from a string or the user’s timezone object. If the
function is called without a parameter it tries to get timezone from ‘Config.timezone’ configuration
variable.
TimeHelper::listTimezones($filter = null, $country = null, $group = true)
Return type array
492 Chapter 9. Core Libraries](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-498-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
You can also add helpers from within an action, so they will only be available to that action and not to the
other actions in the controller. This saves processing power for the other actions that do not use the helper
and helps 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 it 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(
’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
494 Chapter 9. Core Libraries](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-500-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
}
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 configure your helpers and keep configuration logic out
of your controller actions. If you have configuration options that cannot be included as part of a class
declaration, you can set those in your controller’s beforeRender callback:
class PostsController extends AppController {
public function beforeRender() {
parent::beforeRender();
$this->helpers[’CustomStuff’] = $this->_getCustomStuffSettings();
}
}
Using Helpers Once you’ve configured 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 view’s 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 pro-
cess. See the Helper API and the Collections documentation for more information.
Creating Helpers If a core helper (or one showcased on GitHub or in the Bakery) doesn’t fit your needs,
helpers are easy to create.
Let’s say we wanted to create a helper that could be used to output a specifically crafted CSS-styled link you
needed many different places in your application. In order to fit your logic into CakePHP’s existing helper
structure, you’ll need to create a new class in /app/View/Helper. Let’s call our helper LinkHelper. The
actual PHP class file 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...
General Purpose 495](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-501-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
}
$data = $this->data;
if (empty($this->data)) {
$data = $this->read();
}
if (!$data[’User’][’group_id’]) {
return null;
} else {
return array(’Group’ => array(’id’ => $data[’User’][’group_id’]));
}
}
In the above example the return is an array that looks similar to the results of a model find. It is important
to have the id value set or the parentNode relation will fail. The AclBehavior uses this data to construct its
tree structure.
node()
The AclBehavior also allows you to retrieve the Acl node associated with a model record. After setting
$model->id. You can use $model->node() to retrieve the associated Acl node.
You can also retrieve the Acl Node for any row, by passing in a data array:
$this->User->id = 1;
$node = $this->User->node();
$user = array(’User’ => array(
’id’ => 1
));
$node = $this->User->node($user);
Will both return the same Acl Node information.
If you had setup AclBehavior to create both ACO and ARO nodes, you need to specify which node type you
want:
$this->User->id = 1;
$node = $this->User->node(null, ’Aro’);
$user = array(’User’ => array(
’id’ => 1
));
$node = $this->User->node($user, ’Aro’);
Containable
class ContainableBehavior
A new addition to the CakePHP 1.2 core is the ContainableBehavior. This model behavior allows
you to filter and limit model find operations. Using Containable will help you cut down on needless wear
502 Chapter 9. Core Libraries](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-508-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
and tear on your database, increasing the speed and overall performance of your application. The class will
also help you search and filter your data for your users in a clean and consistent way.
Containable allows you to streamline and simplify operations on your model bindings. It works by temporar-
ily or permanently altering the associations of your models. It does this by using supplied the containments
to generate a series of bindModel and unbindModel calls. Since Containable only modifies existing
relationships it will not allow you to restrict results by distant associations. Instead you should refer to
Joining tables.
To use the new behavior, you can add it to the $actsAs property of your model:
class Post extends AppModel {
public $actsAs = array(’Containable’);
}
You can also attach the behavior on the fly:
$this->Post->Behaviors->load(’Containable’);
Using Containable
To see how Containable works, let’s look at a few examples. First, we’ll start off with a find() call on a
model named ‘Post’. Let’s say that ‘Post’ hasMany ‘Comment’, and ‘Post’ hasAndBelongsToMany ‘Tag’.
The amount of data fetched in a normal find() call is rather extensive:
debug($this->Post->find(’all’));
[0] => Array
(
[Post] => Array
(
[id] => 1
[title] => First article
[content] => aaa
[created] => 2008-05-18 00:00:00
)
[Comment] => Array
(
[0] => Array
(
[id] => 1
[post_id] => 1
[author] => Daniel
[email] => dan@example.com
[website] => http://example.com
[comment] => First comment
[created] => 2008-05-18 00:00:00
)
[1] => Array
(
[id] => 2
[post_id] => 1
Behaviors 503](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-509-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
[author] => Sam
[email] => sam@example.net
[website] => http://example.net
[comment] => Second comment
[created] => 2008-05-18 00:00:00
)
)
[Tag] => Array
(
[0] => Array
(
[id] => 1
[name] => Awesome
)
[1] => Array
(
[id] => 2
[name] => Baking
)
)
)
[1] => Array
(
[Post] => Array
(...
For some interfaces in your application, you may not need that much information from the Post model. One
thing the ContainableBehavior does is help you cut down on what find() returns.
For example, to get only the post-related information, you can do the following:
$this->Post->contain();
$this->Post->find(’all’);
You can also invoke Containable’s magic from inside the find() call:
$this->Post->find(’all’, array(’contain’ => false));
Having done that, you end up with something a lot more concise:
[0] => Array
(
[Post] => Array
(
[id] => 1
[title] => First article
[content] => aaa
[created] => 2008-05-18 00:00:00
)
)
[1] => Array
(
[Post] => Array
(
504 Chapter 9. Core Libraries](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-510-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
[id] => 2
[title] => Second article
[content] => bbb
[created] => 2008-05-19 00:00:00
)
)
This sort of help isn’t new: in fact, you can do that without the ContainableBehavior doing something
like this:
$this->Post->recursive = -1;
$this->Post->find(’all’);
Containable really shines when you have complex associations, and you want to pare down things that sit
at the same level. The model’s $recursive property is helpful if you want to hack off an entire level of
recursion, but not when you want to pick and choose what to keep at each level. Let’s see how it works by
using the contain() method.
The contain method’s first argument accepts the name, or an array of names, of the models to keep in the
find operation. If we wanted to fetch all posts and their related tags (without any comment information),
we’d try something like this:
$this->Post->contain(’Tag’);
$this->Post->find(’all’);
Again, we can use the contain key inside a find() call:
$this->Post->find(’all’, array(’contain’ => ’Tag’));
Without Containable, you’d end up needing to use the unbindModel() method of the model, multiple
times if you’re paring off multiple models. Containable creates a cleaner way to accomplish this same task.
Containing deeper associations
Containable also goes a step deeper: you can filter the data of the associated models. If you look at the
results of the original find() call, notice the author field in the Comment model. If you are interested in
the posts and the names of the comment authors — and nothing else — you could do something like the
following:
$this->Post->contain(’Comment.author’);
$this->Post->find(’all’);
// or..
$this->Post->find(’all’, array(’contain’ => ’Comment.author’));
Here, we’ve told Containable to give us our post information, and just the author field of the associated
Comment model. The output of the find call might look something like this:
[0] => Array
(
[Post] => Array
Behaviors 505](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-511-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
(
[id] => 1
[title] => First article
[content] => aaa
[created] => 2008-05-18 00:00:00
)
[Comment] => Array
(
[0] => Array
(
[author] => Daniel
[post_id] => 1
)
[1] => Array
(
[author] => Sam
[post_id] => 1
)
)
)
[1] => Array
(...
As you can see, the Comment arrays only contain the author field (plus the post_id which is needed by
CakePHP to map the results).
You can also filter the associated Comment data by specifying a condition:
$this->Post->contain(’Comment.author = "Daniel"’);
$this->Post->find(’all’);
//or...
$this->Post->find(’all’, array(’contain’ => ’Comment.author = "Daniel"’));
This gives us a result that gives us posts with comments authored by Daniel:
[0] => Array
(
[Post] => Array
(
[id] => 1
[title] => First article
[content] => aaa
[created] => 2008-05-18 00:00:00
)
[Comment] => Array
(
[0] => Array
(
[id] => 1
[post_id] => 1
[author] => Daniel
[email] => dan@example.com
506 Chapter 9. Core Libraries](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-512-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
[website] => http://example.com
[comment] => First comment
[created] => 2008-05-18 00:00:00
)
)
)
There is an important caveat to using Containable when filtering on a deeper association. In the previous
example, assume you had 3 posts in your database and Daniel had commented on 2 of those posts. The
operation $this->Post->find(‘all’, array(‘contain’ => ‘Comment.author = “Daniel”’)); would return ALL
3 posts, not just the 2 posts that Daniel had commented on. It won’t return all comments however, just
comments by Daniel.:
[0] => Array
(
[Post] => Array
(
[id] => 1
[title] => First article
[content] => aaa
[created] => 2008-05-18 00:00:00
)
[Comment] => Array
(
[0] => Array
(
[id] => 1
[post_id] => 1
[author] => Daniel
[email] => dan@example.com
[website] => http://example.com
[comment] => First comment
[created] => 2008-05-18 00:00:00
)
)
)
[1] => Array
(
[Post] => Array
(
[id] => 2
[title] => Second article
[content] => bbb
[created] => 2008-05-18 00:00:00
)
[Comment] => Array
(
)
)
[2] => Array
(
[Post] => Array
(
Behaviors 507](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-513-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
[id] => 3
[title] => Third article
[content] => ccc
[created] => 2008-05-18 00:00:00
)
[Comment] => Array
(
[0] => Array
(
[id] => 22
[post_id] => 3
[author] => Daniel
[email] => dan@example.com
[website] => http://example.com
[comment] => Another comment
[created] => 2008-05-18 00:00:00
)
)
)
If you want to filter the posts by the comments, so that posts without a comment by Daniel won’t be returned,
the easiest way is to find all the comments by Daniel and contain the Posts.:
$this->Comment->find(’all’, array(
’conditions’ => ’Comment.author = "Daniel"’,
’contain’ => ’Post’
));
Additional filtering can be performed by supplying the standard find options:
$this->Post->find(’all’, array(’contain’ => array(
’Comment’ => array(
’conditions’ => array(’Comment.author =’ => "Daniel"),
’order’ => ’Comment.created DESC’
)
)));
Here’s an example of using the ContainableBehavior when you’ve got deep and complex model
relationships.
Let’s consider the following model associations:
User->Profile
User->Account->AccountSummary
User->Post->PostAttachment->PostAttachmentHistory->HistoryNotes
User->Post->Tag
This is how we retrieve the above associations with Containable:
$this->User->find(’all’, array(
’contain’ => array(
’Profile’,
’Account’ => array(
’AccountSummary’
508 Chapter 9. Core Libraries](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-514-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
)
));
You can change ContainableBehavior settings at run time by reattaching the behavior as seen in Behaviors
(Using Behaviors).
ContainableBehavior can sometimes cause issues with other behaviors or queries that use aggregate func-
tions and/or GROUP BY statements. If you get invalid SQL errors due to mixing of aggregate and non-
aggregate fields, try disabling the autoFields setting.:
$this->Post->Behaviors->load(’Containable’, array(’autoFields’ => false));
Using Containable with pagination By including the ‘contain’ parameter in the $paginate property
it will apply to both the find(‘count’) and the find(‘all’) done on the model.
See the section Using Containable for further details.
Here’s an example of how to contain associations when paginating:
$this->paginate[’User’] = array(
’contain’ => array(’Profile’, ’Account’),
’order’ => ’User.username’
);
$users = $this->paginate(’User’);
Note: If you contained the associations through the model instead, it will not honor Containable’s recursive
option. So if you set recursive to -1 for example for the model, it won’t work:
$this->User->recursive = -1;
$this->User->contain(array(’Profile’, ’Account’));
$users = $this->paginate(’User’);
Translate
class TranslateBehavior
TranslateBehavior is actually quite easy to setup and works out of the box with very little configuration. In
this section, you will learn how to add and setup the behavior to use in any model.
If you are using TranslateBehavior in alongside containable issue, be sure to set the ‘fields’ key for your
queries. Otherwise you could end up with invalid SQL generated.
Initializing the i18n Database Tables
You can either use the CakePHP console or you can manually create it. It is advised to use the console for
this, because it might happen that the layout changes in future versions of CakePHP. Sticking to the console
will make sure that you have the correct layout.:
510 Chapter 9. Core Libraries](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-516-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
./cake i18n
Select [I] which will run the i18n database initialization script. You will be asked if you want to drop any
existing and if you want to create it. Answer with yes if you are sure there is no i18n table already, and
answer with yes again to create the table.
Attaching the Translate Behavior to your Models
Add it to your model by using the $actsAs property like in the following example.:
class Post extends AppModel {
public $actsAs = array(
’Translate’
);
}
This will do nothing yet, because it expects a couple of options before it begins to work. You need to define
which fields of the current model should be tracked in the translation table we’ve created in the first step.
Defining the Fields
You can set the fields by simply extending the ’Translate’ value with another array, like so:
class Post extends AppModel {
public $actsAs = array(
’Translate’ => array(
’fieldOne’, ’fieldTwo’, ’and_so_on’
)
);
}
After you have done that (for example putting “title” as one of the fields) you already finished the basic
setup. Great! According to our current example the model should now look something like this:
class Post extends AppModel {
public $actsAs = array(
’Translate’ => array(
’title’
)
);
}
When defining fields for TranslateBehavior to translate, be sure to omit those fields from the translated
model’s schema. If you leave the fields in, there can be issues when retrieving data with fallback locales.
Note: If all the fields in your model are translated be sure to add created and modified columns to
your table. CakePHP requires at least one non primary key field before it will save a record.
Behaviors 511](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-517-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
Conclusion
From now on each record update/creation will cause TranslateBehavior to copy the value of “title” to the
translation table (default: i18n) along with the current locale. A locale is the identifier of the language, so to
speak.
Reading translated content
By default the TranslateBehavior will automatically fetch and add in data based on the current locale.
The current locale is read from Configure::read(’Config.language’) which is assigned by
the L10n class. You can override this default on the fly using $Model->locale.
Retrieve translated fields in a specific locale By setting $Model->locale you can read translations
for a specific locale:
// Read the spanish locale data.
$this->Post->locale = ’es’;
$results = $this->Post->find(’first’, array(
’conditions’ => array(’Post.id’ => $id)
));
// $results will contain the spanish translation.
Retrieve all translation records for a field If you want to have all translation records attached to the
current model record you simply extend the field array in your behavior setup as shown below. The naming
is completely up to you.:
class Post extends AppModel {
public $actsAs = array(
’Translate’ => array(
’title’ => ’titleTranslation’
)
);
}
With this setup the result of $this->Post->find() should look something like this:
Array
(
[Post] => Array
(
[id] => 1
[title] => Beispiel Eintrag
[body] => lorem ipsum...
[locale] => de_de
)
[titleTranslation] => Array
(
[0] => Array
512 Chapter 9. Core Libraries](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-518-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
(
[id] => 1
[locale] => en_us
[model] => Post
[foreign_key] => 1
[field] => title
[content] => Example entry
)
[1] => Array
(
[id] => 2
[locale] => de_de
[model] => Post
[foreign_key] => 1
[field] => title
[content] => Beispiel Eintrag
)
)
)
Note: The model record contains a virtual field called “locale”. It indicates which locale is used in this
result.
Note that only fields of the model you are directly doing ‘find‘ on will be translated. Models attached via as-
sociations won’t be translated because triggering callbacks on associated models is currently not supported.
Using the bindTranslation method You can also retrieve all translations, only when you need them, using
the bindTranslation method
TranslateBehavior::bindTranslation($fields, $reset)
$fields is a named-key array of field and association name, where the key is the translatable field and the
value is the fake association name.:
$this->Post->bindTranslation(array(’title’ => ’titleTranslation’));
// need at least recursive 1 for this to work.
$this->Post->find(’all’, array(’recursive’ => 1));
With this setup the result of your find() should look something like this:
Array
(
[Post] => Array
(
[id] => 1
[title] => Beispiel Eintrag
[body] => lorem ipsum...
[locale] => de_de
)
Behaviors 513](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-519-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
[titleTranslation] => Array
(
[0] => Array
(
[id] => 1
[locale] => en_us
[model] => Post
[foreign_key] => 1
[field] => title
[content] => Example entry
)
[1] => Array
(
[id] => 2
[locale] => de_de
[model] => Post
[foreign_key] => 1
[field] => title
[content] => Beispiel Eintrag
)
)
)
Saving in another language
You can force the model which is using the TranslateBehavior to save in a language other than the one
detected.
To tell a model in what language the content is going to be you simply change the value of the $locale
property on the model before you save the data to the database. You can do that either in your controller or
you can define it directly in the model.
Example A: In your controller:
class PostsController extends AppController {
public function add() {
if (!empty($this->request->data)) {
// we are going to save the german version
$this->Post->locale = ’de_de’;
$this->Post->create();
if ($this->Post->save($this->request->data)) {
return $this->redirect(array(’action’ => ’index’));
}
}
}
}
Example B: In your model:
514 Chapter 9. Core Libraries](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-520-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
}
We can check what our category tree data looks like by visiting /categories You should see something like
this:
• My Categories
– Fun
* Sport
· Surfing
· Extreme knitting
* Friends
· Gerald
· Gwendolyn
– Work
* Reports
· Annual
· Status
* Trips
· National
· International
Adding data In the previous section, we used existing data and checked that it looked hierarchal via the
method generateTreeList. However, usually you would add your data in exactly the same way as you
would for any model. For example:
// pseudo controller code
$data[’Category’][’parent_id’] = 3;
$data[’Category’][’name’] = ’Skating’;
$this->Category->save($data);
When using the tree behavior it’s not necessary to do any more than set the parent_id, and the tree behavior
will take care of the rest. If you don’t set the parent_id, the tree behavior will add to the tree making your
new addition a new top level entry:
// pseudo controller code
$data = array();
$data[’Category’][’name’] = ’Other People’s Categories’;
$this->Category->save($data);
Running the above two code snippets would alter your tree as follows:
• My Categories
Behaviors 519](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-525-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
• $recursive – The number of levels deep to fetch associated records
This method will return data similar to find(‘list’) but with a nested prefix that is specified in the
spacer option to show the structure of your data. Below is an example of what you can expect this
method to return:
$treelist = $this->Category->generateTreeList();
Output:
array(
[1] => "My Categories",
[2] => "_Fun",
[3] => "__Sport",
[4] => "___Surfing",
[16] => "___Skating",
[6] => "__Friends",
[7] => "___Gerald",
[8] => "___Gwendolyn",
[9] => "_Work",
[13] => "__Trips",
[14] => "___National",
[15] => "___International",
[17] => "Other People’s Categories",
[5] => "_Extreme fishing"
)
getParentNode()
This convenience function will, as the name suggests, return the parent node for any node, or false if
the node has no parent (it’s the root node). For example:
$parent = $this->Category->getParentNode(2); //<- id for fun
// $parent contains All categories
getPath($id = null, $fields = null, $recursive = null)
The ‘path’ when referring to hierarchal data is how you get from where you are to the top. So for
example the path from the category “International” is:
•My Categories
•...
•Work
–Trips
*...
*International
Using the id of “International” getPath will return each of the parents in turn (starting from the top).:
524 Chapter 9. Core Libraries](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-530-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
$parents = $this->Category->getPath(15);
// contents of $parents
array(
[0] => array(
’Category’ => array(’id’ => 1, ’name’ => ’My Categories’, ..)
),
[1] => array(
’Category’ => array(’id’ => 9, ’name’ => ’Work’, ..)
),
[2] => array(
’Category’ => array(’id’ => 13, ’name’ => ’Trips’, ..)
),
[3] => array(
’Category’ => array(’id’ => 15, ’name’ => ’International’, ..)
),
)
Advanced Usage
The tree behavior doesn’t only work in the background, there are a number of specific meth-
ods defined in the behavior to cater for all your hierarchical data needs, and any unexpected
problems that might arise in the process.
TreeBehavior::moveDown()
Used to move a single node down the tree. You need to provide the ID of the element to be
moved and a positive number of how many positions the node should be moved down. All
child nodes for the specified node will also be moved.
Here is an example of a controller action (in a controller named Categories) that moves a spec-
ified node down the tree:
public function movedown($id = null, $delta = null) {
$this->Category->id = $id;
if (!$this->Category->exists()) {
throw new NotFoundException(__(’Invalid category’));
}
if ($delta > 0) {
$this->Category->moveDown($this->Category->id, abs($delta));
} else {
$this->Session->setFlash(
’Please provide the number of positions the field should be’ .
’moved down.’
);
}
return $this->redirect(array(’action’ => ’index’));
}
Behaviors 525](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-531-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
$options is used to pass all extra parameters, and has the following possible keys by default,
all of which are optional:
array(
’id’ => null,
’field’ => $model->displayField,
’order’ => ’ASC’,
’verify’ => true
)
TreeBehavior::verify()
Returns true if the tree is valid otherwise an array of errors, with fields for type, incorrect
index and message.
Each record in the output array is an array of the form (type, id, message)
• type is either ’index’ or ’node’
• ’id’ is the id of the erroneous node.
• ’message’ depends on the error
Example Use:
$this->Category->verify();
Example output:
Array
(
[0] => Array
(
[0] => node
[1] => 3
[2] => left and right values identical
)
[1] => Array
(
[0] => node
[1] => 2
[2] => The parent node 999 doesn ’ t exist
)
[10] => Array
(
[0] => index
[1] => 123
[2] => missing
)
[99] => Array
(
[0] => node
[1] => 163
[2] => left greater than right
)
Behaviors 529](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-535-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
);
}
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’),
’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 find 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 defining general pagination values, you can define more than one set of pagination defaults in
the controller, you just name the keys of the array after the model you wish to configure:
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 defined, we can use the PaginatorComponent‘s
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 infor-
mation is set to $this->request->params[’paging’], and is used by PaginatorHelper for
creating links. PaginatorComponent::paginate() also adds PaginatorHelper to the list of
Components 531](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-537-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
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 querys-
tring 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. You can also modify the
$settings property on the PaginatorComponent:
$this->Paginator->settings[’paramType’] = ’querystring’;
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 modification of overloaded property $paginate has no effect.” Assign-
ing an initial value to the property solves the issue:
$this->paginate = array();
$this->paginate[’limit’] = 10;
//or
$this->paginate = array(’limit’ => 10);
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:
Components 535](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-541-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
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
It’s 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.
Sessions can be configured in a number of ways in CakePHP. For more information, you should see the
Session configuration 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. So
User.username would reference the following:
array(’User’ => array(
’username’ => ’clark-kent@dailyplanet.com’
));
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:
536 Chapter 9. Core Libraries](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-542-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
’authenticate’ => array(
’Form’ => array(
’fields’ => array(’username’ => ’email’)
)
)
)
);
Do not put other Auth configuration 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 config-
uration 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 configuration, Basic authentication supports the following keys:
• realm The realm being authenticated. Defaults to env(’SERVER_NAME’).
In addition to the common configuration 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 be returned unchanged by clients. Defaults to
md5($settings[’realm’])
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 difficult at times. For 2.0, you’ll
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’)) {
Components 541](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-547-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
Authentication objects should return false if they cannot identify the user. And an array of user infor-
mation if they can. It’s 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 authen-
tication object needs to support stateless or cookie-less authentication. See the sections on basic and digest
authentication below for more information.
Using custom authentication objects Once you’ve 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 don’t rely on cookies. A typical getUser method looks at
the request/environment and uses the information there to confirm the identity of the user. HTTP Basic au-
thentication for example uses $_SERVER[’PHP_AUTH_USER’] and $_SERVER[’PHP_AUTH_PW’]
for the username and password fields. On each request, these values are used to re-identify the user and
ensure they are valid user. As with authentication object’s 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 identifies a user based on a username and
password.
Handling unauthenticated requests When an unauthenticated user tries to access a protected page first
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 neces-
sary. 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 it’s an AJAX request and
AuthComponent::$ajaxLogin is specified 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.
Components 543](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-549-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
)
)
)
);
When creating new user records you can hash a password in the beforeSave callback of your model using
appropriate password hasher class:
App::uses(’SimplePasswordHasher’, ’Controller/Component/Auth’);
class User extends AppModel {
public function beforeSave($options = array()) {
if (!empty($this->data[$this->alias][’password’])) {
$passwordHasher = new SimplePasswordHasher(array(’hashType’ => ’sha256’));
$this->data[$this->alias][’password’] = $passwordHasher->hash(
$this->data[$this->alias][’password’]
);
}
return true;
}
}
You don’t 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 bcrypt10 a.k.a Blowfish 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 blowfish 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 defined 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, it’s also recommended that you
store the digest password in a separate column, from the normal password hash:
10
https://en.wikipedia.org/wiki/Bcrypt
Components 545](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-551-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
class User extends AppModel {
public function beforeSave($options = array()) {
// make a password for digest auth.
$this->data[$this->alias][’digest_hash’] = DigestAuthenticate::password(
$this->data[$this->alias][’username’],
$this->data[$this->alias][’password’],
env(’SERVER_NAME’)
);
return true;
}
}
Passwords for digest authentication need a bit more information than other password hashes, based on the
RFC for digest authentication.
Note: The third parameter of DigestAuthenticate::password() must match the ‘realm’ config value
defined when DigestAuthentication was configured 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 fol-
lowing:
App::uses(’AbstractPasswordHasher’, ’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’ => $id)
);
$this->Auth->login($this->request->data[’User’]);
546 Chapter 9. Core Libraries](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-552-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
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 don’t want to create a custom authorize object.
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 prefix.
Using ActionsAuthorize ActionsAuthorize integrates with the AclComponent, and provides a fine
grained per action ACL check on each request. ActionsAuthorize is often paired with DbAcl to give dynamic
and flexible 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.
550 Chapter 9. Core Libraries](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-556-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
property AuthComponent::$flash
Settings to use when Auth needs to do a flash 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 (defined as a string or array) to the controller action that handles logins. Defaults to
/users/login
property AuthComponent::$loginRedirect
The URL (defined 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 han-
dle post-logout redirection, a redirect URL will be returned from AuthComponent::logout().
Defaults to AuthComponent::$loginAction.
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 unspecified, 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 specified actions. The special value of ’*’ will mark all the current controllers actions as
public. Best used in your controller’s beforeFilter method.
AuthComponent::constructAuthenticate()
Loads the configured authentication objects.
AuthComponent::constructAuthorize()
Loads the authorization objects configured.
AuthComponent::deny($action[, $action, ...])
Toggle one or more actions previously declared as public actions, as non-public methods. These
methods will now require authorization. Best used inside your controller’s beforeFilter method.
AuthComponent::flash($message)
Set a flash message. Uses the Session component, and values from AuthComponent::$flash.
552 Chapter 9. Core Libraries](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-558-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
Component, or with FormHelper::unlockField(). Fields that have been unlocked are not
required to be part of the POST and hidden unlocked fields do not have their values checked.
property SecurityComponent::$validatePost
Set to false to completely skip the validation of POST requests, essentially turning off form valida-
tion.
CSRF configuration
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 single use. 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 controllers beforeFilter(). You would specify
the security restrictions you want and the Security Component will enforce them on its startup:
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();
}
}
}
Components 557](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-563-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
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 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 SecurityComponent 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 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 benefit 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 controller’s beforeFilter:
public function beforeFilter() {
$this->Security->csrfExpires = ’+1 hour’;
// ...
}
The csrfExpires property can be any value that is compatible with strtotime()12. By default the
12
http://php.net/manual/en/function.strtotime.php
558 Chapter 9. Core Libraries](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-564-320.jpg)
![CakePHP Cookbook Documentation, Release 2.x
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 SecurityComponent blackHoleCallback will be called with a ‘csrf’ parameter.
This helps you filter 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, the request 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 protec-
tion 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 ar-
ray. By default CSRF protection is enabled, and configured to use one-use tokens.
Disabling CSRF and Post Data Validation For Specific Actions
There may be cases where you want to disable all security checks for an action (ex. AJAX re-
quests). You may “unlock” these actions by listing them in $this->Security->unlockedActions
in your beforeFilter. The unlockedActions property will not effect other features of
SecurityComponent.
New in version 2.3.
Request Handling
class RequestHandlerComponent(ComponentCollection $collection, array $settings = ar-
ray())
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 file extensions are enabled.
Components 559](https://image.slidesharecdn.com/cakephpcookbook-150520023606-lva1-app6892/85/Cake-php-cookbook-565-320.jpg)
Cake php cookbook
- 1. CakePHP Cookbook Documentation Release2.x Cake Software Foundation November 12, 2014
- 3. Contents 1 Getting Started1 2 Blog Tutorial 3 Getting CakePHP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 Creating the Blog Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 CakePHP Database Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Optional Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 A Note on mod_rewrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 3 Blog Tutorial - Adding a layer 13 Create a Post Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Create a Posts Controller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Creating Post Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Adding Posts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Data Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Editing Posts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Deleting Posts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Routes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Additional Reading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 4 Installation 33 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Downloading CakePHP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 Production . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 Advanced Installation and URL Rewriting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 i
- 4. Fire It Up. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 5 CakePHP Overview 45 What is CakePHP? Why use it? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 Understanding Model-View-Controller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 Where to Get Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 6 Controllers 51 The App Controller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Request parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Controller actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Request Life-cycle callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Controller Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 Controller Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 More on controllers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 7 Views 85 View Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Using view blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 Layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 Creating your own view classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 View API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 More about Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 8 Models 205 Understanding Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 More on models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207 9 Core Libraries 339 General Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339 Behaviors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500 Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530 Helpers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 581 Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 678 10 Plugins 793 How To Install Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 793 How To Use Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 795 How To Create Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 797 11 Console and Shells 803 The CakePHP console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 803 Creating a shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 805 Shell tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 806 Invoking other shells from your shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 808 Console output levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 808 Styling output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 808 Configuring options and generating help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 810 ii
- 5. Routing in shells/ CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 817 Shell API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 817 More topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 820 12 Development 837 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 837 Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 851 Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 869 Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 875 Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 882 Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 884 Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 887 REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 912 Dispatcher Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 915 13 Deployment 921 Check your security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 921 Set document root . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 921 Update core.php . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 921 Improve your application’s performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 922 14 Tutorials & Examples 923 Blog Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 923 Blog Tutorial - Adding a layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 931 Simple Authentication and Authorization Application . . . . . . . . . . . . . . . . . . . . . . . . 943 Simple Acl controlled Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 950 Simple Acl controlled Application - part 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 957 15 Appendices 961 2.5 Migration Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 961 2.4 Migration Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 966 2.3 Migration Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 972 2.2 Migration Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 979 2.1 Migration Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 985 2.0 Migration Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 996 Migration from 1.2 to 1.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1030 General Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1050 16 Indices and tables 1053 Index 1055 iii
- 6.
- 7. CHAPTER 1 Getting Started TheCakePHP framework provides a robust base for your application. It can handle every aspect, from the user’s initial request all the way to the final 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 filenames to database table names, keep- ing your entire application consistent and logical. This concept is simple but powerful. Follow the conven- tions and you’ll always know exactly where things are and how they’re organized. The best way to experience and learn CakePHP is to sit down and build something. To start off we’ll build a simple blog application. 1
- 8. CakePHP Cookbook Documentation,Release 2.x 2 Chapter 1. Getting Started
- 9. CHAPTER 2 Blog Tutorial Welcometo CakePHP. You’re probably checking out this tutorial because you want to learn more about how CakePHP works. It’s our aim to increase productivity and make coding more enjoyable: we hope you’ll see this as you dive into the code. This tutorial will walk you through the creation of a simple blog application. We’ll be getting and installing CakePHP, creating and configuring a database, and creating enough application logic to list, add, edit, and delete blog posts. Here’s what you’ll need: 1. A running web server. We’re going to assume you’re using Apache, though the instructions for using other servers should be very similar. We might have to play a little with the server configuration, but most folks can get CakePHP up and running without any configuration at all. Make sure you have PHP 5.2.8 or greater. 2. A database server. We’re going to be using MySQL server in this tutorial. You’ll need to know enough about SQL in order to create a database: CakePHP will be taking the reins from there. Since we’re using MySQL, also make sure that you have pdo_mysql enabled in PHP. 3. Basic PHP knowledge. The more object-oriented programming you’ve done, the better: but fear not if you’re a procedural fan. 4. Finally, you’ll need a basic knowledge of the MVC programming pattern. A quick overview can be found in Understanding Model-View-Controller. Don’t worry, it’s only half a page or so. Let’s get started! Getting CakePHP First, let’s get a copy of fresh CakePHP 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 3
- 10. CakePHP Cookbook Documentation,Release 2.x You can also clone the repository using git1. git clone git://github.com/cakephp/cakephp.git Regardless of how you downloaded it, place the code inside of your DocumentRoot. Once finished, 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 CakePHP’s directory structure works: check out the CakePHP Folder Structure section. Tmp directory permissions Next we’ll need to make the app/tmp directory writable by the webserver. The best way to do this is to find out what user your webserver runs as. You can run <?php echo exec(’whoami’); ?> inside any PHP file your webserver can execute. You should see a username printed. Change the ownership of the app/tmp directory to that user. The final command you run (in *nix) might look something like this: $ chown -R www-data app/tmp If for some reason CakePHP can’t write to that directory, you’ll see warnings and uncaught exceptions that cache data cannot be written. Creating the Blog Database Next, let’s set up the underlying database for our blog. If you haven’t already done so, create an empty database for use in this tutorial, with a name of your choice. Right now, we’ll just create a single table to store our posts. We’ll 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()); 1 http://git-scm.com/ 4 Chapter 2. Blog Tutorial
- 11. CakePHP Cookbook Documentation,Release 2.x INSERT INTO posts (title,body,created) VALUES (’A title once again’, ’And the post body follows.’, NOW()); 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 CakePHP’s database naming con- ventions, and CakePHP’s class naming conventions (both outlined in CakePHP Conventions), you’ll be able to take advantage of a lot of free functionality and avoid configuration. CakePHP is flexible 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 suffice it to say that naming our table ‘posts’ automatically hooks it to our Post model, and having fields called ‘modified’ and ‘created’ will be automag- ically managed by CakePHP. CakePHP Database Configuration Onward and upward: let’s tell CakePHP where our database is and how to connect to it. For many, this is the first and last time you configure anything. A copy of CakePHP’s database configuration file is found in /app/Config/database.php.default. Make a copy of this file in the same directory, but name it database.php. The config file should be pretty straightforward: just replace the values in the $default array with those that apply to your setup. A sample completed configuration 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 you’ve saved your new database.php file, you should be able to open your browser and see the CakePHP welcome page. It should also tell you that your database connection file was found, and that CakePHP can successfully connect to the database. Note: Remember that you’ll need to have PDO, and pdo_mysql enabled in your php.ini. CakePHP Database Configuration 5
- 12. CakePHP Cookbook Documentation,Release 2.x Optional Configuration There are a few other items that can be configured. Most developers complete these laundry-list items, but they’re not required for this tutorial. One is defining a custom string (or “salt”) for use in security hashes. The second is defining a custom number (or “seed”) for use in encryption. The security salt is used for generating hashes. Change the default Security.salt value in /app/Config/core.php. The replacement value should be long, hard to guess and be as random as you can make it: /** * 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 Security.cipherSeed value by editing /app/Config/core.php. The replacement value should be a large random integer: /** * A random numeric string (digits only) used to encrypt/decrypt strings. */ Configure::write(’Security.cipherSeed’, ’7485712659625147843639846751’); A Note on mod_rewrite Occasionally new users 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 is not 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 box–and usually does–we’ve 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-specific httpd.conf.) These files can vary between different distributions and Apache versions. You may also take a look at http://wiki.apache.org/httpd/DistrosDefaultLayout for further information. 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). # 6 Chapter 2. Blog Tutorial
- 13. 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 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 default, so you may just need to remove the leading # symbols. After you make changes, restart Apache to make sure the settings are active. Verify that your .htaccess files are actually in the right directories. Some operating systems treat files that start with ‘.’ as hidden and therefore won’t copy them. 3. Make sure your copy of CakePHP comes from the downloads section of the site or our Git repository, and has been unpacked correctly, by checking for .htaccess files. CakePHP root directory (must be copied to your document; redirects everything to your CakePHP app): <IfModule mod_rewrite.c> RewriteEngine on RewriteRule ^ $ app/webroot/ [L] RewriteRule (.*) app/webroot/ $ 1 [L] </IfModule> CakePHP app directory (will be copied to the top directory of your application by bake): <IfModule mod_rewrite.c> RewriteEngine on RewriteRule ^ $ webroot/ [L] RewriteRule (.*) webroot/ $ 1 [L] </IfModule> CakePHP webroot directory (will be copied to your application’s web root by bake): <IfModule mod_rewrite.c> RewriteEngine On RewriteCond %{REQUEST_FILENAME} !-d RewriteCond %{REQUEST_FILENAME} !-f RewriteRule ^(.*) $ index.php [QSA,L] </IfModule> If your CakePHP site still has problems with mod_rewrite, you might want to try modifying settings for Virtual Hosts. On Ubuntu, edit the file /etc/apache2/sites-available/default (location is distribution- dependent). In this file, ensure that AllowOverride None is changed to AllowOverride A Note on mod_rewrite 7
- 14. CakePHP Cookbook Documentation,Release 2.x 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> On Mac OSX, another solution is to use the tool virtualhostx2 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 direc- tory (http://example.com/~username/cakephp/), or any other URL structure that already utilizes mod_rewrite, you’ll need to add RewriteBase statements to the .htaccess files CakePHP uses (/.htac- cess, /app/.htaccess, /app/webroot/.htaccess). This can be added to the same section with the RewriteEngine directive, so for example, your webroot .htaccess file 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 related to CakePHP. Please refer to Apache’s 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 webserver’s 404 page. Additionally you can create a matching HTML 404 page, or use the default built-in CakePHP 404 by adding an ErrorDocument directive: 2 http://clickontyler.com/virtualhostx/ 8 Chapter 2. Blog Tutorial
- 15. CakePHP Cookbook Documentation,Release 2.x ErrorDocument 404 /404-not-found Pretty URLs on nginx nginx does not make use of .htaccess files like Apache, so it is necessary to create those rewritten URLs in the site-available configuration. 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?$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 files. While there are add-ons that can add this support, you can also import htaccess rules into IIS to use CakePHP’s native rewrites. To do this, follow these steps: 1. Use Microsoft’s Web Platform Installer3 to install the URL Rewrite Module 2.04 or download it directly (32-bit5 / 64-bit6). 3 http://www.microsoft.com/web/downloads/platform.aspx 4 http://www.iis.net/downloads/microsoft/url-rewrite 5 http://www.microsoft.com/en-us/download/details.aspx?id=5747 6 http://www.microsoft.com/en-us/download/details.aspx?id=7435 A Note on mod_rewrite 9
- 16. CakePHP Cookbook Documentation,Release 2.x 2. Create a new file called web.config in your CakePHP root folder. 3. Using Notepad or any XML-safe editor, copy the following code into your new web.config file... <?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)" stopProcessing="true"> <match url="^(img|css|files|js|favicon.ico)(.*)$" /> <action type="Rewrite" url="app/webroot/{R:1}{R:2}" appendQueryString="false" /> </rule> <rule name="Rewrite requested file/folder to index.php" stopProcessing="true"> <match url="^(.*)$" ignoreCase="false" /> <action type="Rewrite" url="index.php" appendQueryString="true" /> </rule> </rules> </rewrite> </system.webServer> </configuration> Once the web.config file is created with the correct IIS-friendly rewrite rules, CakePHP’s links, CSS, JavaS- cipt, and rerouting should work correctly. URL-Rewriting on lighttpd Lighttpd does not support .htaccess functions, so you can remove all .htaccess files. In the lighttpd configu- ration, make sure you’ve activated “mod_rewrite”. Add a line: url.rewrite-if-not-file =( "^([^?]*)(?(.+))?$" => "/index.php?url=$1&$3" ) URL rewrite rules for Hiawatha The required UrlToolkit rule (for URL rewriting) to use CakePHP with Hiawatha is: 10 Chapter 2. Blog Tutorial
- 17. CakePHP Cookbook Documentation,Release 2.x UrlToolkit { ToolkitID = cakephp RequestURI exists Return Match .* Rewrite /index.php } I don’t / can’t use URL rewriting If you don’t want to or can’t use URL rewriting on your webserver, refer to the core configuration. Now continue to Blog Tutorial - Adding a layer to start building your first CakePHP application. A Note on mod_rewrite 11
- 18. CakePHP Cookbook Documentation,Release 2.x 12 Chapter 2. Blog Tutorial
- 19. CHAPTER 3 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, we’ll have the foundation in place needed to do our view, add, edit, and delete operations later. CakePHP’s model class files go in /app/Model, and the file we’ll be creating will be saved to /app/Model/Post.php. The completed file should look like this: class Post extends AppModel { } Naming conventions are very important in CakePHP. By naming our model Post, CakePHP can automat- ically 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 find a corresponding file in /app/Model. This also means that if you accidentally name your file wrong (for example, post.php or posts.php instead of Post.php), CakePHP will not recognize any of your settings and will use the defaults instead. For more on models, such as table prefixes, callbacks, and validation, check out the Models chapter of the Manual. Create a Posts Controller Next, we’ll create a controller for our posts. The controller is where all the business logic for post interaction will happen. In a nutshell, it’s the place where you play with the models and get post-related work done. We’ll place this new controller in a file called PostsController.php inside the /app/Controller directory. Here’s what the basic controller should look like: 13
- 20. CakePHP Cookbook Documentation,Release 2.x class PostsController extends AppController { public $helpers = array(’Html’, ’Form’); } Now, let’s 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 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 defining function index() in our PostsController, users can access the logic there by requesting www.example.com/posts/index. Similarly, if we were to define 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 (capitalization, plural 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 we’ll 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 we’ve followed CakePHP’s naming conventions. To learn more about CakePHP’s controllers, check out the Controllers chapter. Creating Post Views Now that we have our data flowing to our model, and our application logic and flow defined by our controller, let’s create a view for the index action we created above. CakePHP views are just presentation-flavored fragments that fit inside an application’s layout. For most applications, they’re HTML mixed with PHP, but they may end up as XML, CSV, or even binary data. A layout is presentation code that is wrapped around a view. Multiple layouts can be defined, and you can switch between them, but for now, let’s just use the default. Remember how in the last section we assigned the ‘posts’ variable to the view using the set() method? That would pass data to the view that would look something like this: // print_r($posts) output: Array 14 Chapter 3. Blog Tutorial - Adding a layer
- 21. CakePHP Cookbook Documentation,Release 2.x ( [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] => ) ) ) CakePHP’s view files are stored in /app/View inside a folder named after the controller to which they correspond. (We’ll have to create a folder named ‘Posts’ in this case.) To format this post data into a nice table, our view code might look something like this <!-- File: /app/View/Posts/index.ctp --> <h1>Blog posts</h1> <table> <tr> <th>Id</th> <th>Title</th> <th>Created</th> </tr> <!-- Here is where we loop through our $posts array, printing out post info --> <?php foreach ($posts as $post): ?> Creating Post Views 15
- 22. CakePHP Cookbook Documentation,Release 2.x <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> 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 what’s important to note here is that the link() method will generate an HTML link with the given title (the first parameter) and URL (the second parameter). When specifying URLs in CakePHP, 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 CakePHP’s 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 (which link a post’s title to a URL /posts/view/some_id), you were probably informed by CakePHP that the action hadn’t yet been defined. If you were not so informed, either something has gone wrong, or you actually did define it already, in which case you are very sneaky. Otherwise, we’ll create it in the PostsController now: // File: /app/Controller/PostsController.php 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 we’re using findById() rather than find(’all’) be- 16 Chapter 3. Blog Tutorial - Adding a layer
- 23. CakePHP Cookbook Documentation,Release 2.x cause we only want a single post’s information. Notice that our view action takes a parameter: the ID of the post we’d 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 that 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 let’s create the view for our new ‘view’ action and place it in /app/View/Posts/view.ctp <!-- File: /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 let’s allow for adding new posts. First, start by creating an add() action in the PostsController: 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)) { Adding Posts 17
- 24. CakePHP Cookbook Documentation,Release 2.x $this->Session->setFlash(__(’Your post has been saved.’)); return $this->redirect(array(’action’ => ’index’)); } $this->Session->setFlash(__(’Unable to add your post.’)); } } } Note: $this->request->is() takes a single argument, which can be the request METHOD (get, put, post, delete) or some request identifier (ajax). It is not a way to check for specific posted data. For instance, $this->request->is(’book’) will not return true if book data was posted. Note: You need to include the SessionComponent - and SessionHelper - in any controller where you will use it. If necessary, include it in your AppController. Here’s what the add() action does: if the HTTP method of the request was POST, it tries to save the data using the Post model. If for some reason it doesn’t save, it just renders 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 flow 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 SessionComponent’s 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- able. The controller’s Controller::redirect function redirects to another URL. The param array(’action’ => ’index’) translates to URL /posts (that is, the index action of the posts con- troller). You can refer to Router::url() function on the API1 to see the formats in which you can specify a URL for various CakePHP functions. Calling the save() method will check for validation errors and abort the save if any occur. We’ll discuss how those errors are handled in the following sections. We call the create() method first in order to reset the model state for saving new information. It does not actually create a record in the database, but clears Model::$id and sets Model::$data based on your database field defaults. Data Validation CakePHP goes a long way toward taking the monotony out of form input validation. Everyone hates coding up endless forms and their validation routines. CakePHP makes it easier and faster. 1 http://api.cakephp.org 18 Chapter 3. Blog Tutorial - Adding a layer
- 25. CakePHP Cookbook Documentation,Release 2.x To take advantage of the validation features, you’ll need to use CakePHP’s FormHelper in your views. The FormHelper is available by default to all views at $this->Form. Here’s our add view: <!-- File: /app/View/Posts/add.ctp --> <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’); ?> We use the FormHelper to generate the opening tag for an HTML form. Here’s 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 via POST to the current controller’s add() action (or edit() action when id is included in the form data). The $this->Form->input() method is used to create form elements of the same name. The first parameter tells CakePHP which field 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. There’s a bit of introspection and automagic here: input() will output different form elements based on the model field specified. The $this->Form->end() call generates a submit button and ends the form. If a string is supplied as the first 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 let’s 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’) ); ?> You may be wondering: how do I tell CakePHP about my validation requirements? Validation rules are defined in the model. Let’s 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’ ) ); } Data Validation 19
- 26. CakePHP Cookbook Documentation,Release 2.x The $validate array tells CakePHP how to validate your data when the save() method is called. Here, I’ve specified that both the body and title fields must not be empty. CakePHP’s validation engine is strong, with a number of pre-built rules (credit card numbers, email addresses, etc.) and flexibility for adding your own validation rules. For more information, 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 we’ve 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. You’re a CakePHP pro by now, so you should have picked up a pattern. Make the action, then the view. Here’s 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(array(’post’, ’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; } } This action first ensures that the user has tried to access an existing record. If they haven’t 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 whether the request is either a POST or a PUT 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: <!-- File: /app/View/Posts/edit.ctp --> <h1>Edit Post</h1> 20 Chapter 3. Blog Tutorial - Adding a layer
- 27. CakePHP Cookbook Documentation,Release 2.x <?php echo $this->Form->create(’Post’); echo $this->Form->input(’title’); echo $this->Form->input(’body’, array(’rows’ => ’3’)); echo $this->Form->input(’id’, array(’type’ => ’hidden’)); echo $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’ field is present in the data array. If no ‘id’ is present (look back at our add view), CakePHP will assume that you are inserting a new model when save() is called. You can now update your index view with links to edit specific posts: <!-- File: /app/View/Posts/index.ctp (edit links added) --> <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> <!-- Here’s where we loop through our $posts array, printing out post info --> <?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’, $post[’Post’][’id’]) ); ?> </td> <td> <?php echo $this->Html->link( ’Edit’, array(’action’ => ’edit’, $post[’Post’][’id’]) ); ?> </td> <td> <?php echo $post[’Post’][’created’]; ?> </td> </tr> Editing Posts 21
- 28. CakePHP Cookbook Documentation,Release 2.x <?php endforeach; ?> </table> Deleting Posts Next, let’s 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 specified by $id, and uses $this->Session->setFlash() to show the user a confirmation 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 CakePHP’s 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 we’re 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: <!-- File: /app/View/Posts/index.ctp --> <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> <!-- Here’s where we loop through our $posts array, printing out post info --> <?php foreach ($posts as $post): ?> <tr> <td><?php echo $post[’Post’][’id’]; ?></td> <td> <?php echo $this->Html->link( $post[’Post’][’title’], 22 Chapter 3. Blog Tutorial - Adding a layer
- 29. CakePHP Cookbook Documentation,Release 2.x array(’action’ => ’view’, $post[’Post’][’id’]) ); ?> </td> <td> <?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’][’id’]) ); ?> </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 to delete our post. Al- lowing 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 confirmation dialog before they attempt to delete a post. Routes For some, CakePHP’s default routing works well enough. Developers who are sensitive to user-friendliness and general search engine compatibility will appreciate the way that CakePHP’s URLs map to specific actions. So we’ll just make a quick change to routes in this tutorial. For more information on advanced routing techniques, see Routes Configuration. By default, CakePHP responds to a request for the root of your site (e.g., http://www.example.com) using its PagesController, rendering a view called “home”. Instead, we’ll replace this with our PostsController by creating a routing rule. CakePHP’s routing is found in /app/Config/routes.php. You’ll want to comment out or remove the line that defines the default root route. It looks like this: Router::connect( ’/’, Routes 23
- 30. CakePHP Cookbook Documentation,Release 2.x 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 defined, you pass array(’controller’ => ’posts’, ’action’ => ’index’) to a function expecting an ar- ray, the resulting URL used will be ‘/’. It’s therefore a good idea to always use arrays for URLs, as this means your routes define where a URL goes, and also ensures that links point to the same place. Conclusion Creating applications this way will win you peace, honor, love, and money beyond even your wildest fan- tasies. Simple, isn’t it? Keep in mind that this tutorial was very basic. CakePHP has many more features to offer, and is flexible in ways we didn’t wish to cover here for simplicity’s sake. Use the rest of this manual as a guide for building more feature-rich applications. Now that you’ve created a basic CakePHP application, you’re ready for the real thing. Start your own project and read the rest of the Cookbook and API2. 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 2 http://api.cakephp.org 24 Chapter 3. Blog Tutorial - Adding a layer
- 31. CakePHP Cookbook Documentation,Release 2.x Additional Reading A Typical CakePHP Request We’ve covered the basic ingredients in CakePHP, so let’s look at how objects work together to complete a basic request. Continuing with our original request example, let’s imagine that our friend Ricardo just clicked on the “Buy A Custom Cake Now!” link on a CakePHP application’s landing page. Figure 3.1: Flow diagram showing a typical CakePHP request Figure: 2. Typical CakePHP 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 re- quest 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 specific controller class). In this case, it’s the buy() method of the CakesController. The controller’s beforeFilter() callback is called before any controller action logic is executed. 4. The controller may use models to gain access to the application’s data. In this example, the controller uses a model to fetch Ricardo’s last purchases from the database. Any applicable model callbacks, Additional Reading 25
- 32. CakePHP Cookbook Documentation,Release 2.x 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 refine 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 sufficiently, that data is handed to the view using the controller’s 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 a layout. 8. Additional controller callbacks (like afterFilter) may be applied. The complete, rendered view code is sent to Ricardo’s browser. CakePHP Conventions We are big fans of convention over configuration. While it takes a bit of time to learn CakePHP’s con- ventions, you save time in the long run: by following convention, you get free functionality, and you free yourself from the maintenance nightmare of tracking config files. Convention also makes for a very uniform system development, allowing other developers to jump in and help more easily. CakePHP’s conventions have been distilled from 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 class names are plural, CamelCased, and end in Controller. PeopleController and LatestArticlesController are both examples of conventional controller names. The first method you write for a controller might be the index() method. When a request specifies 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 prefixing controller method names with underscores. If a controller method has been prefixed 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() { // Logic to find latest news articles 26 Chapter 3. Blog Tutorial - Adding a layer
- 33. CakePHP Cookbook Documentation,Release 2.x } } 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/_findNewArticles/ would get an error, because the method is preceded with an underscore. You can also use PHP’s 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 you’ve just seen, single word controllers map easily to a simple lower case URL path. For example, ApplesController (which would be defined in the file name ‘ApplesController.php’) is accessed from http://example.com/apples. Multiple word controllers can be any ‘inflected’ 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 Configuration. If you have files/directories in your /webroot directory that share a name with one of your routes/controllers, you will be directed to the file/directory and, not to your controller. File and Class Name Conventions In general, filenames match the class names, which are CamelCased. So if you have a class MyNiftyClass, then in CakePHP, the file should be named MyNiftyClass.php. Below are examples of how to name the file 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 file named KissesAnd- HugsController.php • The Component class MyHandyComponent would be found in a file named MyHandyCompo- nent.php • The Model class OptionValue would be found in a file named OptionValue.php • The Behavior class EspeciallyFunkableBehavior would be found in a file named EspeciallyFunk- ableBehavior.php • The View class SuperSimpleView would be found in a file named SuperSimpleView.php • The Helper class BestEverHelper would be found in a file named BestEverHelper.php Additional Reading 27
- 34. CakePHP Cookbook Documentation,Release 2.x Each file would be located in the appropriate folder in your app folder. Model and Database Conventions Model class names 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 Inflector for more information. Field names with two or more words are underscored: first_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 table like category_types whose name contains multiple words, 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, arranged 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 that does not already have a single-field primary key, CakePHP’s convention is that a single-field primary key is added to the table. You must add a single-field primary key if you want to use that table’s 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. For example: 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). CakePHP 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 files 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 configuration. Here’s a final example that ties the conventions together: • Database table: “people” • Model class: “Person”, found at /app/Model/Person.php 28 Chapter 3. Blog Tutorial - Adding a layer
- 35. CakePHP Cookbook Documentation,Release 2.x • Controller class: “PeopleController”, found at /app/Controller/PeopleController.php • 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 automati- cally tied to the ‘people’ table in the database), and renders to a file. None of these relationships have been configured by any means other than by creating classes and files that you’d need to create anyway. Now that you’ve been introduced to CakePHP’s fundamentals, you might try a run through the Blog Tutorial to see how things fit together. CakePHP Folder Structure After you’ve downloaded and extracted CakePHP, these are the files and folders you should see: • app • lib • vendors • plugins • .htaccess • index.php • README You’ll notice three main folders: • The app folder will be where you work your magic: it’s where your application’s files will be placed. • The lib folder is where we’ve worked our magic. Make a personal commitment not to edit files in this folder. We can’t help you if you’ve modified the core. Instead, look into modifying Application Extensions. • Finally, the vendors folder is where you’ll place third-party PHP libraries you need to use with your CakePHP applications. The App Folder CakePHP’s app folder is where you will do most of your application development. Let’s look a little closer at the folders inside app. Config Holds the (few) configuration files CakePHP uses. Database connection details, bootstrapping, core configuration files 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 application’s controllers and their components. Additional Reading 29
- 36. CakePHP Cookbook Documentation,Release 2.x Lib Contains libraries that do not come from 3rd parties or external vendors. This allows you to separate your organization’s internal libraries from vendor libraries. Locale Stores string files for internationalization. Model Contains your application’s models, behaviors, and datasources. Plugin Contains plugin packages. Test This directory contains all the test cases and test fixtures for your application. The Test/Case direc- tory should mirror your application and contain one or more test cases per class in your application. For more information on test cases and test fixtures, refer to the Testing documentation. tmp This is where CakePHP stores temporary data. The actual data it stores depends on how you have CakePHP configured, but this folder is usually used to store model descriptions, logs, and sometimes session information. Make sure that this folder exists and is writable, or the performance of your application will be severely impacted. In debug mode, CakePHP will warn you if the folder is absent or not writable. 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. We’ll get into the differences between the two when we discuss managing multiple applications and more complex system setups. View Presentational files are placed here: elements, error pages, helpers, layouts, and view files. 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 files. 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 we’ll 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 define application- wide changes. AppController (located at /app/Controller/AppController.php), Ap- pHelper (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 routes aren’t classes or files, they play a role in requests made to CakePHP. Route defini- tions 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. 30 Chapter 3. Blog Tutorial - Adding a layer
- 37. CakePHP Cookbook Documentation,Release 2.x Some features in an application merit packaging as a whole. A plugin is a package of models, controllers and views that accomplishes a specific purpose that can span multiple applications. A user management system or a simplified blog might be a good fit for CakePHP plugins. 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 fit. 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 fitted with callbacks. These callbacks are available for your use, just in case you need to insert some logic between CakePHP’s core operations. Callbacks available include: • afterFilter(), executed after all controller logic, including the rendering of the view • beforeFilter(), executed before any controller action logic • beforeRender(), executed after controller logic, but before the view is rendered 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 are also 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 files, 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 with many iCal events. Like controllers, models have callbacks: • beforeFind() • afterFind() • beforeValidate() • afterValidate() • beforeSave() • afterSave() • beforeDelete() • afterDelete() The names of these methods should be descriptive enough to let you know what they do. You can find the details in the models chapter. Additional Reading 31
- 38. 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 pre- sentational 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. Ele- ments are used when small snippets of content need to be reused in multiple views. 32 Chapter 3. Blog Tutorial - Adding a layer
- 39. CHAPTER 4 Installation CakePHP isfast and easy to install. The minimum requirements are a webserver and a copy of CakePHP, that’s it! While this manual focuses primarily on setting up on Apache (because it’s the most commonly used), you can configure CakePHP 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 isn’t 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: All built-in drivers require PDO. You should make sure you have the correct PDO extensions in- stalled. 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. 33
- 40. 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 archived 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” link. All current releases of CakePHP are hosted on GitHub1. GitHub houses both CakePHP itself as well as many other plugins for CakePHP. The CakePHP releases are available at GitHub tags2. Alternatively you can get fresh off the press code, with all the bug-fixes and up to the minute enhancements. These can be accessed from GitHub by cloning the GitHub3 repository: git clone git://github.com/cakephp/cakephp.git Permissions CakePHP uses the app/tmp directory for a number of different operations. A few examples would be Model descriptions, cached views and session information. As such, make sure the directory app/tmp and all its subdirectories in your CakePHP installation are writable by the web server user. One common issue is that the app/tmp directories and subdirectories must be writable both by the web server and the command line user. On a UNIX system, if your web server user is different from your command line user, you can run the following commands just once in your project to ensure that permissions will be setup properly: HTTPDUSER=‘ps aux | grep -E ’[a]pache|[h]ttpd|[_]www|[w]ww-data|[n]ginx’ | grep -v root | h setfacl -R -m u: $ {HTTPDUSER}:rwx app/tmp setfacl -R -d -m u: $ {HTTPDUSER}:rwx app/tmp Setup Setting up CakePHP can be as simple as slapping it in your web server’s document root, or as complex and flexible 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 configure the web server’s document root, clean URLs, very se- cure. 1 http://github.com/cakephp/cakephp 2 https://github.com/cakephp/cakephp/tags 3 http://github.com/cakephp/cakephp 34 Chapter 4. Installation
- 41. CakePHP Cookbook Documentation,Release 2.x • Advanced: With some configuration, allows you to place key CakePHP directories in different parts of the filesystem, possibly sharing a single CakePHP core library folder amongst many CakePHP applications. Development A development installation is the fastest method to setup CakePHP. 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. Unpack the contents of the CakePHP archive into /var/www/html. You now have a folder in your doc- ument root named after the release you’ve downloaded (e.g. cake_2.0.0). Rename this folder to cake_2_0. Your development setup will look like this on the file system: /var/www/html/ cake_2_0/ app/ lib/ plugins/ vendors/ .htaccess index.php README If your web server is configured correctly, you should now find your CakePHP 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 PHP’s include_path. To start off, clone CakePHP into a directory. For this example, we’ll 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 don’t want to use git, you can download a zipball and the remaining steps will be the same. Next you’ll 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 Configuration File’, you can find the actual location. Once you’ve found the correct ini file, modify the include_path configuration 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 reflected in phpinfo(). Note: If you are on windows, separate include paths with ; instead of : Development 35
- 42. CakePHP Cookbook Documentation,Release 2.x Having finished setting up your include_path your applications should be able to find CakePHP auto- matically. Production A production installation is a more flexible way to setup CakePHP. Using this method allows an entire domain to act as a single CakePHP application. This example will help you install CakePHP anywhere on your filesystem and make it available at http://www.example.com. Note that this installation may require the rights to change the DocumentRoot on Apache webservers. Unpack the contents of the CakePHP archive into a directory of your choice. For the purposes of this example, we assume you chose to install CakePHP into /cake_install. Your production setup will look like this on the filesystem: /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 If your web server is configured correctly, you should now find your CakePHP application accessible at http://www.example.com. 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 you’ll 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. 36 Chapter 4. Installation
- 43. CakePHP Cookbook Documentation,Release 2.x After installing CakePHP with PEAR, if PEAR is configured correctly you should be able to use the cake command to create a new application. Since CakePHP will be located on PHP’s include_path you won’t 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 simplifies managing multiple versions of libraries. Since CakePHP publishes a PEAR package you can install CakePHP using composer4. Before installing CakePHP you’ll need to setup a composer.json file. A composer.json file for a CakePHP application would look like the following: { "name": "example-app", "require": { "cakephp/cakephp": "2.5.*" }, "config": { "vendor-dir": "Vendor/" } } Save this JSON into composer.json in the APP directory of your project. Next download the com- poser.phar file into your project. After you’ve downloaded Composer, install CakePHP. In the same directory as your composer.json run the following: $ php composer.phar install Once Composer has finished running you should have a directory structure that looks like: example-app/ composer.phar composer.json Vendor/ bin/ autoload.php composer/ cakephp/ 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 . DS . ’Vendor’ . DS . ’cakephp’ . DS . ’cakephp’ . DS . ’lib’ ); 4 http://getcomposer.org Advanced Installation and URL Rewriting 37
- 44. CakePHP Cookbook Documentation,Release 2.x Note: If you are planning to create unit tests for your application you’ll also need to make the above change to webroot/test.php If you’re installing any other libraries with Composer, you’ll need to setup the autoloader, and work around an issue in Composer’s autoloader. In your Config/bootstrap.php file add the following: // Load Composer autoload. require APP . ’Vendor/autoload.php’; // Remove and re-prepend CakePHP’s autoloader as Composer thinks it is the // most important. // See: http://goo.gl/kKVJO7 spl_autoload_unregister(array(’App’, ’load’)); spl_autoload_register(array(’App’, ’load’), true, true); You should now have a functioning CakePHP application installed via Composer. Be sure to keep the composer.json and composer.lock file with the rest of your source code. Sharing CakePHP Libraries with multiple Applications There may be some situations where you wish to place CakePHP’s directories on different places on the filesystem. This may be due to a shared host restriction, or maybe you just want a few of your apps to share the same CakePHP libraries. This section describes how to spread your CakePHP directories across a filesystem. First, realize that there are three main parts to a CakePHP application: 1. The core CakePHP libraries, in /lib/Cake. 2. Your application code, in /app. 3. The application’s webroot, usually in /app/webroot. Each of these directories can be located anywhere on your file 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 CakePHP where you’ve put it. To configure your CakePHP installation, you’ll need to make some changes to the following files. • /app/webroot/index.php • /app/webroot/test.php (if you use the Testing feature.) There are three constants that you’ll 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. Let’s 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: 38 Chapter 4. Installation
- 45. CakePHP Cookbook Documentation,Release 2.x • The CakePHP core libraries will be placed in /usr/lib/cake. • My application’s webroot directory will be /var/www/mysite/. • My application’s app directory will be /home/me/myapp. Given this type of setup, I would need to edit my webroot/index.php file (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’); } 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 file paths. This prevents any missing file 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 box–and usually does–we’ve 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-specific httpd.conf.) These files can vary between different distributions and Apache versions. You may also take a look at http://wiki.apache.org/httpd/DistrosDefaultLayout for further information. 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. Advanced Installation and URL Rewriting 39
- 46. CakePHP Cookbook Documentation,Release 2.x # <Directory /> Options FollowSymLinks AllowOverride All # Order deny,allow # Deny from all </Directory> 2. Make sure you are loading 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 default, so you may just need to remove the leading # symbols. After you make changes, restart Apache to make sure the settings are active. Verify that your .htaccess files are actually in the right directories. Some operating systems treat files that start with ‘.’ as hidden and therefore won’t copy them. 3. Make sure your copy of CakePHP comes from the downloads section of the site or our Git repository, and has been unpacked correctly, by checking for .htaccess files. CakePHP root directory (must be copied to your document; redirects everything to your CakePHP app): <IfModule mod_rewrite.c> RewriteEngine on RewriteRule ^ $ app/webroot/ [L] RewriteRule (.*) app/webroot/ $ 1 [L] </IfModule> CakePHP app directory (will be copied to the top directory of your application by bake): <IfModule mod_rewrite.c> RewriteEngine on RewriteRule ^ $ webroot/ [L] RewriteRule (.*) webroot/ $ 1 [L] </IfModule> CakePHP webroot directory (will be copied to your application’s web root by bake): <IfModule mod_rewrite.c> RewriteEngine On RewriteCond %{REQUEST_FILENAME} !-d RewriteCond %{REQUEST_FILENAME} !-f RewriteRule ^(.*) $ index.php [QSA,L] </IfModule> If your CakePHP site still has problems with mod_rewrite, you might want to try modifying settings for Virtual Hosts. On Ubuntu, edit the file /etc/apache2/sites-available/default (location is distribution- dependent). In this file, ensure that AllowOverride None is changed to AllowOverride All, so you have: 40 Chapter 4. Installation
- 47. CakePHP Cookbook Documentation,Release 2.x <Directory /> Options FollowSymLinks AllowOverride All </Directory> <Directory /var/www> Options Indexes FollowSymLinks MultiViews AllowOverride All Order Allow,Deny Allow from all </Directory> On Mac OSX, another solution is to use the tool virtualhostx5 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 direc- tory (http://example.com/~username/cakephp/), or any other URL structure that already utilizes mod_rewrite, you’ll need to add RewriteBase statements to the .htaccess files CakePHP uses (/.htac- cess, /app/.htaccess, /app/webroot/.htaccess). This can be added to the same section with the RewriteEngine directive, so for example, your webroot .htaccess file 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 related to CakePHP. Please refer to Apache’s 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 webserver’s 404 page. Additionally you can create a matching HTML 404 page, or use the default built-in CakePHP 404 by adding an ErrorDocument directive: 5 http://clickontyler.com/virtualhostx/ Advanced Installation and URL Rewriting 41
- 48. CakePHP Cookbook Documentation,Release 2.x ErrorDocument 404 /404-not-found Pretty URLs on nginx nginx does not make use of .htaccess files like Apache, so it is necessary to create those rewritten URLs in the site-available configuration. 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?$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 files. While there are add-ons that can add this support, you can also import htaccess rules into IIS to use CakePHP’s native rewrites. To do this, follow these steps: 1. Use Microsoft’s Web Platform Installer6 to install the URL Rewrite Module 2.07 or download it directly (32-bit8 / 64-bit9). 6 http://www.microsoft.com/web/downloads/platform.aspx 7 http://www.iis.net/downloads/microsoft/url-rewrite 8 http://www.microsoft.com/en-us/download/details.aspx?id=5747 9 http://www.microsoft.com/en-us/download/details.aspx?id=7435 42 Chapter 4. Installation
- 49. CakePHP Cookbook Documentation,Release 2.x 2. Create a new file called web.config in your CakePHP root folder. 3. Using Notepad or any XML-safe editor, copy the following code into your new web.config file... <?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)" stopProcessing="true"> <match url="^(img|css|files|js|favicon.ico)(.*)$" /> <action type="Rewrite" url="app/webroot/{R:1}{R:2}" appendQueryString="false" /> </rule> <rule name="Rewrite requested file/folder to index.php" stopProcessing="true"> <match url="^(.*)$" ignoreCase="false" /> <action type="Rewrite" url="index.php" appendQueryString="true" /> </rule> </rules> </rewrite> </system.webServer> </configuration> Once the web.config file is created with the correct IIS-friendly rewrite rules, CakePHP’s links, CSS, JavaS- cipt, and rerouting should work correctly. URL-Rewriting on lighttpd Lighttpd does not support .htaccess functions, so you can remove all .htaccess files. In the lighttpd configu- ration, make sure you’ve activated “mod_rewrite”. Add a line: url.rewrite-if-not-file =( "^([^?]*)(?(.+))?$" => "/index.php?url=$1&$3" ) URL rewrite rules for Hiawatha The required UrlToolkit rule (for URL rewriting) to use CakePHP with Hiawatha is: Advanced Installation and URL Rewriting 43
- 50. CakePHP Cookbook Documentation,Release 2.x UrlToolkit { ToolkitID = cakephp RequestURI exists Return Match .* Rewrite /index.php } I don’t / can’t use URL rewriting If you don’t want to or can’t use URL rewriting on your webserver, refer to the core configuration. Fire It Up Alright, let’s see CakePHP in action. Depending on which setup you used, you should point your browser to http://example.com/ or http://www.example.com/cake_2_0/. At this point, you’ll be presented with CakePHP’s default home, and a message that tells you the status of your current database connection. Congratulations! You are ready to create your first CakePHP application. Not working? If you’re getting timezone related errors 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’); 44 Chapter 4. Installation
- 51. CHAPTER 5 CakePHP Overview Welcometo 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 object- oriented programming (OOP). Different functionality within the framework makes use of different technolo- gies – 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? CakePHP1 is a free2, open-source3, rapid development4 framework5 for PHP6. It’s a foundational structure for programmers to create web applications. Our primary goal is to enable you to work in a structured and rapid manner–without loss of flexibility. CakePHP takes the monotony out of web development. It provides you with all the tools you need to get started coding and what you need to get done: the logic specific to your application. Instead of reinventing the wheel every time you begin a new project, check out a copy of CakePHP and get started with the logic of your application. CakePHP has an active developer team7 and community, bringing great value to the project. In addition to keeping you from wheel-reinventing, using CakePHP means your application’s core is well tested and is being constantly improved. Here’s a quick list of features you’ll enjoy when using CakePHP: • Active, friendly Official CakePHP discussion group 1 http://www.cakephp.org/ 2 http://en.wikipedia.org/wiki/MIT_License 3 http://en.wikipedia.org/wiki/Open_source 4 http://en.wikipedia.org/wiki/Rapid_application_development 5 http://en.wikipedia.org/wiki/Application_framework 6 http://www.php.net/ 7 https://github.com/cakephp?tab=members 45
- 52. CakePHP Cookbook Documentation,Release 2.x • Flexible licensing8 • Compatible with versions PHP 5.2.8 and greater • Integrated CRUD9 for database interaction • Application scaffolding10 • Code generation • MVC11 architecture • Request dispatcher with clean, custom URLs and routes • Built-in validation12 • Fast and flexible templating13 (PHP syntax, with helpers) • View helpers for AJAX, JavaScript, HTML forms and more • Email, cookie, security, session, and request handling Components • Flexible ACL14 • Data sanitization • Flexible caching15 • Localization • Works from any web site directory, with little to no Apache16 configuration involved Understanding Model-View-Controller CakePHP follows the MVC17 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. 8 http://en.wikipedia.org/wiki/MIT_License 9 http://en.wikipedia.org/wiki/Create,_read,_update_and_delete 10 http://en.wikipedia.org/wiki/Scaffold_(programming) 11 http://en.wikipedia.org/wiki/Model-view-controller 12 http://en.wikipedia.org/wiki/Data_validation 13 http://en.wikipedia.org/wiki/Web_template_system 14 http://en.wikipedia.org/wiki/Access_control_list 15 http://en.wikipedia.org/wiki/Web_cache 16 http://httpd.apache.org/ 17 http://en.wikipedia.org/wiki/Model-view-controller 46 Chapter 5. CakePHP Overview
- 53. CakePHP Cookbook Documentation,Release 2.x At a first glance, Model objects can be looked at as the first 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, finding suggestions for new friends, etc. The model objects can be thought as “Friend”, “User”, “Comment”, or “Photo”. 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 contain- ing 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. It is responsible for rendering a response with the aid of both the Model and the View layer. A controller can be seen as a manager that ensures that all resources needed for completing a task are delegated to the correct workers. It waits for petitions from clients, checks their validity according to au- thentication or authorization rules, delegates data fetching or processing to the model, selects the type of presentational data that the clients are accepting, and finally delegates the rendering process to the View layer. Understanding Model-View-Controller 47
- 54. CakePHP Cookbook Documentation,Release 2.x 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 first 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 proceed to delegate to the correct view object the task of generating 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. We’ll add some details later on which are specific to CakePHP, so keep this in mind as we proceed. Benefits Why use MVC? Because it is a tried and true software design pattern that turns an application into a main- tainable, 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 simulta- neously, including the ability to rapidly prototype18. Separation also allows developers to make changes in one part of the application without affecting the others. If you’ve never built an application this way, it takes some time getting used to, but we’re confident that once you’ve built your first application using CakePHP, you won’t want to do it any other way. To get started on your first CakePHP application, try the blog tutorial now 18 http://en.wikipedia.org/wiki/Software_prototyping 48 Chapter 5. CakePHP Overview
- 55. CakePHP Cookbook Documentation,Release 2.x Where to Get Help The Official CakePHP website http://www.cakephp.org The Official 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 first 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 first. Answers may come slower, but will remain longer – and you’ll 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 regarding CakePHP. Check it out for tutorials, case studies, and code examples. Once you’re acquainted with CakePHP, log on and share your knowledge with the community and gain instant fame and fortune. The API http://api.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. It’s 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 sufficient, 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: Where to Get Help 49
- 56. CakePHP Cookbook Documentation,Release 2.x • #cakephp – General Discussion • #cakephp-docs – Documentation • #cakephp-bakery – Bakery If you’re stumped, give us a holler in the CakePHP IRC channel. Someone from the development team19 is usually there, especially during the daylight hours for North and South America users. We’d love to hear from you, whether you need some help, want to find users in your area, or would like to donate your brand new sports car. Official CakePHP discussion group CakePHP Google Group20 CakePHP also has its official discusson group on Google Groups. There are thousands of people discussing CakePHP projects, helping each other, solving problems, building projects and sharing ideas. It can be a great resource for finding archived answers, frequently asked questions, and getting answers to immediate problems. Join other CakePHP users and start discussing. Stackoverflow http://stackoverflow.com/21 Tag your questions with cakephp and the specific version you are using to enable existing users of stack- overflow to find your questions. Where to get Help in your Language French • French CakePHP Community22 19 https://github.com/cakephp?tab=members 20 http://groups.google.com/group/cake-php 21 http://stackoverflow.com/questions/tagged/cakephp/ 22 http://cakephp-fr.org 50 Chapter 5. CakePHP Overview
- 57. CHAPTER 6 Controllers Controllers arethe ‘C’ in MVC. After routing has been applied and the correct controller has been found, your controller’s 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, a controller is used to manage the logic around a single model. For example, if you were building a site for an online bakery, you might have a RecipesController managing your recipes and an IngredientsController managing your ingredients. However, it’s also possible to have controllers work with more than one model. In CakePHP, a controller is named after the primary model it handles. Your application’s controllers extend the AppController class, which in turn ex- tends the core Controller class. The AppController class can be defined in /app/Controller/AppController.php and it should contain methods that are shared between all of your application’s controllers. Controllers provide a number of methods that handle requests. These are called actions. By default, each public method in a controller is an action, and is accessible from a URL. An action is 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 application’s controllers. AppController itself extends the Controller class included in the CakePHP core library. AppController is defined in /app/Controller/AppController.php as follows: class AppController extends Controller { } Controller attributes and methods created in your AppController will be available to all of your appli- cation’s controllers. Components (which you’ll learn about later) are best used for code that is used in many (but not necessarily all) controllers. 51
- 58. 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 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 into your application’s con- trollers: • $components • $helpers • $uses Remember to add the default Html and Form helpers if you define the $helpers property in your AppController. Also remember to call AppController‘s callbacks within child controller callbacks for best results: public function beforeFilter() { parent::beforeFilter(); } Request parameters When a request is made to a CakePHP application, CakePHP’s Router and Dispatcher classes use Routes Configuration to find and create the correct controller. The request data is encapsulated in 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 boilerplate code you would otherwise need to write. By convention, CakePHP renders a view with an inflected version of the action name. Returning to our on- line 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.. 52 Chapter 6. Controllers
- 59. CakePHP Cookbook Documentation,Release 2.x } public function search($query) { //action logic goes here.. } } The view files for these actions would be app/View/Recipes/view.ctp, app/View/Recipes/share.ctp, and app/View/Recipes/search.ctp. The conventional view file name is the lowercased 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 don’t 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 you’d like to skip the default behavior, both of the following techniques will bypass 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 you use controller methods with requestAction(), you will often want to return data that isn’t 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 nor- mal requests. Returning array data to a non-requestAction request will cause errors and should be avoided. See the section on requestAction() for more tips on using requestAction() In order for you to use a controller effectively in your own application, we’ll cover some of the core attributes and methods provided by CakePHP’s controllers. Request Life-cycle callbacks class Controller CakePHP controllers come fitted 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. It’s a handy place to check for an active Request Life-cycle callbacks 53
- 60. CakePHP Cookbook Documentation,Release 2.x session or inspect user permissions. 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 API1. Interacting with Views Controllers interact with views 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 file 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 you’ve 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 first parameter. This can often be a quick way to assign a set of information to the view: $data = array( ’color’ => ’pink’, ’type’ => ’sugar’, ’base_price’ => 23.95 ); // make $color, $type, and $base_price // available to the view: 1 http://api.cakephp.org/2.4/class-Controller.html 54 Chapter 6. Controllers
- 61. CakePHP Cookbook Documentation,Release 2.x $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’); As of 2.5 the variable $title_for_layout is deprecated, use view blocks instead. 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 you’ve submitted using the set() method), places the view inside its $layout, and serves it back to the end user. The default view file used by render is determined by convention. If the search() action of the RecipesController is requested, the view file 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 after every action’s logic (unless you’ve set $this->autoRender to false), you can use it to specify an alternate view file by specifying an action name in the controller using $action. If $view starts with ‘/’, it is assumed to be a view or element file 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 with which the view is rendered. Rendering a specific view In your controller, you may want to render a different view than the conventional one. 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 instead of app/View/Posts/my_action.ctp You can also render views inside plugins using the following syntax: $this->render(’PluginName.PluginController/custom_file’). For example: Controller Methods 55
- 62. CakePHP Cookbook Documentation,Release 2.x 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 flow control method you’ll use most often is redirect(). This method takes its first 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 define 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’, 56 Chapter 6. Controllers
- 63. CakePHP Cookbook Documentation,Release 2.x ’product’ => ’pizza’, ’quantity’ => 5) ); An example using query strings and hash would look like: $this->redirect(array( ’controller’ => ’orders’, ’action’ => ’confirm’, ’?’ => array( ’product’ => ’pizza’, ’quantity’ => 5 ), ’#’ => ’top’) ); The generated URL would be: http://www.example.com/orders/confirm?product=pizza&quantity=5#top 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 first parameter should hold the message to be displayed, and the second parameter is a CakePHP- relative URL. CakePHP will display the $message for $pause seconds before forwarding the user on. If there’s a particular template you’d like your flashed message to use, you may specify the name of that layout in the $layout parameter. For in-page flash messages, be sure to check out SessionComponent::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. Controller Methods 57
- 64. CakePHP Cookbook Documentation,Release 2.x 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() != ’/’) { 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 user’s 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 find 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 CakePHP’s FormHelper and HtmlHelper to create a quick form 58 Chapter 6. Controllers
- 65. CakePHP Cookbook Documentation,Release 2.x based on the Order model. Then a controller action can use the data posted from that form to craft find 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->find() 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( ’Order’ => array( ’num_items’ => ’4’, ’referrer’ => ’Ye Olde’ ) ) */ // Let’s 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 find 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, fields 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 find 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 controller’s 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. Controller Methods 59
- 66. CakePHP Cookbook Documentation,Release 2.x 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. Let’s 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’, ’limit’ => 10) ); } } 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 it’s 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 file exists and is valid. In addition, requestAction() now takes array based cake style URLs: echo $this->requestAction( array(’controller’ => ’articles’, ’action’ => ’featured’), array(’return’) ); 60 Chapter 6. Controllers
- 67. CakePHP Cookbook Documentation,Release 2.x This allows the requestAction() call to bypass the usage of Router::url() which can in- crease 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 sec- ond array and wrap them with the correct key. This is because requestAction() merges the named args array (requestAction’s 2nd parameter) with the Controller::params member ar- ray 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 action’s 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)) ); 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 pa- rameters 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 controller’s default model or its associated model: $this->loadModel(’Article’); $recentArticles = $this->Article->find( ’all’, array(’limit’ => 5, ’order’ => ’Article.created DESC’) ); $this->loadModel(’User’, 2); $user = $this->User->read(); Controller Attributes For a complete list of controller attributes and their descriptions visit the CakePHP API2. 2 http://api.cakephp.org/2.4/class-Controller.html Controller Attributes 61
- 68. CakePHP Cookbook Documentation,Release 2.x 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 inflecting 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 you’ll 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}). Note: Each controller has some of these classes available by default, so you may not need to configure 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 controller’s 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 file. However, the models defined in the AppController will still be loaded. You can also use false to not load any models at all. Even those defined in the AppController. Changed in version 2.1: $uses now has a new default value, it also handles false differently. property Controller::$helpers The HtmlHelper, FormHelper, and SessionHelper are available by default, as is the SessionComponent. But if you choose to define your own $helpers array in AppController, make sure to include HtmlHelper and FormHelper 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. Let’s 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’); } 62 Chapter 6. Controllers
- 69. CakePHP Cookbook Documentation,Release 2.x Each of these variables are merged with their inherited values, therefore it is not necessary (for exam- ple) to redeclare the FormHelper, or anything that is declared in your AppController. 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 Configuring Components for more infor- mation. Other Attributes While you can check out the details for all controller attributes in the API3, there are other controller at- tributes that merit their own sections in the manual. property Controller::$cacheAction The cacheAction attribute is used to define the duration and other information about full page caching. You can read more about full page caching in the CacheHelper documentation. property Controller::$paginate The paginate attribute is a deprecated compatibility property. Using it loads and configures the PaginatorComponent. It is recommended that you update your code to use normal component settings: class ArticlesController extends AppController { public $components = array( ’Paginator’ => array( ’Article’ => array( ’conditions’ => array(’published’ => 1) ) ) ); } 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 inter- rogating and interacting with request data. On each request, one CakeRequest is created and then passed 3 http://api.cakephp.org More on controllers 63
- 70. CakePHP Cookbook Documentation,Release 2.x 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 client’s IP address, and the subdomain/domain information about the application the server is running on. • Provide access to request parameters both as array indexes and object properties. Accessing request parameters CakeRequest exposes several interfaces for accessing request parameters. The first uses object properties, the second uses array indexes, and the third uses $this->request->params: $this->request->controller; $this->request[’controller’]; $this->request->params[’controller’]; All of the above will access the same value. Multiple ways of accessing the parameters have been provided 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’]; All of these will provide you access to the passed arguments and named parameters. There are several im- portant/useful parameters that CakePHP uses internally. These are also all found in the request parameters: • plugin The plugin handling the request. Will be null when there is no plugin. • controller The controller handling the current request. • action The action handling the current request. • prefix The prefix for the current action. See Prefix 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(). 64 Chapter 6. Controllers
- 71. CakePHP Cookbook Documentation,Release 2.x Accessing Querystring parameters Querystring parameters can be read using CakeRequest::$query: // URL is /posts/index?page=1&sort=title $this->request->query[’page’]; // You can also access it via an array // Note: BC accessor, will be deprecated in future versions $this->request[’url’][’page’]; 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 prefix will have that data prefix 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 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’); More on controllers 65
- 72. CakePHP Cookbook Documentation,Release 2.x Some deserializing methods require additional parameters when called, such as the ‘as array’ parameter on json_decode. 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 meth- ods have been moved to CakeRequest, and offer a new interface alongside a more backwards-compatible usage: $this->request->is(’post’); $this->request->isPost(); // deprecated Both method calls will return the same value. For the time being, the methods are still avail- able on RequestHandlerComponent, but are deprecated and still might be removed before the final release. You can also easily extend the request detectors that are available by using CakeRequest::addDetector() to create new kinds of detectors. There are four different types of detectors that you can create: • Environment value comparison - Compares a value fetched from env() for equality with the pro- vided 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 expres- sion. Subsequent calls to add an already defined options detector will merge the options. • Callback detectors - Callback detectors allow you to provide a ‘callback’ type to handle the check. The callback will receive the request object as its only parameter. Some examples would be: // Add an environment detector. $this->request->addDetector( ’post’, array(’env’ => ’REQUEST_METHOD’, ’value’ => ’POST’) ); // Add a pattern value detector. $this->request->addDetector( ’iphone’, 66 Chapter 6. Controllers
- 73. CakePHP Cookbook Documentation,Release 2.x array(’env’ => ’HTTP_USER_AGENT’, ’pattern’ => ’/iPhone/i’) ); // 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 sub- domains. There are several built-in detectors that you can use: • is(’get’) Check to see whether the current request is a GET. • is(’put’) Check to see whether the current request is a PUT. • is(’post’) Check to see whether the current request is a POST. • is(’delete’) Check to see whether the current request is a DELETE. • is(’head’) Check to see whether the current request is HEAD. • is(’options’) Check to see whether the current request is OPTIONS. • is(’ajax’) Check to see whether the current request came with X-Requested-With = XML- HttpRequest. • is(’ssl’) Check to see whether the request is via SSL • is(’flash’) Check to see whether the request has a User-Agent of Flash • is(’mobile’) Check to see whether 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 figure out how it still fits into the picture. For 2.0, RequestHandlerComponent provides a layer of sugar, such as switching layout and views based on content, on top of the utility that CakeRequest affords. This separation of utility and sugar between the two classes lets you more easily choose what you want. More on controllers 67
- 74. 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 find 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. Deprecated since version 2.5: Use CakeRequest::allowMethod() instead. CakeRequest::allowMethod($methods) Set allowed HTTP methods. If not matched will throw MethodNotAllowedException. The 405 re- sponse will include the required Allow header with the passed methods New in version 2.5. CakeRequest::referer($local = false) Returns the referring address for the request. CakeRequest::clientIp($safe = true) Returns the current visitor’s IP address. CakeRequest::header($name) Allows you to access any of the HTTP_* headers that were used for the request. For example: $this->request->header(’User-Agent’); would return the user agent used for the request. 68 Chapter 6. Controllers
- 75. CakePHP Cookbook Documentation,Release 2.x CakeRequest::input($callback[, $options]) Retrieve the input data for a request, and optionally pass it through a decoding function. Useful when interacting with XML or JSON request body content. Additional parameters for the decoding function can be passed as arguments to input(): $this->request->input(’json_decode’); CakeRequest::data($name) Provides dot notation access to request data. Allows request data to be read and modified. Calls can be chained together as well: // 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 criterion. Uses the built-in detection rules as well as any additional rules defined with CakeRequest::addDetector(). CakeRequest::addDetector($name, $options) Add a detector to be used with CakeRequest::is(). See Inspecting the request for more infor- mation. CakeRequest::accepts($type = null) Find out which content types the client accepts, or check whether it accepts 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 all the languages accepted by the client, or check whether a specific language is accepted. Get the list of accepted languages: CakeRequest::acceptLanguage(); Check whether a specific language is accepted: More on controllers 69
- 76. CakePHP Cookbook Documentation,Release 2.x 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. 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 flexible and transparent class. If you need to override it with your own application-specific class, you can replace CakeResponse in app/webroot/index.php. This will make all the controllers in your application use CustomResponse instead of CakeResponse. You can also replace the response instance by setting $this->response in your controllers. Overriding the response object is handy during testing, as it 70 Chapter 6. Controllers
- 77. CakePHP Cookbook Documentation,Release 2.x 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 application’s responses with CakeResponse::type(). If your application needs to deal with content types that are not built into CakeResponse, you can map them with CakeResponse::type() as well: // Add a vCard type $this->response->type(array(’vcf’ => ’text/v-card’)); // Set the response Content-Type to vcard. $this->response->type(’vcf’); Usually, you’ll want to map additional content types in your controller’s beforeFilter() callback, so you can leverage the automatic view switching features of RequestHandlerComponent if you are using it. Sending files There are times when you want to send files as responses for your requests. Prior to version 2.3, you could use MediaView. As of 2.3, MediaView is deprecated and you can use CakeResponse::file() to send a file as response: public function sendFile($id) { $file = $this->Attachment->getFile($id); $this->response->file($file[’path’]); // Return response object to prevent controller from trying to render // a view return $this->response; } As shown in the above example, you must pass the file path to the method. CakePHP will send a proper content type header if it’s a known file type listed in CakeResponse::$_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 file to be downloaded instead of displayed in the browser by specifying the options: $this->response->file( $file[’path’], array(’download’ => true, ’name’ => ’foo’) ); Sending a string as file You can respond with a file that does not exist on the disk, such as a pdf or an ics generated on the fly from a string: More on controllers 71
- 78. CakePHP Cookbook Documentation,Release 2.x 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 configurations: // 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 as regular header calls do. Headers are not sent when CakeResponse::header() is called; instead they are 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 not to cache the results of a controller action. CakeResponse::disableCache() is intended for just that: public function index() { // do something. $this->response->disableCache(); } 72 Chapter 6. Controllers
- 79. CakePHP Cookbook Documentation,Release 2.x Warning: Using disableCache() with downloads from SSL domains while trying to send files 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 vis- itors’ experience. CakeResponse::cache() sets the Last-Modified value to the first argument. Expires header and the max-age directive are set based on the second parameter. Cache-Control’s public directive is set as well. Fine tuning HTTP cache One of the best and easiest ways of speeding up your application is to use 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 modified time and response entity tag. Rather than forcing you to code the logic for caching and for invalidating (refreshing) it once the data has changed, HTTP uses two models, expiration and validation, which usually are much simpler to use. Apart from using CakeResponse::cache(), you can also use many other methods to fine-tune HTTP cache headers to take advantage of browser or reverse proxy caching. The Cache Control header New in version 2.1. Used under the expiration model, this header contains multiple indicators that 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 final valid Cache-Control header. The first is the CakeResponse::sharable() method, which indicates whether a response is to be considered sharable across different users or clients. 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, the control directive must be set as public. The 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); More on controllers 73
- 80. CakePHP Cookbook Documentation,Release 2.x } 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 directives in the Cache-Control header. The Expiration header New in version 2.1. You can set the Expires header to a date and 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 instance 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 it asks the application every time whether the resource has changed, instead of using it directly. This is commonly used with static resources such as images and other assets. The etag() method (called entity tag) is a string that uniquely identifies the requested resource, as a checksum does for a file, in order to determine whether it matches a cached resource. To take advantage of this header, you must either call the CakeResponse::checkNotModified() method manually or include the RequestHandlerComponent 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; } ... } 74 Chapter 6. Controllers
- 81. CakePHP Cookbook Documentation,Release 2.x The Last Modified header New in version 2.1. Under the HTTP cache validation model, you can also set the Last-Modified header to indicate the date and time at which the resource was modified for the last time. Setting this header helps CakePHP tell caching clients whether the response was modified or not based on their cache. To take advantage of this header, you must either call the CakeResponse::checkNotModified() method manually or include the RequestHandlerComponent 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 content using the same URL. This is often the case if you have a multilingual page or respond with different HTML depending on the browser. Under such circumstances you can 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 having methods spread across several objects, you only have to mock a single object, since controllers and components delegate to CakeResponse. This helps you to 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 run tests from the command line more easily, as you can use mocks to avoid the ‘headers sent’ errors that can occur when trying to set headers in CLI. More on controllers 75
- 82. CakePHP Cookbook Documentation,Release 2.x 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 more 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 of 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 the Expires header to be set to a specific 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-Modified header to a specific date and time in the correct format. New in version 2.1. CakeResponse::checkNotModified(CakeRequest $request) Compares the cache headers for the request object with the cache header from the response and deter- 76 Chapter 6. Controllers
- 83. CakePHP Cookbook Documentation,Release 2.x mines whether it can still be considered fresh. If so, deletes the response content, and sends the 304 Not Modified header. New in version 2.1. CakeResponse::compress() Turns on gzip compression for the request. CakeResponse::download($filename) Allows you to send a response as an attachment, and to set its filename. CakeResponse::statusCode($code = null) Allows you to set the status code of the response. CakeResponse::body($content = null) Sets the content body of 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 the Content-Disposition header of a file either to display or to download. New in version 2.3. Scaffolding Deprecated since version 2.5: Dynamic scaffolding will be removed and replaced in 3.0 Application scaffolding is a technique that allows a developer to define and create a basic application that can create, retrieve, update and delete objects. Scaffolding in CakePHP also allows developers to define how objects are related to each other, and to create and break those links. All that’s needed to create a scaffold is a model and its controller. Once you set the $scaffold variable in the controller, you’re up and running. CakePHP’s scaffolding is pretty cool. It allows you to get a basic CRUD application up and going in minutes. It’s so cool that you’ll want to use it in production apps. Now, we think it’s cool too, but please realize that scaffolding is... well... just scaffolding. It’s a loose structure you throw up real quick during the beginning of a project in order to get started. It isn’t meant to be completely flexible, it’s meant as a temporary way to get up and going. If you find yourself really wanting to customize your logic and your views, it’s time to pull your scaffolding down in order to write some code. CakePHP’s 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. More on controllers 77
- 84. CakePHP Cookbook Documentation,Release 2.x To add scaffolding to your application, in the controller, add the $scaffold variable: class CategoriesController extends AppController { public $scaffold; } Assuming you’ve created even the most basic Category model class file (in app/Model/Category.php), you’re 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 aware of model’s associations; so, if your Category model belongsTo User, you’ll see re- lated User IDs in the Category listings. While scaffolding “knows” about model’s 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 to your User and Group models. Before you do it, the view displays an empty select input for Group in the New User form; after – 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 you’d rather see something besides an ID (like the user’s first name), you can set the $displayField variable in the model. Let’s set the $displayField variable in our User class so that users related to categories will be shown by first name rather than just by 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/Config/core.php with Configure::write(’Routing.prefixes’, array(’admin’));, you can use scaffold- ing to generate an admin interface. Once you have enabled admin routing, assign your admin prefix 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 78 Chapter 6. Controllers
- 85. CakePHP Cookbook Documentation,Release 2.x http://example.com/admin/controller/add http://example.com/admin/controller/delete 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 file for the action as well. Customizing Scaffold Views If you’re looking for something a little different in your scaffolded views, you can create templates. We still don’t recommend using this technique for production applications, but such a customization may be useful during prototyping iterations. Custom scaffolding views for a specific 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 con- troller for serving up static content. The home page you see after installation is generated using this con- troller. If you make the view file 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 CakePHP’s console utility the Pages Controller is created in your app/Controller/ folder. You can also copy the file 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 file under the lib/Cake folder to avoid issues when updating the core in future. More on controllers 79
- 86. CakePHP Cookbook Documentation,Release 2.x Components Components are packages of logic that are shared between controllers. CakePHP comes with a fantastic set of core components you can use to aid in various common tasks. You can also create your own components. If you find yourself wanting to copy and paste things between controllers, you should consider creating your own component to contain the functionality. Creating components keeps controller code clean and allows you to reuse code between projects. Each of the core components is detailed in its own chapter. See Components. This section describes how to configure and use components, and how to create your own components. Configuring Components Many of the core components require configuration. Some examples of components requiring configuration are Authentication and Cookie. Configuration for these components, and for components in general, is usually done in the $components array or your controller’s beforeFilter() method: class PostsController extends AppController { public $components = array( ’Auth’ => array( ’authorize’ => array(’controller’), ’loginAction’ => array( ’controller’ => ’users’, ’action’ => ’login’ ) ), ’Cookie’ => array(’name’ => ’CookieMonster’) ); The previous fragment of code would be an example of configuring a component with the $components array. All core components allow their configuration settings to be set in this way. In addition, you can configure components in your controller’s 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’; } It’s possible, however, that a component requires certain configuration options to be set before the con- troller’s beforeFilter() is run. To this end, some components allow configuration options be set in the $components array: public $components = array( ’DebugKit.Toolbar’ => array(’panels’ => array(’history’, ’session’)) ); 80 Chapter 6. Controllers
- 87. CakePHP Cookbook Documentation,Release 2.x Consult the relevant documentation to determine what configuration 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 you’ve 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: 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 fly 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 controller’s method you More on controllers 81
- 88. CakePHP Cookbook Documentation,Release 2.x can do the following: $this->OneTimer = $this->Components->load(’OneTimer’); $this->OneTimer->getTime(); Note: Keep in mind that loading a component on the fly 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 con- trollers. The first step is to create a new component file and class. Create the file 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; } } Note: All components must extend Component. Failing to do this will trigger an exception. Including your component in your controllers Once our component is finished, we can use it in the application’s controllers by placing the component’s name (without the “Component” part) in the controller’s $components array. The controller will auto- matically 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. 82 Chapter 6. Controllers
- 89. CakePHP Cookbook Documentation,Release 2.x When including Components in a Controller you can also declare a set of parameters that will be passed on to the Component’s 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, if array keys match component’s public properties, the properties will be set to the values of these keys. 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) { $this->Existing->foo(); } public function bar() { // ... } } // app/Controller/Component/ExistingComponent.php App::uses(’Component’, ’Controller’); class ExistingComponent extends Component { public function foo() { // ... } } Note: In contrast to a component included in a controller no callbacks will be triggered on a component’s component. More on controllers 83
- 90. CakePHP Cookbook Documentation,Release 2.x 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) Is called before the controller’s beforeFilter method. Component::startup(Controller $controller) Is called after the controller’s beforeFilter method but before the controller executes the current action handler. Component::beforeRender(Controller $controller) Is called after the controller executes the requested action’s logic, but before the controller’s renders views and layout. Component::shutdown(Controller $controller) Is called before output is sent to the browser. Component::beforeRedirect(Controller $controller, $url, $status=null, $exit=true) Is invoked when the controller’s redirect method is called but before any further action. If this method returns false the controller will not continue on to redirect the request. The $url, $status and $exit variables have same meaning as for the controller’s method. You can also return a string which will be interpreted as the URL to redirect to or return an associative array with the key ‘url’ and optionally ‘status’ and ‘exit’. 84 Chapter 6. Controllers
- 91. CHAPTER 7 Views Views arethe V in MVC. Views are responsible for generating the specific output required for the request. Often this is in the form of HTML, XML, or JSON, but streaming files and creating PDF’s 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 files, or dynamically generated files, you can use Sending files. • 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 file for a user. By default CakePHP view files are written in plain PHP and have a default extension of .ctp (CakePHP Tem- plate). These files contain all the presentational logic needed to get the data it received from the controller in a format that is ready for the audience you’re serving to. If you’d prefer using a templating language like Twig, or Smarty, a subclass of View will bridge your templating language and CakePHP. A view file is stored in /app/View/, in a subfolder named after the controller that uses the file. It has a filename corresponding to its action. For example, the view file for the Products controller’s “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 application’s response. • elements: smaller, reusable bits of view code. Elements are usually rendered inside views. 85
- 92. CakePHP Cookbook Documentation,Release 2.x • layouts: view files that contain presentational code that wraps many interfaces in your application. Most views are rendered inside 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 specific view being rendered. By extending a common view file, you can avoid repeating the common markup for your sidebar, and only define 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 file could be used as a parent view. It expects that the view extending it will define the sidebar and title blocks. The content block is a special block that CakePHP creates. It will contain all the uncaptured content from the extending view. Assuming our view file has a $post variable with the data about our post, the 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’]); 86 Chapter 7. Views
- 93. CakePHP Cookbook Documentation,Release 2.x The post view above shows how you can extend a view, and populate a set of blocks. Any content not already in a defined 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 file. Once it is complete, the extended view will be rendered. Calling extend() more than once in a view file 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 view’s content as the content block. Note: You should avoid using content as a block name in your application. CakePHP uses this for uncaptured content in extended views. Using view blocks New in version 2.1. View blocks replace $scripts_for_layout and provide a flexible API that allows you to define slots or blocks in your views/layouts that will be defined 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 defined in two ways: either as a capturing block, or by direct assignment. The start(), append() and end() methods allow you 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() method was added to prepend content to an existing block: // Prepend to sidebar $this->prepend(’sidebar’, ’this content goes on top of sidebar’); Using view blocks 87
- 94. CakePHP Cookbook Documentation,Release 2.x The method startIfEmpty() can be used to start a block only if it is empty or undefined. If the block already exists, the captured content will be discarded. This is useful when you want to conditionally define default content for a block if it does 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 a parent view/layout <?php $this->startIfEmpty(’navbar’); ?> <p>If the block is not defined by now - show this instead</p> <?php $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 first section. Since the block was defined 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 second argument: <div class="shopping-cart"> <h3>Your Cart</h3> 88 Chapter 7. Views
- 95. CakePHP Cookbook Documentation,Release 2.x <?php echo $this->fetch(’cart’, ’Your cart is empty’); ?> </div> Changed in version 2.3: The $default argument was added in 2.3. Using blocks for script and CSS files 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’, 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. CakePHP’s 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 files 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’) Here’s an example of what a default layout might look like: Layouts 89
- 96. CakePHP Cookbook Documentation,Release 2.x <!DOCTYPE html> <html lang="en"> <head> <title><?php echo $this->fetch(’title’); ?></title> <link rel="shortcut icon" href="favicon.ico" type="image/x-icon"> <!-- Include external files and scripts here (See HTML helper for more info.) --> <?php echo $this->fetch(’meta’); echo $this->fetch(’css’); echo $this->fetch(’script’); ?> </head> <body> <!-- If you’d like some sort of menu to show up on all of your views, include it here --> <div id="header"> <div id="menu">...</div> </div> <!-- Here’s where I want my views to be displayed --> <?php echo $this->fetch(’content’); ?> <!-- Add a footer to each displayed page --> <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 defined in the views using the built-in HTML helper. Useful for including JavaScript and CSS files from views. Note: When using HtmlHelper::css() or HtmlHelper::script() in view files, 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. Note: The $title_for_layout is deprecated as of 2.5, use $this->fetch(’title’) in your layout and $this->assign(’title’, ’page title’) instead. Setting the title for the layout is easiest to do in the controller, setting the $title_for_layout variable: 90 Chapter 7. Views
- 97. CakePHP Cookbook Documentation,Release 2.x 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 file: $this->set(’title_for_layout’, $titleContent); 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 view’s $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 CakePHP’s default layout) you can use in your own application: ‘ajax’ and ‘flash’. The Ajax layout is handy for crafting AJAX responses - it’s an empty layout. (Most AJAX calls only require a bit of markup in return, rather than a fully-rendered interface.) The flash 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 isn’t 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: Layouts 91
- 98. CakePHP Cookbook Documentation,Release 2.x 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 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 mini- view 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 file. They can also help you re-use content fragments in your application. Elements live in the /app/View/Elements/ folder, and have the .ctp filename 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 element’s second argument: echo $this->element(’helpbox’, array( "helptext" => "Oh, this text is very helpful." )); Inside the element file, 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 files). In the above example, the /app/View/Elements/helpbox.ctp file 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( // uses the "long_view" cache configuration "cache" => "long_view", // set to true to have before/afterRender called for the element "callbacks" => true 92 Chapter 7. Views
- 99. CakePHP Cookbook Documentation,Release 2.x ) ); Element caching is facilitated through the Cache class. You can configure elements to be stored in any Cache configuration you’ve set up. This gives you a great amount of flexibility 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(), which 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, 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 five 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 configuration. Otherwise, you can set which cache configuration Elements 93
- 100. CakePHP Cookbook Documentation,Release 2.x should be used. See Caching for more information on configuring 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() call’s cached result. For example: 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’) ); The above will ensure that both element results are cached separately. If you want all element caching to use the same cache configuration, you can avoid some repetition by setting View::$elementCache to the cache configuration you want to use. CakePHP will use this configuration 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 prefixed onto all elements used, unless another plugin name is present. If the element doesn’t 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. For example, if you are in the ContactsController of the Contacts plugin, the following: echo $this->element(’helpbox’); // and echo $this->element(’Contacts.helpbox’); are equivalent and will result in the same element being rendered. 94 Chapter 7. Views
- 101. CakePHP Cookbook Documentation,Release 2.x 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 files should be put in App/View. For example: App/View/PdfView.php • View classes should be suffixed with View. For example: PdfView. • When referencing view class names you should omit the View suffix. For example: $this->viewClass = ’Pdf’;. You’ll also want to extend View to ensure things work correctly: // in App/View/PdfView.php App::uses(’View’, ’View’); 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 files. To call any view method use $this->method() 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 file 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 file you can do: $this->set(’activeMenuButton’, ’posts’); Then, in your layout, the $activeMenuButton variable will be available and contain the value ‘posts’. View::get(string $var, $default = null) Get the value of a viewVar with the name $var. As of 2.5, you can provide a default value in case the variable is not already set. Creating your own view classes 95
- 102. CakePHP Cookbook Documentation,Release 2.x Changed in version 2.5: The $default argument was added in 2.5. View::getVar(string $var) Gets the value of the viewVar with the name $var. Deprecated since version 2.3: Use View::get() instead. 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 ID’s 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 and elements in the layout will not be added to $scripts_for_layout. This method is most often used from inside helpers, such as the JsHelper and HtmlHelper Helpers. Deprecated since version 2.1: Use the Using view blocks features instead. View::blocks() Get the names of all defined 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 to the block with $name. See the section on Using view blocks for examples. New in version 2.3. 96 Chapter 7. Views
- 103. CakePHP Cookbook Documentation,Release 2.x View::startIfEmpty($name) Start a block if it is empty. All content in the block will be captured and discarded if the block is already defined. 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 undefined, ‘’ 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 configuration used to cache elements. Setting this property will change the default config- uration 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 file, 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. 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: More about Views 97
- 104. CakePHP Cookbook Documentation,Release 2.x 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 files 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. Note: It is 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 file for an edit action of a Posts controller would reside at /app/View/Themed/Example/Posts/edit.ctp. Layout files would reside in /app/View/Themed/Example/Layouts/. If a view file can’t be found in the theme, CakePHP will try to locate the view file in the /app/View/ folder. This way, you can create master view files 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 files. A theme can include any necessary assets in its web- root 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, it’s recommended that you either symlink or copy theme assets into the application’s 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 finding the correct theme assets in your view paths. All of CakePHP’s built-in helpers are aware of themes and will create the correct paths automatically. Like view files, if a file isn’t 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’); //creates a path like /theme/purple_cupcake/css/main.css 98 Chapter 7. Views
- 105. CakePHP Cookbook Documentation,Release 2.x //and links to app/View/Themed/PurpleCupcake/webroot/css/main.css Increasing performance of plugin and theme assets It’s 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 it’s 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 becomes app/webroot/debug_kit/js/my_file.js • app/View/Themed/Navy/webroot/css/navy.css becomes app/webroot/theme/Navy/css/navy.css Media Views class MediaView Deprecated since version 2.3: Use Sending files instead. Media views allow you to send binary files to the user. For example, you may wish to have a directory of files outside of the webroot to prevent users from direct linking them. You can use the Media view to pull the file from a special folder within /app/, allowing you to perform authentication before delivering the file 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 file 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); } } Here’s an example of rendering a file whose mime type is not included in the MediaView’s $mimeType array. We are also using a relative path which will default to your app/webroot folder: More about Views 99
- 106. 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.document’ ), ’path’ => ’files’ . DS ); $this->set($params); } Settable Parameters id The ID is the file name as it resides on the file server including the file extension. name The name allows you to specify an alternate file name to be sent to the user. Specify the name without the file extension. download A boolean value indicating whether headers should be set to force download. extension The file extension. This is matched against an internal list of acceptable mime types. If the mime type specified is not in the list (or set in the mimeType parameter array), the file will not be downloaded. path The folder name, including the final 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 file (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 first is by using the _serialize key, and the second is by creating normal view files. 100 Chapter 7. Views
- 107. CakePHP Cookbook Documentation,Release 2.x Enabling data views in your application Before you can use the data view classes, you’ll 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 controller’s list of components. This will en- able 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 file, CakePHP will automat- ically 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 defining view files for your controller actions if you don’t 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 files. The value of _serialize can be either a string or an array of view variables to serialize: class PostsController extends AppController { public $components = array(’RequestHandler’); public function index() { $this->set(’posts’, $this->paginate()); $this->set(’_serialize’, array(’posts’)); } } You can also define _serialize as an array of view variables to combine: class PostsController extends AppController { public $components = array(’RequestHandler’); public function index() { // some code that created $posts and $comments $this->set(compact(’posts’, ’comments’)); $this->set(’_serialize’, array(’posts’, ’comments’)); } } Defining _serialize as an array has the added benefit 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. More about Views 101
- 108. CakePHP Cookbook Documentation,Release 2.x Using a data view with view files You should use view files if you need to do some manipulation of your view content before creating the final output. For example if we had posts, that had a field containing generated HTML, we would probably want to omit that from a JSON response. This is a situation where a view file 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 complex manipulations, or use helpers to do formatting as well. Note: The data view classes don’t support layouts. They assume that the view file 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 appli- cation. 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 appli- cation. 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 parameter 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 presen- tational logic that is shared between many views, elements, or layouts. This chapter will show you how to 102 Chapter 7. Views
- 109. CakePHP Cookbook Documentation,Release 2.x create your own helpers, and outline the basic tasks CakePHP’s core helpers can help you accomplish. 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 CakePHP temporarily stores parsed layouts and views as simple PHP + HTML files. 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 file and output to generate the cache file. 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 CakePHP doesn’t find 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 Configure write call for Cache.check. This will tell CakePHP to check for, and generate view cache files when handling requests. Once you’ve uncommented the Cache.check line you will need to add the helper to your controller’s $helpers array: class PostsController extends AppController { public $helpers = array(’Cache’); } You will also need to add the CacheDispatcher to your dispatcher filters 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 Config- ure::write(‘Cache.viewPrefix’, ‘YOURPREFIX’); to store the view cache files prefixed. Additional configuration options CacheHelper has a few additional configuration 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”). More about Views 103
- 110. CakePHP Cookbook Documentation,Release 2.x Using the example of an ArticlesController, that receives a lot of traffic that needs to be cached: 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 files to create the components and models for the controller. Additionally, fire 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 don’t 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 <!--nocache--> <!--/nocache--> like so: <!--nocache--> <?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; ?> <!--/nocache--> 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 file is created, the request object, and view variables are serialized with PHP’s serialize(). 104 Chapter 7. Views
- 111. 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 modified. 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 you’ve 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 files. If you need to clear the cached view files, 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 flexible - it will do almost everything for you using conventions, or you can use specific methods to get only what you need. Creating Forms The first method you’ll 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, I’d 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. More about Views 105
- 112. 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 form’s context. All fields are assumed to belong to this model (unless otherwise specified), 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 prop- erty to automatically detect whether to create an add or edit form. If $this->request->data contains an array element named after the form’s model, and that array contains a non-empty value of the model’s 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 field 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 configuration 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(). 106 Chapter 7. Views
- 113. 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’, ‘file’, ‘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 ‘file’ 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 file elements inside the form. The absence of the proper enctype attribute will cause the file 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 specific action in your current controller. For example, if you’d 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 isn’t 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’, More about Views 107
- 114. CakePHP Cookbook Documentation,Release 2.x ’type’ => ’get’ )); 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 form’s 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 form’s 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 // has a label element echo $this->Form->input( ’username’, array(’label’ => ’Username’) ); Closing the Form FormHelper::end($options = null, $secureAttributes = array()) 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(); ?> <!-- Form elements go here --> <?php echo $this->Form->end(); ?> If a string is supplied as the first parameter to end(), the FormHelper outputs a submit button named accordingly along with the closing form tag: <?php echo $this->Form->end(’Finish’); ?> 108 Chapter 7. Views
- 115. CakePHP Cookbook Documentation,Release 2.x Will output: <div class="submit"> <input type="submit" value="Finish" /> </div> </form> You can specify detail settings by passing an array to end(): $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 Form Helper API1 for further details. Note: If you are using SecurityComponent in your application you should always end your forms with end(). Changed in version 2.5: The $secureAttributes parameter was added in 2.5. Creating form elements There are a few ways to create form inputs with the FormHelper. We’ll start by looking at input(). This method will automatically inspect the model field it has been supplied in order to create an appropriate input for that field. Internally input() delegates to other methods in FormHelper. FormHelper::input(string $fieldName, 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 1 http://api.cakephp.org/2.4/class-FormHelper.html More about Views 109
- 116. CakePHP Cookbook Documentation,Release 2.x 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 binary file The $options parameter allows you to customize how input() works, and finely control what is generated. The wrapping div will have a required class name appended if the validation rules for the Model’s field do not specify allowEmpty => true. One limitation of this behavior is the field’s model must have been loaded during this request. Or be directly associated to the model supplied to create(). New in version 2.5: The binary type now maps to a file input. 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 field. 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, let’s assume that your User model includes fields 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 fields: echo $this->Form->create(); echo $this->Form->input(’username’); //text echo $this->Form->input(’password’); //password echo $this->Form->input(’approved’); //day, month, year, hour, minute, //meridian echo $this->Form->input(’quote’); //textarea echo $this->Form->end(’Add’); A more extensive example showing some options for a date field: echo $this->Form->input(’birth_dt’, array( ’label’ => ’Date of birth’, ’dateFormat’ => ’DMY’, ’minYear’ => date(’Y’) - 70, ’maxYear’ => date(’Y’) - 18, )); 110 Chapter 7. Views
- 117. CakePHP Cookbook Documentation,Release 2.x Besides the specific options for input() found below, you can specify any option for the in- put 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 vari- able (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 field while using a belongsTo - or hasOne - Relation, you can add the following to your Users-controller (assuming your User belongsTo Group): $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(’list’) ); Note: Try to avoid using FormHelper::input() to generate submit buttons. Use FormHelper::submit() instead. FormHelper::inputs(mixed $fields = null, array $blacklist = null, $options = array()) Generate a set of inputs for $fields. If $fields is null all fields, except of those defined in $blacklist, of the current model will be used. In addition to controller fields output, $fields can be used to control legend and fieldset render- ing 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 fields control, inputs() allows you to use a few additional options. •fieldset Set to false to disable the fieldset. If a string is supplied it will be used as the class name for the fieldset element. More about Views 111
- 118. CakePHP Cookbook Documentation,Release 2.x •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 field name with the form helper methods, it’ll 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.fieldname as the first parameter: echo $this->Form->input(’Modelname.fieldname’); If you need to specify multiple fields using the same field name, thus creating an array that can be saved in one shot with saveAll(), use the following convention: 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 field-suffixes internally for datetime input creation. If you are using fields 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 specific to FormHelper::input(). • $options[’type’] You can force the type of an input, overriding model introspection, by spec- ifying a type. In addition to the field types found in the Creating form elements, you can also create ‘file’, ‘password’, and any type supported by HTML5: echo $this->Form->input(’field’, array(’type’ => ’file’)); echo $this->Form->input(’email’, array(’type’ => ’email’)); Output: 112 Chapter 7. Views
- 119. CakePHP Cookbook Documentation,Release 2.x <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 input’s containing div. Using a string value will set the div’s class name. An array will set the div’s attributes to those specified by the array’s 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: <div class="class_name"> <label for="UserName">Name</label> <input name="data[User][name]" type="text" value="" id="UserName" /> </div> 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: More about Views 113
- 120. CakePHP Cookbook Documentation,Release 2.x 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> 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 & field classes set the error key to false: $this->Form->input(’Model.field’, array(’error’ => false)); To disable only the error message, but retain the field 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: 114 Chapter 7. Views
- 121. CakePHP Cookbook Documentation,Release 2.x $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 • $options[’before’], $options[’between’], $options[’separator’], and $options[’after’] 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--’, More about Views 115
- 122. CakePHP Cookbook Documentation,Release 2.x ’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 by 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 find yourself repeating the same options in multiple in- put() calls, you can use inputDefaults‘ to keep your code dry: 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 specific types of inputs In addition to the generic input() method, FormHelper has specific 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. 116 Chapter 7. Views
- 123. CakePHP Cookbook Documentation,Release 2.x 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 class name 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 field. The value is used if the data passed to the form does not contain a value for the field (or if no data is passed at all). Example usage: echo $this->Form->input(’ingredient’, array(’default’ => ’Sugar’)); Example with select field (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 fields’ default values can be set by using the ‘selected’ key. Beware of using false to assign a default value. A false value is used to disable/exclude options of an input field, 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. More about Views 117
- 124. CakePHP Cookbook Documentation,Release 2.x 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 field to blank, use ‘value’ => ‘’ instead. Options can also supplied as key-value pairs. • $options[’hiddenField’] For certain input types (checkboxes, radios) a hidden input is cre- ated so that the key in $this->request->data will exist even without a value specified: <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 first. If the hidden input is on the page in multiple places, only the last group of input’s 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" /> 118 Chapter 7. Views
- 125. CakePHP Cookbook Documentation,Release 2.x <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 field 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 in the order defined by the dateFormat option. • $options[’minYear’], $options[’maxYear’] Used in combination with a date/datetime input. Defines the lower and/or upper end of values shown in the years select field. • $options[’orderYear’] Used in combination with a date/datetime input. Defines the order in which the year values will be set. Valid values include ‘asc’, ‘desc’. The default value is ‘desc’. • $options[’interval’] This option specifies 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. More about Views 119
- 126. CakePHP Cookbook Documentation,Release 2.x • $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-Specific Methods All elements are created under a form for the User model as in the examples above. For this reason, the HTML code generated will contain attributes that reference to the User model. Ex: name=data[User][username], id=UserUsername FormHelper::label(string $fieldName, string $text, array $options) Create a label element. $fieldName is used for generating the DOM id. If $text is undefined, $fieldName will be used to inflect the label’s 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 class name: 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 specific 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’)); Will output: <input name="data[User][username]" type="text" class="users" id="UserUsername" /> FormHelper::password(string $fieldName, array $options) Creates a password field.: echo $this->Form->password(’password’); Will output: 120 Chapter 7. Views
- 127. CakePHP Cookbook Documentation,Release 2.x <input name="data[User][password]" value="" id="UserPassword" type="password" /> FormHelper::hidden(string $fieldName, array $options) Creates a hidden form input. Example: echo $this->Form->hidden(’id’); Will output: <input name="data[User][id]" id="UserId" type="hidden" /> If the form is edited (that is, the array $this->request->data will contain the information saved for the User model), the value corresponding to id field will automatically be added to the HTML generated. Example for data[User][id] = 10: <input name="data[User][id]" id="UserId" type="hidden" /> Changed in version 2.0: Hidden fields no longer remove the class attribute. This means that if there are validation errors on hidden fields, the error-field class name will be applied. FormHelper::textarea(string $fieldName, array $options) Creates a textarea input field.: echo $this->Form->textarea(’notes’); Will output: <textarea name="data[User][notes]" id="UserNotes"></textarea> If the form is edited (that is, the array $this->request->data will contain the information saved for the User model), the value corresponding to notes field will automatically be added to the HTML generated. Example: <textarea name="data[User][notes]" id="UserNotes"> This text is to be edited. </textarea> Note: The textarea input type allows for the $options attribute of ’escape’ which deter- mines 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 specific options: •$options[’rows’], $options[’cols’] These two keys specify the number of rows and columns: More about Views 121
- 128. CakePHP Cookbook Documentation,Release 2.x echo $this->Form->textarea( ’textarea’, array(’rows’ => ’5’, ’cols’ => ’5’) ); Output: <textarea name="data[Form][textarea]" cols="5" rows="5" id="FormTextarea"> </textarea> FormHelper::checkbox(string $fieldName, array $options) Creates a checkbox form element. This method also generates an associated hidden form input to force the submission of data for the specified field.: 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 don’t 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 $fieldName, 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 first 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 legend and fieldset by de- fault. Set $attributes[’legend’] to false to remove them.: 122 Chapter 7. Views
- 129. CakePHP Cookbook Documentation,Release 2.x $options = array(’M’ => ’Male’, ’F’ => ’Female’); $attributes = array(’legend’ => false); echo $this->Form->radio(’gender’, $options, $attributes); Will output: <input name="data[User][gender]" id="UserGender_" value="" type="hidden" /> <input name="data[User][gender]" id="UserGenderM" value="M" type="radio" /> <label for="UserGenderM">Male</label> <input name="data[User][gender]" id="UserGenderF" value="F" type="radio" /> <label for="UserGenderF">Female</label> If for some reason you don’t 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 $fieldName, array $options, array $attributes) Creates a select element, populated with the items in $options, with the option specified by $attributes[’value’] shown as selected by default. Set the ‘empty’ key in the $attributes variable to false 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 specified 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> More about Views 123
- 130. CakePHP Cookbook Documentation,Release 2.x <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’, ’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 fieldsets: $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’, 124 Chapter 7. Views
- 131. CakePHP Cookbook Documentation,Release 2.x $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’ )); 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="checkbox"> <label for="ModelField1">Label 1</label> </div> <div class="checkbox"> <input name="data[Model][field][]" value="Value 2" id="ModelField2" type="checkbox"> <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="ModelField1" type="checkbox"> <label for="ModelField1">Label 1</label> More about Views 125
- 132. CakePHP Cookbook Documentation,Release 2.x </div> <div class="checkbox"> <input name="data[Model][field][]" value="Value 2" id="ModelField2" type="checkbox"> <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 $fieldName, array $options) To add a file upload field to a form, you must first 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 file: 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 fields of type ‘file’. Each time the form is displayed, the value inside will be empty. Upon submission, file fields 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 file fields read the PHP manual section on file uploads2. 2 http://php.net/features.file-upload 126 Chapter 7. Views
- 133. CakePHP Cookbook Documentation,Release 2.x Validating Uploads Below is an example validation method you could define in your model to validate whether a file 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 file 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"> Note: When using $this->Form->file(), remember to set the form encoding-type, by setting the type option to ‘file’ 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 specified title and a default type of “button”. Setting More about Views 127
- 134. CakePHP Cookbook Documentation,Release 2.x $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 $this->Form->button(’A Button’); echo $this->Form->button(’Another Button’, array(’type’ => ’button’)); echo $this->Form->button(’Reset the Form’, array(’type’ => ’reset’)); echo $this->Form->button(’Submit Form’, array(’type’ => ’submit’)); Will output: <button type="submit">A Button</button> <button type="button">Another Button</button> <button type="reset">Reset the Form</button> <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: 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 $con- firmMessage = 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. Changed in version 2.5: The inline and block options were added. They allow buffering the generated form tag, instead of returning with the link. This helps avoiding nested form tags. Setting ’inline’ => true will add the form tag to postLink content block or you can use option block to specify a custom block. 128 Chapter 7. Views
- 135. CakePHP Cookbook Documentation,Release 2.x Creating date and time inputs FormHelper::dateTime($fieldName, $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 fields with the current datetime. FormHelper::year(string $fieldName, 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> FormHelper::month(string $fieldName, 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> More about Views 129
- 136. CakePHP Cookbook Documentation,Release 2.x <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’, array(’monthNames’ => false)); FormHelper::day(string $fieldName, 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 first option is ‘Day’), you can supply the text as the final 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 $fieldName, boolean $format24Hours, array $attributes) Creates a select element populated with the hours of the day. FormHelper::minute(string $fieldName, array $attributes) Creates a select element populated with the minutes of the hour. FormHelper::meridian(string $fieldName, array $attributes) Creates a select element populated with ‘am’ and ‘pm’. Displaying and checking errors FormHelper::error(string $fieldName, mixed $text, array $options) Shows a validation error message, specified by $text, for the given field, 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 class name for the error message FormHelper::isFieldError(string $fieldName) Returns true if the supplied $fieldName has an active validation error.: 130 Chapter 7. Views
- 137. CakePHP Cookbook Documentation,Release 2.x 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 field described by the current entity has no errors. Otherwise it returns the validation message. Setting Defaults for all fields 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’ // has a label element same defaults echo $this->Form->input( ’username’, array(’label’ => ’Username’) ); Working with SecurityComponent SecurityComponent offers several features that make your forms safer and more secure. By simply including the SecurityComponent in your controller, you’ll automatically benefit 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 field making it exempt from the SecurityComponent field hashing. This also allows the fields to be manipulated by JavaScript. The $name parameter should be the entity name for the input: More about Views 131
- 138. CakePHP Cookbook Documentation,Release 2.x $this->Form->unlockField(’User.id’); FormHelper::secure(array $fields = array()) Generates a hidden field with a security hash based on the fields 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 simplifies 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 pa- rameters. You can override this default by supplying $options[’url’] in the second parameter of $this->Form->create() FormHelper::hidden() Hidden fields no longer remove the class attribute. This means that if there are validation errors on hidden fields, the error-field class name will be applied. 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 flexible 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: 132 Chapter 7. Views
- 139. CakePHP Cookbook Documentation,Release 2.x 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 you’re getting an error informing you that it isn’t there, it’s usually due to its name being missing from a manually configured $helpers controller variable. Inserting Well-Formatted elements The most important task the HtmlHelper accomplishes is creating well formed markup. Don’t 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 document’s 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: <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 file to link, or an array with multiple files • $options (array) – An array of options or html attributes. More about Views 133
- 140. CakePHP Cookbook Documentation,Release 2.x 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 file specified resides inside the /app/webroot/css directory if path doesn’t start with a ‘/’.: echo $this->Html->css(’forms’); Will output: <link rel="stylesheet" type="text/css" href="/css/forms.css" /> The first parameter can be an array to include multiple files.: 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 files 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 file 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: .. versionchanged:: 2.4 echo $this->Html->css(‘Blog.common.css’, 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. • $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 you’d 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). 134 Chapter 7. Views
- 141. CakePHP Cookbook Documentation,Release 2.x If you set the “type” attribute using the $attributes parameter, CakePHP contains a few shortcuts: type translated value html text/html rss application/rss+xml atom application/atom+xml icon 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" /> <?php echo $this->Html->meta( ’description’, ’enter any meta description here’ ); ?> // Output More about Views 135
- 142. CakePHP Cookbook Documentation,Release 2.x <meta name="description" content="enter any meta description here" /> If you want to add a custom meta tag then the first 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 translated value html4-strict HTML4 Strict html4-trans HTML4 Transitional html4-frame HTML4 Frameset html5 HTML5 xhtml-strict XHTML1 Strict xhtml-trans XHTML1 Transitional xhtml-frame XHTML1 Frameset xhtml11 XHTML1.1 echo $this->Html->docType(); // Outputs: // <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" // "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> 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.w3.org/TR/html4/loose.dtd"> 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 definitions based on the keys and values of the array passed to the method. Especially handy if your CSS file is dynamic.: echo $this->Html->style(array( ’background’ => ’#633’, ’border-bottom’ => ’1px solid #000’, 136 Chapter 7. Views
- 143. CakePHP Cookbook Documentation,Release 2.x ’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 files 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 file 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: More about Views 137
- 144. 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 $confir- mMessage = 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’ => ’_blank’) ); 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 delete this recipe?’ );"> 138 Chapter 7. Views
- 145. CakePHP Cookbook Documentation,Release 2.x Delete </a> 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: <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> More about Views 139
- 146. CakePHP Cookbook Documentation,Release 2.x 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. HtmlHelper::media(string|array $path, array $options) Parameters • $path (string|array) – Path to the video file, relative to the web- root/{$options[’pathPrefix’]} 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 file’s mime type. – text Text to include inside the video tag – pathPrefix Path prefix to use for relative URLs, defaults to ‘files/’ – 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 140 Chapter 7. Views
- 147. CakePHP Cookbook Documentation,Release 2.x <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=’theora, vorbis’" ) ), 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. Returns text wrapped in a specified tag. If no text is specified 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 More about Views 141
- 148. CakePHP Cookbook Documentation,Release 2.x • $class (string) – The class name 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 first parameter specifies 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 specified, 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 class name for the paragraph. • $text (string) – The content inside the paragraph. • $options (array) – An array of html attributes. 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 file, or an array of strings for multiple files. • $options (array) – An array of html attributes. Include a script file(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. 142 Chapter 7. Views
- 149. CakePHP Cookbook Documentation,Release 2.x 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 file inclusion assumes that the JavaScript file specified 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 files with absolute paths as well to link files 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 first parameter can be an array to include multiple files.: 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 specific 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 files 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 file 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. More about Views 143
- 150. CakePHP Cookbook Documentation,Release 2.x 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 defined 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: $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 = ar- ray(), 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’, 144 Chapter 7. Views
- 151. CakePHP Cookbook Documentation,Release 2.x ’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) 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: More about Views 145
- 152. CakePHP Cookbook Documentation,Release 2.x <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. • $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 specific <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> 146 Chapter 7. Views
- 153. CakePHP Cookbook Documentation,Release 2.x echo $this->Html->tableCells(array( array( ’Jul 7th, 2007’, array( ’Best Brownies’, array(’class’ => ’highlight’) ), ’Yes’), 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> More about Views 147
- 154. CakePHP Cookbook Documentation,Release 2.x 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. • $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 a 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", 148 Chapter 7. Views
- 155. CakePHP Cookbook Documentation,Release 2.x "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" )); // Output /posts/search?foo=bar#first For further information check Router::url3 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 $configFile, 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 config file containing the tags you’d 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">’, 3 http://api.cakephp.org/2.4/class-Router.html#_url More about Views 149
- 156. CakePHP Cookbook Documentation,Release 2.x ’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|array|bool $startText = false) CakePHP has the built-in ability to automatically create a breadcrumb trail in your app. To set this up, first 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 first link: 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 you’ll 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’, array(’controller’ => ’users’, ’action’ => ’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’, ‘firstClass’, ‘lastClass’ and ‘escape’ 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 first breadcrumb link/text. This is useful when you al- ways want to include a root link. This option works the same as the $startText option for getCrumbs(). 150 Chapter 7. Views
- 157. CakePHP Cookbook Documentation,Release 2.x Changed in version 2.1: The $startText parameter was added. Changed in version 2.3: The ‘separator’, ‘firstClass’ and ‘lastClass’ options were added. Changed in version 2.5: The ‘escape’ option was added. JsHelper class JsHelper(View $view, array $settings = array()) Warning: The JsHelper is currently deprecated and completely removed in 3.x. We recommend using regular JavaScript and directly interacting with JavaScript libraries where possible. Since the beginning CakePHP’s support for JavaScript has been with Prototype/Scriptaculous. While we still think these are excellent JavaScript libraries, 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. 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 flexibility they need to address their specific application needs. JavaScript Engines form the backbone of the new JsHelper. A JavaScript engine translates an abstract JavaScript element into concrete JavaScript code specific to the JavaScript library being used. In addition they create an extensible system for others to use. Using a specific 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: echo $this->Html->script(’jquery’); // Include jQuery library Replace jquery with the name of your library file (.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 specific 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. More about Views 151
- 158. CakePHP Cookbook Documentation,Release 2.x 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 shouldn’t 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 cus- tomHelper: public $helpers = array(’Js’); Note: It is not possible to declare a JavaScript engine inside a custom helper. Doing that will have no effect. 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: Be sure to declare the JsHelper and its engine on top of the $helpers array in your controller. 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 fit your JavaScript library. Creating a JavaScript Engine JavaScript engine helpers follow normal helper conventions, with a few additional restrictions. They must have the Engine suffix. 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). 152 Chapter 7. Views
- 159. CakePHP Cookbook Documentation,Release 2.x The JsHelper by default buffers almost all script code generated, allowing you to collect scripts through- out 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 JavaScript libraries can change, a common set of options is supported by JsHelper, these common options will be mapped out to the library specific options 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 file 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 files. JsHelper::writeBuffer($options = array()) Writes all JavaScript generated so far to a code block or caches them to a file 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 file 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) More about Views 153
- 160. CakePHP Cookbook Documentation,Release 2.x Creating a cache file 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 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 specific options. This is done to provide end developers with as unified 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. 154 Chapter 7. Views
- 161. CakePHP Cookbook Documentation,Release 2.x 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 final position. •opacity - Opacity of the placeholder •distance - Distance a sortable must be dragged before sorting starts. Event Options •start - Event fired when sorting starts •sort - Event fired during sorting •complete - Event fired 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, stop:onStop }); JsHelper::request($url, $options = array()) Generate a JavaScript snippet to create an XmlHttpRequest or ‘AJAX’ request. More about Views 155
- 162. CakePHP Cookbook Documentation,Release 2.x Event Options •complete - Callback to fire on complete. •success - Callback to fire on success. •before - Callback to fire on request initialization. •error - Callback to fire 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 eval’ed. •dataExpression - Should the data key be treated as a callback. Useful for supplying $options[’data’] as another JavaScript expression. Example use: $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. 156 Chapter 7. Views
- 163. CakePHP Cookbook Documentation,Release 2.x •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 fired when the drag starts •drag - Event fired on every step of the drag •stop - Event fired 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 $("#element").draggable({ containment:"#content", drag:onDrag, grid:[10,10], start:onStart, stop:onStop }); 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 fired when an element is dropped into the drop zone. •hover - Event fired when a drag enters a drop zone. •leave - Event fired 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’, More about Views 157
- 164. CakePHP Cookbook Documentation,Release 2.x ’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 imple- mentation 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. Events •change - Fired when the slider’s 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 )); 158 Chapter 7. Views
- 165. CakePHP Cookbook Documentation,Release 2.x 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:onComplete, value:2 }); 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 event type if your library supports them. $content should contain the function body for the call- back. 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: More about Views 159
- 166. CakePHP Cookbook Documentation,Release 2.x $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.: $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?’); 160 Chapter 7. Views
- 167. CakePHP Cookbook Documentation,Release 2.x 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 files. 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 - Confirm message displayed before sending the request. Using confirm, 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 both FormHelper::submit() and JsHelper::request() when using submit. 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. Options •confirm - Generate a confirm() 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. More about Views 161
- 168. CakePHP Cookbook Documentation,Release 2.x 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: <a href="/posts/index/page:2" other="value">Page 2</a> 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. 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: 162 Chapter 7. Views
- 169. CakePHP Cookbook Documentation,Release 2.x public $components = array(’RequestHandler’); public $helpers = array(’Js’); Next link in the JavaScript library you want to use. For this example we’ll 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, call the options() at the top of your view: $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 file. 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 don’t 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 $this->fetch(’content’); ?> </div> <?php echo $this->Html->image( ’indicator.gif’, array(’id’ => ’busy-indicator’) ); ?> </body> </html> More about Views 163
- 170. CakePHP Cookbook Documentation,Release 2.x Remember to place the indicator.gif file 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 file. With the above layout, we’ve included an indicator image file, 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’ => false) ), )); 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 convenient methods that enable display numbers in common formats in your views. These methods include ways to format currency, percentages, data sizes, format numbers to specific precisions and also to give you more flexibility 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 = ar- ray()) Parameters • $number (float) – 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: 164 Chapter 7. Views
- 171. CakePHP Cookbook Documentation,Release 2.x // called as NumberHelper echo $this->Number->currency($number, $currency); // called as CakeNumber App::uses(’CakeNumber’, ’Utility’); echo CakeNumber::currency($number, $currency); The first parameter, $number, should be a floating point number that represents the amount of money you are expressing. The second parameter is used to choose a predefined currency formatting scheme: $currency 1234.56, formatted by currency type EUR C1.234,56 GBP £1,234.56 USD $1,234.56 The third parameter is an array of options for further defining the output. The following options are available: Option Description before The currency symbol to place before whole numbers ie. ‘$’ after The currency symbol to place after decimal numbers ie. ‘c’. Set to boolean false to use no decimal symbol. eg. 0.35 => $0.35. zero The text to use for zero values, can be a string or a number. ie. 0, ‘Free!’ places Number of decimal places to use. ie. 2 thousands Thousands separator ie. ‘,’ decimals Decimal separator symbol ie. ‘.’ negative Symbol for negative numbers. If equal to ‘()’, the number will be wrapped with ( and ) escape Should the output be htmlentity escaped? Defaults to true wholeSym- bol String to use for whole numbers ie. ‘ dollars’ wholePosi- tion Either ‘before’ or ‘after’ to place the whole symbol fraction- Symbol String to use for fraction numbers ie. ‘ cents’ fractionPo- sition Either ‘before’ or ‘after’ to place the fraction symbol fractionEx- ponent Fraction exponent of this specific 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’); More about Views 165
- 172. CakePHP Cookbook Documentation,Release 2.x 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 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. Uses the same $options keys as CakeNumber::currency(). Add a currency format to the Number helper. Makes reusing currency formats easier: // called as NumberHelper $this->Number->addFormat(’BRL’, array(’before’ => ’R$’, ’thousands’ => ’.’, ’decimals’ // called as CakeNumber App::uses(’CakeNumber’, ’Utility’); CakeNumber::addFormat(’BRL’, array(’before’ => ’R$’, ’thousands’ => ’.’, ’decimals’ => You can now use BRL as a short form when formatting currency amounts: // called as NumberHelper echo $this->Number->currency($value, ’BRL’); // called as CakeNumber App::uses(’CakeNumber’, ’Utility’); echo CakeNumber::currency($value, ’BRL’); Added formats are merged with the following defaults: array( ’wholeSymbol’ => ’’, ’wholePosition’ => ’before’, ’fractionSymbol’ => false, ’fractionPosition’ => ’after’, ’zero’ => 0, ’places’ => 2, ’thousands’ => ’,’, ’decimals’ => ’.’, ’negative’ => ’()’, ’escape’ => true, ’fractionExponent’ => 2 ) 166 Chapter 7. Views
- 173. CakePHP Cookbook Documentation,Release 2.x NumberHelper::precision(mixed $number, int $precision = 3) Parameters • $number (float) – The value to covert • $precision (integer) – The number of decimal places to display This method displays a number with the specified amount of precision (decimal places). It will round in order to maintain the level of precision defined.: // called as NumberHelper echo $this->Number->precision(456.91873645, 2); // 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 = ar- ray()) Parameters • $number (float) – The value to covert. • $precision (integer) – The number of decimal places to display. • $options (array) – Options, see below. Option Description multi- ply 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 More about Views 167
- 174. CakePHP Cookbook Documentation,Release 2.x • $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. 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 $op- tions 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 168 Chapter 7. Views
- 175. CakePHP Cookbook Documentation,Release 2.x –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’ => ’.’, ’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 $op- tions 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’ => ’.’, More about Views 169
- 176. CakePHP Cookbook Documentation,Release 2.x ’thousands’ => ’,’ )); // output ’+123,456.79’ // called as CakeNumber App::uses(’CakeNumber’, ’Utility’); echo CakeNumber::formatDelta(’123456.7890’, array( ’places’ => 2, ’decimals’ => ’.’, ’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 inflection. • $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 first click, links generated with sort() will handle direction switching auto- matically. Link sorting default by ‘asc’. If the resultset is sorted ‘asc’ by the specified 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(). • direction The default direction to use when this link isn’t active. 170 Chapter 7. Views
- 177. CakePHP Cookbook Documentation,Release 2.x • lock Lock direction. Will only use the default direction then, defaults to false. New in version 2.5: You can now set the lock option to true in order to lock the sorting direction into the specified direction. 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: 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 automat- ically 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> The lock option can be used to lock sorting into the specified direction: echo $this->Paginator->sort(’user_id’, null, array(’direction’ => ’asc’, ’lock’ => true)); 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. More about Views 171
- 178. CakePHP Cookbook Documentation,Release 2.x 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 first links generated, set to an integer to define the number of ‘first’ links to generate. Defaults to false. If a string is set a link to the first page will be generated with the value as the title: echo $this->Paginator->numbers(array(’first’ => ’First page’)); • last Whether you want last links generated, set to an integer to define 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 class name used on the wrapping tag. • currentClass The class name 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 first 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 first 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. 172 Chapter 7. Views
- 179. CakePHP Cookbook Documentation,Release 2.x Creating jump links In addition to generating links that go directly to specific page numbers, you’ll often want links that go to the previous and next links, first 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 you’re already on the first 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. •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’ => ’prev disabled’) ); 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"> << previous </a> </span> If there were no previous pages you would get: <span class="prev disabled"><< previous</span> You can change the wrapping tag using the tag option: echo $this->Paginator->prev(__(’previous’), array(’tag’ => ’li’)); More about Views 173
- 180. CakePHP Cookbook Documentation,Release 2.x Output: <li class="prev"> <a rel="prev" href="/posts/index/page:1/sort:title/order:desc"> previous </a> </li> 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 </a> 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, $dis- abledOptions = 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($first = ‘<< first’, $options = array()) Returns a first or set of numbers for the first pages. If a string is given, then only a link to the first page with the provided text will be created: echo $this->Paginator->first(’< first’); The above creates a single link for the first page. Will output nothing if you are on the first page. You can also use an integer to indicate how many first paging links you want generated: echo $this->Paginator->first(3); The above will create links for the first 3 pages, once you get to the third or greater page. Prior to that nothing will be output. 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 ‘...’ 174 Chapter 7. Views
- 181. CakePHP Cookbook Documentation,Release 2.x 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 first 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 specific 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 first record being displayed. – {:end} - number of the last record being displayed. – {: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}’ ); More about Views 175
- 182. CakePHP Cookbook Documentation,Release 2.x 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’ ) )); The above adds the en route parameter to all links the helper will generate. It will also create links with specific sort, direction and page values. By default PaginatorHelper will merge in all of the current pass and named parameters. So you don’t have to do that in each view file. • escape Defines if the title field 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 specified, regular links will be created: 176 Chapter 7. Views
- 183. CakePHP Cookbook Documentation,Release 2.x $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 being paginated, defaults to PaginatorHelper::defaultModel(). 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 configuration 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’) )); Configuring the PaginatorHelper to use a JavaScript helper By default the PaginatorHelper uses JsHelper to do AJAX features. However, if you don’t 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 It’s 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 doesn’t always need to be restricted as such. See the details on PaginatorHelper4 in the API. As mentioned, the PaginatorHelper also offers sorting fea- tures which can be easily integrated into your table column headers: // app/View/Posts/index.ctp <table> <tr> <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> 4 http://api.cakephp.org/2.4/class-PaginatorHelper.html More about Views 177
- 184. CakePHP Cookbook Documentation,Release 2.x <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 field. 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 final 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}’ )); 178 Chapter 7. Views
- 185. CakePHP Cookbook Documentation,Release 2.x Other Methods PaginatorHelper::link($title, $url = array(), $options = array()) 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 Would create a link pointing at ‘/posts/index/page:5/sort:title/direction:desc’ 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 More about Views 179
- 186. CakePHP Cookbook Documentation,Release 2.x [nextPage] => 3 [pageCount] => 3 [order] => [limit] => 20 [options] => Array ( [page] => 2 [conditions] => Array ( ) ) [paramType] => named ) */ PaginatorHelper::param(string $key, string $model = null) Gets the specific 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 we’ve 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, first we need to edit the controller to add in the rss-specific code. 180 Chapter 7. Views
- 187. CakePHP Cookbook Documentation,Release 2.x Controller Code It is a good idea to add RequestHandler to your PostsController’s $components array. This will allow a lot of automagic to occur: 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 DESC’) ); return $this->set(compact(’posts’)); } // this is not an Rss request, so deliver // data used by website’s 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, put the following contents in app/View/Layouts/rss/default.ctp: if (!isset($documentData)) { $documentData = array(); } if (!isset($channelData)) { $channelData = array(); } if (!isset($channelData[’title’])) { $channelData[’title’] = $this->fetch(’title’); More about Views 181
- 188. CakePHP Cookbook Documentation,Release 2.x } $channel = $this->Rss->channel(array(), $channelData, $this->fetch(’content’)); echo $this->Rss->document($documentData, $channel); It doesn’t look like much but thanks to the power in the RssHelper it’s doing a lot of lifting for us. We haven’t 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. Next up is view file for my posts/index. Much like the layout file we created, we need to create a View/Posts/rss/ directory and create a new index.ctp inside that folder. The contents of the file 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 Con- troller::set() method. Here though we are passing the channel’s 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 ar- ray 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. 182 Chapter 7. Views
- 189. CakePHP Cookbook Documentation,Release 2.x $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’], ’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 filter 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 configuration 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 field property RssHelper::$helpers Helpers used by the RSS Helper property RssHelper::$here URL to current action More about Views 183
- 190. CakePHP Cookbook Documentation,Release 2.x property RssHelper::$model Name of current model property RssHelper::$params Parameter array property RssHelper::$version Default spec version of generated RSS. 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 $end- Tag = 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 component’s 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: 184 Chapter 7. Views
- 191. CakePHP Cookbook Documentation,Release 2.x array(’User’ => array( ’username’ => ’[email protected]’ )); Given the previous array structure, the node would be accessed by User.username, with the dot in- dicating the nested array. This notation is used for all Session helper methods wherever a $key is used. SessionHelper::read(string $key) 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 whether a key is in the Session. Returns a boolean representing the key’s existence. SessionHelper::error() Return type string Returns last error encountered in a session. SessionHelper::valid() Return type boolean Used to check whether a session is valid in a view. Displaying notifications or flash messages SessionHelper::flash(string $key = ‘flash’, array $params = array()) Return type string As explained in Creating notification messages, you can create one-time notifications 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.’); More about Views 185
- 192. CakePHP Cookbook Documentation,Release 2.x When outputting this message, you can choose the element used to display the 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. The failure element would contain something like this: <div class="flash flash-failure"> <?php echo h($message); ?> </div> You can also pass additional parameters into the flash() method, which allows 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 escape the HTML in flash messages. If you are using any request or user data in your flash messages, you should escape it with h when formatting your mes- sages. 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 gracefully truncating long stretches of text. Changed in version 2.1: Several TextHelper methods have been moved into the String class to allow easier use outside of the View layer. Within a view, these methods are accessible via the TextHelper class. You can call one 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. 186 Chapter 7. Views
- 193. CakePHP Cookbook Documentation,Release 2.x • $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 defined in $htmlOptions (see HtmlHelper::link()).: $myText = ’For more information regarding our world-famous ’ . ’pastries and desserts, contact [email protected]’; $linkedText = $this->Text->autoLinkEmails($myText); Output: 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 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: As of 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 are found, and <br> where single-line returns are found.: $myText = ’For more information regarding our world-famous pastries and desserts. More about Views 187
- 194. CakePHP Cookbook Documentation,Release 2.x 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. • $needle (string) – The string to find. • $options (array) – An array of options, see below. Highlights $needle in $haystack using the $options[’format’] string specified or a de- fault 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="highlight">1</span>’) ); // called as String App::uses(’String’, ’Utility’); echo String::highlight( $lastSentence, ’using’, array(’format’ => ’<span class="highlight">1</span>’) ); 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) 188 Chapter 7. Views
- 195. CakePHP Cookbook Documentation,Release 2.x Parameters • $text (string) – The text to truncate. • $length (int) – The length, in characters, beyond which the text should be trun- cated. • $options (array) – An array of options to use. If $text is longer than $length characters, this method truncates it at $length and adds a prefix consisting of ’ellipsis’, if defined. If ’exact’ is passed as false, the truncation will occur at the first whitespace after the point at which $length is exceeded. 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.’, 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 More about Views 189
- 196. CakePHP Cookbook Documentation,Release 2.x • $text (string) – The text to truncate. • $length (int) – The length, in characters, beyond which the text should be trun- cated. • $options (array) – An array of options to use. If $text is longer than $length characters, this method removes an initial substring with length consisting of the difference and prepends a suffix consisting of ’ellipsis’, if defined. If ’exact’ is passed as false, the truncation will occur at the first whitespace prior to the point at which truncation would otherwise take place. $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: $sampleText = ’I packed my bag and in it I put a PSP, a PS3, a TV, ’ . ’a C# program that can divide by zero, death metal t-shirts’ // called as TextHelper echo $this->Text->tail( $sampleText, 70, array( ’ellipsis’ => ’...’, ’exact’ => false ) ); // called as String App::uses(’String’, ’Utility’); echo String::tail( $sampleText, 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 $ellip- sis=”...”) Parameters 190 Chapter 7. Views
- 197. CakePHP Cookbook Documentation,Release 2.x • $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 prefix/suffix 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’.: // 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). More about Views 191
- 198. CakePHP Cookbook Documentation,Release 2.x 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 user’s 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 appli- cation’s time zone is set to GMT+0. Next add a time zone field to your users table and make the necessary modifications 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 h:i A’, $post[’Post’][’created’], null, $user[’User’][’time_zone’] ); // Will display August 22nd, 2011 11:53 PM for a user in GMT+0 // August 22nd, 2011 03:53 PM for a user in GMT-8 // and August 23rd, 2011 09:53 AM GMT+10 Most of the Time Helper methods have a $timezone parameter. The $timezone parameter accepts a valid timezone identifier string or an instance of DateTimeZone class. Formatting TimeHelper::convert($serverTime, $timezone = NULL) Return type integer Converts given time (in server’s time zone) to user’s 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 192 Chapter 7. Views
- 199. CakePHP Cookbook Documentation,Release 2.x Converts a string representing the format for the function strftime and returns a windows safe and i18n aware format. TimeHelper::dayAsSql($dateString, $field_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, $fieldName, $timezone = NULL) Return type string Returns a string in the format “($field_name >= ‘2008-01-21 00:00:00’) AND ($field_name <= ‘2008- 01-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. TimeHelper::format($date, $format = NULL, $default = false, $timezone = NULL) Return type string Will return a string formatted to the given format using the PHP strftime() formatting options5: // called via TimeHelper echo $this->Time->format(’2011-08-22 11:53:00’, ’%B %e, %Y %H:%M %p’); // August 22, 2011 11:53 AM echo $this->Time->format(’+2 days’, ’%c’); 5 http://www.php.net/manual/en/function.strftime.php More about Views 193
- 200. CakePHP Cookbook Documentation,Release 2.x // 2 days from now formatted as Sun, 13 Nov 2011 03:36:10 AM EET // called as CakeTime App::uses(’CakeTime’, ’Utility’); echo CakeTime::format(’2011-08-22 11:53:00’, ’%B %e, %Y %H:%M %p’); echo CakeTime::format(’+2 days’, ’%c’); You can also provide the date/time as the first 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 be- low. $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 strtotime6 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’); 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).: 6 http://us.php.net/manual/en/function.date.php 194 Chapter 7. Views
- 201. CakePHP Cookbook Documentation,Release 2.x // 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 file is used. For more info about LC_TIME file 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’); 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() More about Views 195
- 202. CakePHP Cookbook Documentation,Release 2.x Return type integer Returns server’s offset from GMT in seconds. TimeHelper::timeAgoInWords($dateString, $options = array()) Return type string Will take a datetime string (anything that is parsable by PHP’s strtotime() function or MySQL’s date- time 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 // on August 22nd, 2011 echo $this->Time->timeAgoInWords( ’Aug 22, 2011’, array(’format’ => ’F jS, Y’) ); // 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’ => ’+1 year’) ); // 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’ => ’+1 year’) ); 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. 196 Chapter 7. Views
- 203. CakePHP Cookbook Documentation,Release 2.x 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: $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 More about Views 197
- 204. CakePHP Cookbook Documentation,Release 2.x 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 server’s timezone. TimeHelper::timezone($timezone = NULL) Return type DateTimeZone New in version 2.2: Returns a timezone object from a string or the user’s timezone object. If the function is called without a parameter it tries to get timezone from ‘Config.timezone’ configuration variable. TimeHelper::listTimezones($filter = null, $country = null, $group = true) Return type array New in version 2.2: Returns a list of timezone identifiers. 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: 198 Chapter 7. Views
- 205. CakePHP Cookbook Documentation,Release 2.x // 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 Configuring 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 controller’s $helpers array: 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 to the other actions in the controller. This saves processing power for the other actions that do not use the helper and helps 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 it 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: More about Views 199
- 206. CakePHP Cookbook Documentation,Release 2.x 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( ’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 configure your helpers and keep configuration logic out of your controller actions. If you have configuration options that cannot be included as part of a class declaration, you can set those in your controller’s beforeRender callback: class PostsController extends AppController { public function beforeRender() { parent::beforeRender(); $this->helpers[’CustomStuff’] = $this->_getCustomStuffSettings(); } } Using Helpers Once you’ve configured 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 200 Chapter 7. Views
- 207. CakePHP Cookbook Documentation,Release 2.x 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 view’s 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. Creating Helpers If a core helper (or one showcased on GitHub or in the Bakery) doesn’t fit your needs, helpers are easy to create. Let’s say we wanted to create a helper that could be used to output a specifically crafted CSS-styled link you needed many different places in your application. In order to fit your logic into CakePHP’s existing helper structure, you’ll need to create a new class in /app/View/Helper. Let’s call our helper LinkHelper. The actual PHP class file 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 { More about Views 201
- 208. CakePHP Cookbook Documentation,Release 2.x 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 you’ve created your helper and placed it in /app/View/Helper/, you’ll be able to include it in your controllers using the special variable $helpers: 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: <!-- make a link using the new 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($file) Resolve a file name to the webroot of the application. If a theme is active and the file exists in the current theme’s webroot, the path to the themed file will be returned. 202 Chapter 7. Views
- 209. CakePHP Cookbook Documentation,Release 2.x Helper::url($url, $full = false) Generates an HTML escaped URL, delegates to Router::url(). Helper::value($options = array(), $field = 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 field. 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 file is rendered. This includes elements, views, parent views and layouts. Helper::afterRenderFile($viewFile, $content) Is called after each view file 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 controller’s beforeRender method but before the con- troller renders view and layout. Receives the file 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 filename as an argument. Helper::afterLayout($layoutFile) Is called after layout rendering is complete. Receives the layout filename as an argument. More about Views 203
- 210. CakePHP Cookbook Documentation,Release 2.x 204 Chapter 7. Views
- 211. CHAPTER 8 Models Models arethe classes that form the business layer in your application. They should be responsible for managing almost everything regarding your data, its validity, and its interactions, as well as the evolution of the information workflow in your domain. Usually, model classes represent data and are used in CakePHP applications for data access. They generally represent a database table but can be used to access anything that manipulates data such as files, external web services, or iCal events. A model can be associated with other models. For example, a Recipe may be associated with an Author as well as an Ingredient. 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. It will explain the different ways to build associations for your data. It will describe how to find, save, and delete data. Finally, it will look at Datasources. Understanding Models A Model represents your data model. In object-oriented programming, a data model is an object that rep- resents a thing such as 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 definition in CakePHP: App::uses(’AppModel’, ’Model’); class Ingredient extends AppModel { public $name = ’Ingredient’; } With just this simple declaration, the Ingredient model is endowed with all the functionality you need to create queries and to save and delete data. These methods come from CakePHP’s Model class by the magic of inheritance. The Ingredient model extends the application model, AppModel, which in turn extends 205
- 212. CakePHP Cookbook Documentation,Release 2.x CakePHP’s internal Model class. It is this core Model class that bestows the functionality onto your In- gredient model. App::uses(’AppModel’, ’Model’) ensures that the model is loaded when it is needed. The intermediate class, AppModel, is empty. If you haven’t created your own, it is taken from the CakePHP core folder. Overriding the AppModel allows you to define functionality that should be made available to all models within your application. To do so, you need to create your own AppModel.php file that resides in the Model folder, as do all other models in your application. Creating a project using Bake will automatically generate this file 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 file in the /app/Model/ directory. By convention, it should have the same name as the class, which for this example will be Ingredient.php. Note: CakePHP will dynamically create a model object for you if it cannot find a corresponding file in /app/Model. This also means that if your model file isn’t named correctly (for instance, if it is named ingredient.php or Ingredients.php rather than Ingredient.php), CakePHP will use an instance of AppModel rather than your model file (which CakePHP assumes is missing). If you’re trying to use a method you’ve defined in your model, or a behavior attached to your model, and you’re getting SQL errors that are the name of the method you’re calling, it’s a sure sign that CakePHP can’t find your model and you need to check the file names, your application cache, or both. Note: Some class names are not usable for model names. For instance, “File” cannot be used, since “File” is a class that already exists in the CakePHP core. When your model is defined, 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 associa- tion 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 defined, take a 206 Chapter 8. Models
- 213. CakePHP Cookbook Documentation,Release 2.x look at the Associations section 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. Defining 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. Defining 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, define, 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 Association Type Example one to one hasOne A user has one profile. one to many hasMany A user can have multiple recipes. many to one belongsTo Many recipes belong to a user. many to many hasAndBelongsToMany Recipes have, and belong to, many ingredients. Associations are defined by creating a class variable named after the association you are defining. The class variable can sometimes be as simple as a string, but can be as complex as a multidimensional array used to define association specifics. 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 first instance of the word ‘Recipe’ is what is termed an ‘Alias’. This is an identifier for the relationship, and can be anything you choose. Usually, you will choose the same name as the class More on models 207
- 214. CakePHP Cookbook Documentation,Release 2.x that it references. However, aliases for each model must be unique across the app. For example, it is appropriate to have: 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’, ) 208 Chapter 8. Models
- 215. 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. CakePHP 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 associa- tions: $this->User->Recipe->someFunction(); Note: Remember that associations are defined ‘one way’. If you define User hasMany Recipe, that has no effect on the Recipe Model. You need to define Recipe belongsTo User to be able to access the User model from your Recipe model. hasOne Let’s set up a User model with a hasOne relationship to a Profile 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 profiles table will contain a field called user_id. The basic pattern is: hasOne: the other model contains the foreign key. Relation Schema Apple hasOne Banana bananas.apple_id User hasOne Profile profiles.user_id Doctor hasOne Mentor mentors.doctor_id Note: It is not mandatory to follow CakePHP conventions. You can easily override the use of any for- eignKey in your associations definitions. Nevertheless, sticking to conventions will make your code less repetitive and easier to read and maintain. The User model file will be saved in /app/Model/User.php. To define the ‘User hasOne Profile’ association, add the $hasOne property to the model class. Remember to have a Profile model in /app/Model/Profile.php, or the association won’t work: class User extends AppModel { public $hasOne = ’Profile’; } There are two ways to describe this relationship in your model files. The simplest method is to set the $hasOne attribute to a string containing the class name of the associated model, as we’ve done above. More on models 209
- 216. CakePHP Cookbook Documentation,Release 2.x If you need more control, you can define your associations using array syntax. For example, you might want to limit the association to include only certain records. 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 class name of the model being associated to the current model. If you’re defining a ‘User hasOne Profile’ relationship, the className key should equal ‘Profile’. • foreignKey: the name of the foreign key found in the other model. This is especially handy if you need to define multiple hasOne relationships. The default value for this key is the underscored, singular name of the current model, suffixed with ‘_id’. In the example above, it would default to ‘user_id’. • conditions: an array of find()-compatible conditions or SQL strings such as array(‘Profile.approved’ => true) • fields: A list of fields to be retrieved when the associated model data is fetched. Returns all fields by default. • order: an array of find()-compatible order clauses or SQL strings such as array(‘Profile.last_name’ => ‘ASC’) • dependent: When the dependent key is set to true, and the model’s 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 Profile. Once this association has been defined, find operations on the User model will also fetch a related Profile 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 210 Chapter 8. Models
- 217. CakePHP Cookbook Documentation,Release 2.x ) ) belongsTo Now that we have Profile data access from the User model, let’s define a belongsTo association in the Profile 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 Schema Banana belongsTo Apple bananas.apple_id Profile belongsTo User profiles.user_id Mentor belongsTo Doctor mentors.doctor_id Tip: If a model(table) contains a foreign key, it belongsTo the other model(table). We can define the belongsTo association in our Profile model at /app/Model/Profile.php using the string syntax as follows: class Profile extends AppModel { public $belongsTo = ’User’; } We can also define a more specific 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 class name of the model being associated to the current model. If you’re defining a ‘Profile 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 define multiple belongsTo relationships. The default value for this key is the underscored, singular name of the other model, suffixed with _id. • conditions: an array of find() compatible conditions or SQL strings such as array(’User.active’ => true) • type: the type of the join to use in the SQL query. The default is ‘LEFT’, which may not fit your needs in all situations. The value ‘INNER’ may be helpful (when used with some conditions) when you want everything from your main and associated models or nothing at all. More on models 211
- 218. CakePHP Cookbook Documentation,Release 2.x • fields: A list of fields to be retrieved when the associated model data is fetched. Returns all fields by default. • order: an array of find() compatible order clauses or SQL strings such as array(’User.username’ => ’ASC’) • counterCache: If set to true, the associated Model will automatically increase or decrease the “[sin- gular_model_name]_count” field in the foreign table whenever you do a save() or delete(). If it’s a string, then it’s the field name to use. The value in the counter field represents the number of related rows. You can also specify multiple counter caches by defining an array. See Multiple counterCache. • counterScope: Optional conditions array to use for updating counter cache field. Once this association has been defined, find operations on the Profile 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 ) ) counterCache - Cache your count() This feature helps you cache the count of related data. Instead of counting the records manually via find(’count’), the model itself tracks any addition/deletion towards the associated $hasMany model and increases/decreases a dedicated integer field within the parent model table. The name of the field consists of the singular model name followed by a underscore and the word “count”: my_model_count Let’s say you have a model called ImageComment and a model called Image. You would add a new INT-field to the images table and name it image_comment_count. Here are some more examples: 212 Chapter 8. Models
- 219. CakePHP Cookbook Documentation,Release 2.x Model Associated Model Example User Image users.image_count Image ImageComment images.image_comment_count BlogEntry BlogEntryComment blog_entries.blog_entry_comment_count Once you have added the counter field, you are good to go. Activate counter-cache in your association by adding a counterCache key and set the value to true: class ImageComment extends AppModel { public $belongsTo = array( ’Image’ => array( ’counterCache’ => true, ) ); } From now on, every time you add or remove a ImageComment associated to Image, the number within image_comment_count is adjusted automatically. counterScope You can also specify counterScope. It allows you to specify a simple condition which tells the model when to update (or when not to, depending on how you look at it) the counter value. Using our Image model example, we can specify it like so: class ImageComment extends AppModel { public $belongsTo = array( ’Image’ => array( ’counterCache’ => ’active_comment_count’, //custom field name // only count if "ImageComment" is active = 1 ’counterScope’ => array( ’ImageComment.active’ => 1 ) ) ); } Multiple counterCache Since 2.0, CakePHP has supported having multiple counterCache in a single model relation. It is also possible to define a counterScope for each counterCache. Assuming you have a User model and a Message model, and you want to be able to count the amount of read and unread messages for each user. Model Field Description User users.messages_read Count read Message User users.messages_unread Count unread Message Message messages.is_read Determines if a Message is read or not. With this setup, your belongsTo would look like this: More on models 213
- 220. CakePHP Cookbook Documentation,Release 2.x class Message extends AppModel { public $belongsTo = array( ’User’ => array( ’counterCache’ => array( ’messages_read’ => array(’Message.is_read’ => 1), ’messages_unread’ => array(’Message.is_read’ => 0) ) ) ); } hasMany Next step: defining a “User hasMany Comment” association. A hasMany association will allow us to fetch a user’s comments when we fetch a User record. When keying your database tables for a hasMany relationship, follow this convention: hasMany: the other model contains the foreign key. Relation Schema User hasMany Comment Comment.user_id Cake hasMany Virtue Virtue.cake_id Product hasMany Option Option.product_id We can define the hasMany association in our User model at /app/Model/User.php using the string syntax as follows: class User extends AppModel { public $hasMany = ’Comment’; } We can also define a more specific relationship using array syntax: class User extends AppModel { public $hasMany = array( ’Comment’ => array( ’className’ => ’Comment’, ’foreignKey’ => ’user_id’, ’conditions’ => array(’Comment.status’ => ’1’), ’order’ => ’Comment.created DESC’, ’limit’ => ’5’, ’dependent’ => true ) ); } Possible keys for hasMany association arrays include: • className: the class name of the model being associated to the current model. If you’re defining a ‘User hasMany Comment’ relationship, the className key should equal ‘Comment.’ 214 Chapter 8. Models
- 221. CakePHP Cookbook Documentation,Release 2.x • foreignKey: the name of the foreign key found in the other model. This is especially handy if you need to define multiple hasMany relationships. The default value for this key is the underscored, singular name of the actual model, suffixed with ‘_id’. • conditions: an array of find() compatible conditions or SQL strings such as array(‘Comment.visible’ => true) • order: an array of find() compatible order clauses or SQL strings such as array(‘Profile.last_name’ => ‘ASC’) • limit: The maximum number of associated rows you want returned. • offset: The number of associated rows to skip over (given the current conditions and order) before fetching and associating. • dependent: When dependent is set to true, recursive model deletion is possible. In this example, Comment records will be deleted when their associated User record has been deleted. • exclusive: When exclusive is set to true, recursive model deletion does the delete with a deleteAll() call, instead of deleting each entity separately. This greatly improves performance, but may not be ideal for all circumstances. • finderQuery: A complete SQL query CakePHP can use to fetch associated model records. This should be used in situations that require highly customized results. If a query you’re building re- quires a reference to the associated model ID, use the special {$__cakeID__$} marker in the query. For example, if your Apple model hasMany Orange, the query should look something like this: SELECT Orange.* from oranges as Orange WHERE Orange.apple_id = {$__cakeID__$}; Once this association has been defined, find operations on the User model will also fetch related Comment records if they exist: //Sample results from a $this->User->find() call. Array ( [User] => Array ( [id] => 121 [name] => Gwoo the Kungwoo [created] => 2007-05-01 10:31:01 ) [Comment] => Array ( [0] => Array ( [id] => 123 [user_id] => 121 [title] => On Gwoo the Kungwoo [body] => The Kungwooness is not so Gwooish [created] => 2006-05-01 10:31:01 ) [1] => Array ( More on models 215
- 222. CakePHP Cookbook Documentation,Release 2.x [id] => 124 [user_id] => 121 [title] => More on Gwoo [body] => But what of the ’ Nut? [created] => 2006-05-01 10:41:01 ) ) ) One thing to remember is that you’ll need a complementary Comment belongsTo User association in order to get the data from both directions. What we’ve outlined in this section empowers you to get Comment data from the User. Adding the Comment belongsTo User association in the Comment model enables you to get User data from the Comment model, completing the connection and allowing the flow of information from either model’s perspective. hasAndBelongsToMany (HABTM) All right. At this point, you can already call yourself a CakePHP model associations professional. You’re already well versed in the three associations that take up the bulk of object relations. Let’s tackle the final relationship type: hasAndBelongsToMany, or HABTM. This association is used when you have two models that need to be joined up, repeatedly, many times, in many different ways. The main difference between hasMany and HABTM is that a link between models in HABTM is not exclu- sive. For example, we’re about to join up our Recipe model with an Ingredient model using HABTM. Using tomatoes as an Ingredient for my grandma’s spaghetti recipe doesn’t “use up” the ingredient. I can also use it for a salad Recipe. Links between hasMany associated objects are exclusive. If my User hasMany Comments, a comment is only linked to a specific user. It’s not up for grabs. Moving on. We’ll need to set up an extra table in the database to handle HABTM associations. This new join table’s name needs to include the names of both models involved, in alphabetical order, and separated with an underscore ( _ ). The contents of the table should be two fields that are foreign keys (which should be integers) pointing to the primary keys of the involved models. To avoid any issues, don’t define a combined primary key for these two fields. If your application requires a unique index, you can define one. If you plan to add any extra information to this table, or use a ‘with’ model, you should add an additional primary key field (by convention ‘id’). HABTM requires a separate join table that includes both model names. Relationship HABTM Table Fields Recipe HABTM Ingredient ingredients_recipes.id, ingredients_recipes.ingredient_id, ingredients_recipes.recipe_id Cake HABTM Fan cakes_fans.id, cakes_fans.cake_id, cakes_fans.fan_id Foo HABTM Bar bars_foos.id, bars_foos.foo_id, bars_foos.bar_id Note: Table names are in alphabetical order by convention. It is possible to define a custom table name in association definition. 216 Chapter 8. Models
- 223. CakePHP Cookbook Documentation,Release 2.x Make sure primary keys in tables cakes and recipes have “id” fields as assumed by convention. If they’re different than assumed, they must be changed in model’s primaryKey. Once this new table has been created, we can define the HABTM association in the model files. We’re going to skip straight to the array syntax this time: class Recipe extends AppModel { public $hasAndBelongsToMany = array( ’Ingredient’ => array( ’className’ => ’Ingredient’, ’joinTable’ => ’ingredients_recipes’, ’foreignKey’ => ’recipe_id’, ’associationForeignKey’ => ’ingredient_id’, ’unique’ => true, ’conditions’ => ’’, ’fields’ => ’’, ’order’ => ’’, ’limit’ => ’’, ’offset’ => ’’, ’finderQuery’ => ’’, ’with’ => ’’ ) ); } Possible keys for HABTM association arrays include: • className: the class name of the model being associated to the current model. If you’re defining a ‘Recipe HABTM Ingredient’ relationship, the className key should equal ‘Ingredient’. • joinTable: The name of the join table used in this association (if the current table doesn’t adhere to the naming convention for HABTM join tables). • with: Defines the name of the model for the join table. By default CakePHP will auto-create a model for you. Using the example above it would be called IngredientsRecipe. By using this key you can override this default name. The join table model can be used just like any “regular” model to access the join table directly. By creating a model class with such name and filename, you can add any custom behavior to the join table searches, such as adding more information/columns to it. • foreignKey: the name of the foreign key found in the current model. This is especially handy if you need to define multiple HABTM relationships. The default value for this key is the underscored, singular name of the current model, suffixed with ‘_id’. • associationForeignKey: the name of the foreign key found in the other model. This is especially handy if you need to define multiple HABTM relationships. The default value for this key is the underscored, singular name of the other model, suffixed with ‘_id’. • unique: boolean or string keepExisting. – If true (default value) CakePHP will first delete existing relationship records in the foreign keys table before inserting new ones. Existing associations need to be passed again when updating. More on models 217
- 224. CakePHP Cookbook Documentation,Release 2.x – When false, CakePHP will insert the specified new relationship records and leave any ex- isting relationship records in place, possibly resulting in duplicate relationship records. – When set to keepExisting, the behavior is similar to true, but with an additional check so that if any of the records to be added are duplicates of an existing relationship record, the existing relationship record is not deleted, and the duplicate is ignored. This can be useful if, for example, the join table has additional data in it that needs to be retained. • conditions: an array of find()-compatible conditions or SQL string. If you have conditions on an associated table, you should use a ‘with’ model, and define the necessary belongsTo associations on it. • fields: A list of fields to be retrieved when the associated model data is fetched. Returns all fields by default. • order: an array of find()-compatible order clauses or SQL strings • limit: The maximum number of associated rows you want returned. • offset: The number of associated rows to skip over (given the current conditions and order) before fetching and associating. • finderQuery: A complete SQL query CakePHP can use to fetch associated model records. This should be used in situations that require highly customized results. Once this association has been defined, find operations on the Recipe model will also fetch related Tag records if they exist: // Sample results from a $this->Recipe->find() call. Array ( [Recipe] => Array ( [id] => 2745 [name] => Chocolate Frosted Sugar Bombs [created] => 2007-05-01 10:31:01 [user_id] => 2346 ) [Ingredient] => Array ( [0] => Array ( [id] => 123 [name] => Chocolate ) [1] => Array ( [id] => 124 [name] => Sugar ) [2] => Array ( [id] => 125 [name] => Bombs 218 Chapter 8. Models
- 225. CakePHP Cookbook Documentation,Release 2.x ) ) ) Remember to define a HABTM association in the Ingredient model if you’d like to fetch Recipe data when using the Ingredient model. Note: HABTM data is treated like a complete set. Each time a new data association is added, the complete set of associated rows in the database is dropped and created again so you will always need to pass the whole data set for saving. For an alternative to using HABTM, see hasMany through (The Join Model). Tip: For more information on saving HABTM objects, see Saving Related Model Data (HABTM) hasMany through (The Join Model) It is sometimes desirable to store additional data with a many-to-many association. Consider the following Student hasAndBelongsToMany Course Course hasAndBelongsToMany Student In other words, a Student can take many Courses and a Course can be taken by many Students. This is a simple many-to-many association demanding a table such as this: id | student_id | course_id Now what if we want to store the number of days that were attended by the student on the course and their final grade? The table we’d want would be: id | student_id | course_id | days_attended | grade The trouble is, hasAndBelongsToMany will not support this type of scenario because when hasAndBe- longsToMany associations are saved, the association is deleted first. You would lose the extra data in the columns as it is not replaced in the new insert. Changed in version 2.1. You can set the unique setting to keepExisting to circumvent losing extra data during the save operation. See unique key in HABTM association arrays. The way to implement our requirement is to use a join model, otherwise known as a hasMany through association. That is, the association is a model itself. So, we can create a new model CourseMembership. Take a look at the following models.: // Student.php class Student extends AppModel { public $hasMany = array( ’CourseMembership’ ); } More on models 219
- 226. CakePHP Cookbook Documentation,Release 2.x // Course.php class Course extends AppModel { public $hasMany = array( ’CourseMembership’ ); } // CourseMembership.php class CourseMembership extends AppModel { public $belongsTo = array( ’Student’, ’Course’ ); } The CourseMembership join model uniquely identifies a given Student’s participation on a Course in addi- tion to extra meta-information. Join models are pretty useful things to be able to use, and CakePHP makes it easy to do so with its built-in hasMany and belongsTo associations and saveAll feature. Creating and Destroying Associations on the Fly Sometimes it becomes necessary to create and destroy model associations on the fly. This may be for any number of reasons: • You want to reduce the amount of associated data fetched, but all your associations are on the first level of recursion. • You want to change the way an association is defined in order to sort or filter associated data. This association creation and destruction is done using the CakePHP model bindModel() and unbindModel() methods. (There is also a very helpful behavior called “Containable”. Please refer to the manual section about Built-in behaviors for more information.) Let’s set up a few models so we can see how bindModel() and unbindModel() work. We’ll start with two models: class Leader extends AppModel { public $hasMany = array( ’Follower’ => array( ’className’ => ’Follower’, ’order’ => ’Follower.rank’ ) ); } class Follower extends AppModel { public $name = ’Follower’; } Now, in the LeadersController, we can use the find() method in the Leader model to fetch a Leader and its associated followers. As you can see above, the association array in the Leader model defines a “Leader 220 Chapter 8. Models
- 227. CakePHP Cookbook Documentation,Release 2.x hasMany Followers” relationship. For demonstration purposes, let’s use unbindModel() to remove that association in a controller action: public function some_action() { // This fetches Leaders, and their associated Followers $this->Leader->find(’all’); // Let’s remove the hasMany... $this->Leader->unbindModel( array(’hasMany’ => array(’Follower’)) ); // Now using a find function will return // Leaders, with no Followers $this->Leader->find(’all’); // NOTE: unbindModel only affects the very next // find function. An additional find call will use // the configured association information. // We’ve already used find(’all’) after unbindModel(), // so this will fetch Leaders with associated // Followers once again... $this->Leader->find(’all’); } Note: Removing or adding associations using bind- and unbindModel() only works for the next find opera- tion unless the second parameter has been set to false. If the second parameter has been set to false, the bind remains in place for the remainder of the request. Here’s the basic usage pattern for unbindModel(): $this->Model->unbindModel( array(’associationType’ => array(’associatedModelClassName’)) ); Now that we’ve successfully removed an association on the fly, let’s add one. Our as-of-yet unprincipled Leader needs some associated Principles. The model file for our Principle model is bare, except for the public $name statement. Let’s associate some Principles to our Leader on the fly (but remember, only for the following find operation). This function appears in the LeadersController: public function another_action() { // There is no Leader hasMany Principles in // the leader.php model file, so a find here // only fetches Leaders. $this->Leader->find(’all’); // Let’s use bindModel() to add a new association // to the Leader model: $this->Leader->bindModel( array(’hasMany’ => array( ’Principle’ => array( ’className’ => ’Principle’ More on models 221
- 228. CakePHP Cookbook Documentation,Release 2.x ) ) ) ); // Now that we’re associated correctly, // we can use a single find function to fetch // Leaders with their associated principles: $this->Leader->find(’all’); } There you have it. The basic usage for bindModel() is the encapsulation of a normal association array inside an array whose key is named after the type of association you are trying to create: $this->Model->bindModel( array(’associationName’ => array( ’associatedModelClassName’ => array( // normal association keys go here... ) ) ) ); Even though the newly bound model doesn’t need any sort of association definition in its model file, it will still need to be correctly keyed in order for the new association to work properly. Multiple relations to the same model There are cases where a Model has more than one relation to another Model. For example, you might have a Message model that has two relations to the User model: one relation to the user who sends a message, and a second to the user who receives the message. The messages table will have a field user_id, but also a field recipient_id. Now your Message model can look something like: class Message extends AppModel { public $belongsTo = array( ’Sender’ => array( ’className’ => ’User’, ’foreignKey’ => ’user_id’ ), ’Recipient’ => array( ’className’ => ’User’, ’foreignKey’ => ’recipient_id’ ) ); } Recipient is an alias for the User model. Now let’s see what the User model would look like: class User extends AppModel { public $hasMany = array( ’MessageSent’ => array( ’className’ => ’Message’, 222 Chapter 8. Models
- 229. CakePHP Cookbook Documentation,Release 2.x ’foreignKey’ => ’user_id’ ), ’MessageReceived’ => array( ’className’ => ’Message’, ’foreignKey’ => ’recipient_id’ ) ); } It is also possible to create self associations as shown below: class Post extends AppModel { public $belongsTo = array( ’Parent’ => array( ’className’ => ’Post’, ’foreignKey’ => ’parent_id’ ) ); public $hasMany = array( ’Children’ => array( ’className’ => ’Post’, ’foreignKey’ => ’parent_id’ ) ); } Fetching a nested array of associated records: If your table has a parent_id field, you can also use find(‘threaded’) to fetch a nested array of records using a single query without setting up any associations. Joining tables In SQL, you can combine related tables using the JOIN statement. This allows you to perform complex searches across multiple tables (for example, search posts given several tags). In CakePHP, some associations (belongsTo and hasOne) perform automatic joins to retrieve data, so you can issue queries to retrieve models based on data in the related one. But this is not the case with hasMany and hasAndBelongsToMany associations. Here is where forcing joins comes to the rescue. You only have to define the necessary joins to combine tables and get the desired results for your query. Note: Remember that you need to set the recursion to -1 for this to work: $this->Channel->recursive = -1; To force a join between tables, you need to use the “modern” syntax for Model::find(), adding a ‘joins’ key to the $options array. For example: $options[’joins’] = array( array(’table’ => ’channels’, More on models 223
- 230. CakePHP Cookbook Documentation,Release 2.x ’alias’ => ’Channel’, ’type’ => ’LEFT’, ’conditions’ => array( ’Channel.id = Item.channel_id’, ) ) ); $Item->find(’all’, $options); Note: Note that the ‘join’ arrays are not keyed. In the above example, a model called Item is left-joined to the channels table. You can alias the table with the Model name, so the retrieved data complies with the CakePHP data structure. The keys that define the join are the following: • table: The table for the join. • alias: An alias to the table. The name of the model associated with the table is the best bet. • type: The type of join: inner, left or right. • conditions: The conditions to perform the join. With joins, you could add conditions based on Related model fields: $options[’joins’] = array( array(’table’ => ’channels’, ’alias’ => ’Channel’, ’type’ => ’LEFT’, ’conditions’ => array( ’Channel.id = Item.channel_id’, ) ) ); $options[’conditions’] = array( ’Channel.private’ => 1 ); $privateItems = $Item->find(’all’, $options); You could perform several joins as needed in hasAndBelongsToMany: Suppose there is a Book hasAndBelongsToMany Tag association. This relation uses a books_tags table as a join table, so you need to join the books table to the books_tags table, and this with the tags table: $options[’joins’] = array( array(’table’ => ’books_tags’, ’alias’ => ’BooksTag’, ’type’ => ’inner’, ’conditions’ => array( ’Book.id = BooksTag.book_id’ 224 Chapter 8. Models
- 231. CakePHP Cookbook Documentation,Release 2.x ) ), array(’table’ => ’tags’, ’alias’ => ’Tag’, ’type’ => ’inner’, ’conditions’ => array( ’BooksTag.tag_id = Tag.id’ ) ) ); $options[’conditions’] = array( ’Tag.tag’ => ’Novel’ ); $books = $Book->find(’all’, $options); Using joins allows you to have maximum flexibility in how CakePHP handles associations and fetches the data. However, in most cases, you can use other tools to achieve the same results such as correctly defining associations, binding models on the fly and using the Containable behavior. This feature should be used with care because it could lead, in a few cases, into ill-formed SQL queries if combined with any of the former techniques described for associating models. Retrieving Your Data As stated before, one of the roles of the Model layer is to get data from multiple types of storage. The CakePHP Model class comes with some functions that will help you search for this data, sort it, paginate it, and filter it. The most common function you will use in models is Model::find() find find(string $type = ’first’, array $params = array()) Find is the multifunctional workhorse of all model data-retrieval functions. $type can be ’all’, ’first’, ’count’, ’list’, ’neighbors’ or ’threaded’, or any custom finder you can de- fine. Keep in mind that $type is case-sensitive. Using an upper case character (for example, All) will not produce the expected results. $params is used to pass all parameters to the various types of find(), and has the following possible keys by default, all of which are optional: array( ’conditions’ => array(’Model.field’ => $thisValue), //array of conditions ’recursive’ => 1, //int //array of field names ’fields’ => array(’Model.field1’, ’DISTINCT Model.field2’), //string or array defining order ’order’ => array(’Model.created’, ’Model.field3 DESC’), ’group’ => array(’Model.field’), //fields to GROUP BY ’limit’ => n, //int More on models 225
- 232. CakePHP Cookbook Documentation,Release 2.x ’page’ => n, //int ’offset’ => n, //int ’callbacks’ => true //other possible values are false, ’before’, ’after’ ) It’s also possible to add and use other parameters. Some types of find() and behaviors make use of this ability, and your own model methods can, too. If your find() operation fails to match any records, you will get an empty array. find(‘first’) find(’first’, $params) will return one result. You’d use this for any case where you expect only one result. Below are a couple of simple (controller code) examples: public function some_function() { // ... $semiRandomArticle = $this->Article->find(’first’); $lastCreated = $this->Article->find(’first’, array( ’order’ => array(’Article.created’ => ’desc’) )); $specificallyThisOne = $this->Article->find(’first’, array( ’conditions’ => array(’Article.id’ => 1) )); // ... } In the first example, no parameters at all are passed to find, so no conditions or sort order will be used. The format returned from find(’first’) call is of the form: Array ( [ModelName] => Array ( [id] => 83 [field1] => value1 [field2] => value2 [field3] => value3 ) [AssociatedModelName] => Array ( [id] => 1 [field1] => value1 [field2] => value2 [field3] => value3 ) ) 226 Chapter 8. Models
- 233. CakePHP Cookbook Documentation,Release 2.x find(‘count’) find(’count’, $params) returns an integer value. Below are a couple of simple (controller code) examples: public function some_function() { // ... $total = $this->Article->find(’count’); $pending = $this->Article->find(’count’, array( ’conditions’ => array(’Article.status’ => ’pending’) )); $authors = $this->Article->User->find(’count’); $publishedAuthors = $this->Article->find(’count’, array( ’fields’ => ’DISTINCT Article.user_id’, ’conditions’ => array(’Article.status !=’ => ’pending’) )); // ... } Note: Don’t pass fields as an array to find(’count’). You would only need to specify fields for a DISTINCT count (since otherwise, the count is always the same, dictated by the conditions). find(‘all’) find(’all’, $params) returns an array of potentially multiple results. It is, in fact, the mechanism used by all find() variants, as well as paginate. Below are a couple of simple (controller code) examples: public function some_function() { // ... $allArticles = $this->Article->find(’all’); $pending = $this->Article->find(’all’, array( ’conditions’ => array(’Article.status’ => ’pending’) )); $allAuthors = $this->Article->User->find(’all’); $allPublishedAuthors = $this->Article->User->find(’all’, array( ’conditions’ => array(’Article.status !=’ => ’pending’) )); // ... } Note: In the above example, $allAuthors will contain every user in the users table. There will be no condition applied to the find, since none were passed. The results of a call to find(’all’) will be of the following form: Array ( [0] => Array ( More on models 227
- 234. CakePHP Cookbook Documentation,Release 2.x [ModelName] => Array ( [id] => 83 [field1] => value1 [field2] => value2 [field3] => value3 ) [AssociatedModelName] => Array ( [id] => 1 [field1] => value1 [field2] => value2 [field3] => value3 ) ) ) find(‘list’) find(’list’, $params) returns an indexed array, useful for any place where you would want a list, such as for populating input select boxes. Below are a couple of simple (controller code) examples: public function some_function() { // ... $allArticles = $this->Article->find(’list’); $pending = $this->Article->find(’list’, array( ’conditions’ => array(’Article.status’ => ’pending’) )); $allAuthors = $this->Article->User->find(’list’); $allPublishedAuthors = $this->Article->find(’list’, array( ’fields’ => array(’User.id’, ’User.name’), ’conditions’ => array(’Article.status !=’ => ’pending’), ’recursive’ => 0 )); // ... } Note: In the above example, $allAuthors will contain every user in the users table. There will be no condition applied to the find, since none were passed. The results of a call to find(’list’) will be in the following form: Array ( //[id] => ’displayValue’, [1] => ’displayValue1’, [2] => ’displayValue2’, [4] => ’displayValue4’, [5] => ’displayValue5’, 228 Chapter 8. Models
- 235. CakePHP Cookbook Documentation,Release 2.x [6] => ’displayValue6’, [3] => ’displayValue3’, ) When calling find(’list’), the fields passed are used to determine what should be used as the array key and value, and optionally what to group the results by. By default, the primary key for the model is used for the key, and the display field (which can be configured using the model attribute displayField) is used for the value. Some further examples to clarify: public function some_function() { // ... $justusernames = $this->Article->User->find(’list’, array( ’fields’ => array(’User.username’) )); $usernameMap = $this->Article->User->find(’list’, array( ’fields’ => array(’User.username’, ’User.first_name’) )); $usernameGroups = $this->Article->User->find(’list’, array( ’fields’ => array(’User.username’, ’User.first_name’, ’User.group’) )); // ... } With the above code example, the resultant vars would look something like this: $justusernames = Array ( //[id] => ’username’, [213] => ’AD7six’, [25] => ’_psychic_’, [1] => ’PHPNut’, [2] => ’gwoo’, [400] => ’jperras’, ) $usernameMap = Array ( //[username] => ’firstname’, [’AD7six’] => ’Andy’, [’_psychic_’] => ’John’, [’PHPNut’] => ’Larry’, [’gwoo’] => ’Gwoo’, [’jperras’] => ’Joël’, ) $usernameGroups = Array ( [’User’] => Array ( [’PHPNut’] => ’Larry’, [’gwoo’] => ’Gwoo’, ) More on models 229
- 236. CakePHP Cookbook Documentation,Release 2.x [’Admin’] => Array ( [’_psychic_’] => ’John’, [’AD7six’] => ’Andy’, [’jperras’] => ’Joël’, ) ) find(‘threaded’) find(’threaded’, $params) returns a nested array, and is appropriate if you want to use the parent_id field of your model data to build nested results. Below are a couple of simple (controller code) examples: public function some_function() { // ... $allCategories = $this->Category->find(’threaded’); $comments = $this->Comment->find(’threaded’, array( ’conditions’ => array(’article_id’ => 50) )); // ... } Tip: A better way to deal with nested data is using the Tree behavior In the above code example, $allCategories will contain a nested array representing the whole category structure. The results of a call to find(’threaded’) will be of the following form: Array ( [0] => Array ( [ModelName] => Array ( [id] => 83 [parent_id] => null [field1] => value1 [field2] => value2 [field3] => value3 ) [AssociatedModelName] => Array ( [id] => 1 [field1] => value1 [field2] => value2 [field3] => value3 ) [children] => Array 230 Chapter 8. Models
- 237. CakePHP Cookbook Documentation,Release 2.x ( [0] => Array ( [ModelName] => Array ( [id] => 42 [parent_id] => 83 [field1] => value1 [field2] => value2 [field3] => value3 ) [AssociatedModelName] => Array ( [id] => 2 [field1] => value1 [field2] => value2 [field3] => value3 ) [children] => Array ( ) ) ... ) ) ) The order in which results appear can be changed, as it is influenced by the order of processing. For example, if ’order’ => ’name ASC’ is passed in the params to find(’threaded’), the results will appear in name order. Any order can be used; there is no built-in requirement of this method for the top result to be returned first. Warning: If you specify fields, you need to always include the id and parent_id (or their current aliases): public function some_function() { $categories = $this->Category->find(’threaded’, array( ’fields’ => array(’id’, ’name’, ’parent_id’) )); } Otherwise, the returned array will not be of the expected nested structure from above. find(‘neighbors’) find(’neighbors’, $params) will perform a find similar to ‘first’, but will return the row before and after the one you request. Below is a simple (controller code) example: More on models 231
- 238. CakePHP Cookbook Documentation,Release 2.x public function some_function() { $neighbors = $this->Article->find( ’neighbors’, array(’field’ => ’id’, ’value’ => 3) ); } You can see in this example the two required elements of the $params array: field and value. Other elements are still allowed as with any other find. (For example: If your model acts as containable, then you can specify ‘contain’ in $params.) The result returned from a find(’neighbors’) call is in the form: Array ( [prev] => Array ( [ModelName] => Array ( [id] => 2 [field1] => value1 [field2] => value2 ... ) [AssociatedModelName] => Array ( [id] => 151 [field1] => value1 [field2] => value2 ... ) ) [next] => Array ( [ModelName] => Array ( [id] => 4 [field1] => value1 [field2] => value2 ... ) [AssociatedModelName] => Array ( [id] => 122 [field1] => value1 [field2] => value2 ... ) ) ) Note: Note how the result always contains only two root elements: prev and next. This function does not honor a model’s default recursive var. The recursive setting must be passed in the parameters on each call. 232 Chapter 8. Models
- 239. CakePHP Cookbook Documentation,Release 2.x Creating custom find types The find method is flexible enough to accept your custom finders. This is done by declaring your own types in a model variable and by implementing a special function in your model class. A Model Find Type is a shortcut to find() options. For example, the following two finds are equivalent $this->User->find(’first’); $this->User->find(’all’, array(’limit’ => 1)); The following are core find types: • first • all • count • list • threaded • neighbors But what about other types? Let’s say you want a finder for all published articles in your database. The first change you need to do is add your type to the Model::$findMethods variable in the model class Article extends AppModel { public $findMethods = array(’available’ => true); } Basically this is just telling CakePHP to accept the value available as the first argument of the find function. The next step is to implement the function _findAvailable. This is done by convention. If you wanted to implement a finder called myFancySearch, then the method to implement would be named _findMyFancySearch. class Article extends AppModel { public $findMethods = array(’available’ => true); protected function _findAvailable($state, $query, $results = array()) { if ($state === ’before’) { $query[’conditions’][’Article.published’] = true; return $query; } return $results; } } This all comes together in the following example (controller code): class ArticlesController extends AppController { // Will find all published articles and order them by the created column public function index() { $articles = $this->Article->find(’available’, array( ’order’ => array(’created’ => ’desc’) More on models 233
- 240. CakePHP Cookbook Documentation,Release 2.x )); } } The special _find[Type] methods receive three arguments as shown above. The first one means the state of the query execution, which could be either before or after. It is done this way because this function is just a sort of callback function that has the ability to modify the query before it is done, or to modify the results after they are fetched. Typically the first thing to check in our custom find function is the state of the query. The before state is the moment to modify the query, bind new associations, apply more behaviors, and interpret any special key that is passed in the second argument of find. This state requires you to return the $query argument (modified or not). The after state is the perfect place to inspect the results, inject new data, process it in order to return it in another format, or do whatever you like to the recently fetched data. This state requires you to return the $results array (modified or not). You can create as many custom finders as you like, and they are a great way of reusing code in your application across models. It is also possible to paginate via a custom find type as follows: class ArticlesController extends AppController { // Will paginate all published articles public function index() { $this->paginate = array(’available’); $articles = $this->paginate(); $this->set(compact(’articles’)); } } Setting the $this->paginate property as above on the controller will result in the type of the find becoming available, and will also allow you to continue to modify the find results. To simply return the count of a custom find type, call count like you normally would, but pass in the find type in an array for the second argument. class ArticlesController extends AppController { // Will find the count of all published articles (using the available find defined abov public function index() { $count = $this->Article->find(’count’, array( ’type’ => ’available’ )); } } If your pagination page count is becoming corrupt, it may be necessary to add the following code to your AppModel, which should fix the pagination count: 234 Chapter 8. Models
- 241. CakePHP Cookbook Documentation,Release 2.x class AppModel extends Model { /** * Removes ’fields’ key from count query on custom finds when it is an array, * as it will completely break the Model::_findCount() call * * @param string $state Either "before" or "after" * @param array $query * @param array $results * @return int The number of records found, or false * @access protected * @see Model::find() */ protected function _findCount($state, $query, $results = array()) { if ($state === ’before’) { if (isset($query[’type’]) && isset($this->findMethods[$query[’type’]])) { $query = $this->{ ’_find’ . ucfirst($query[’type’]) }(’before’, $query); if (!empty($query[’fields’]) && is_array($query[’fields’])) { if (!preg_match(’/^count/i’, current($query[’fields’]))) { unset($query[’fields’]); } } } } return parent::_findCount($state, $query, $results); } } ?> Changed in version 2.2. You no longer need to override _findCount for fixing incorrect count results. The ’before’ state of your custom finder will now be called again with $query[’operation’] = ‘count’. The returned $query will be used in _findCount() If necessary, you can distinguish by checking the ’operation’ key and return a different $query: protected function _findAvailable($state, $query, $results = array()) { if ($state === ’before’) { $query[’conditions’][’Article.published’] = true; if (!empty($query[’operation’]) && $query[’operation’] === ’count’) { return $query; } $query[’joins’] = array( //array of required joins ); return $query; } return $results; } More on models 235
- 242. CakePHP Cookbook Documentation,Release 2.x Magic Find Types These magic functions can be used as a shortcut to search your tables by a certain field. Just add the name of the field (in CamelCase format) to the end of these functions, and supply the criteria for that field as the first parameter. findAllBy() functions will return results in a format like find(’all’), while findBy() return in the same format as find(’first’) findAllBy findAllBy<fieldName>(string $value, array $fields, array $order, int $limit, int $page, int $recursive) findAllBy<x> Example Corresponding SQL Fragment $this->Product->findAllByOrderStatus(’3’); Product.order_status = 3 $this->Recipe->findAllByType(’Cookie’); Recipe.type = ’Cookie’ $this->User->findAllByLastName(’Anderson’);User.last_name = ’Anderson’ $this->Cake->findAllById(7); Cake.id = 7 $this->User->findAllByEmailOrUsername(’jhon’, ’jhon’); User.email = ’jhon’ OR User.username = ’jhon’; $this->User->findAllByUsernameAndPassword(’jhon’, ’123’); User.username = ’jhon’ AND User.password = ’123’; $this->User->findAllByLastName(’psychic’, array(), array(’User.user_name => ’asc’)); User.last_name = ’psychic’ ORDER BY User.user_name ASC The returned result is an array formatted just as it would be from find(’all’). findBy findBy<fieldName>(string $value); The findBy magic functions also accept some optional parameters: findBy<fieldName>(string $value[, mixed $fields[, mixed $order]]); findBy<x> Example Corresponding SQL Fragment $this->Product->findByOrderStatus(’3’);Product.order_status = 3 $this->Recipe->findByType(’Cookie’); Recipe.type = ’Cookie’ $this->User->findByLastName(’Anderson’);User.last_name = ’Anderson’; $this->User->findByEmailOrUsername(’jhon’, ’jhon’); User.email = ’jhon’ OR User.username = ’jhon’; $this->User->findByUsernameAndPassword(’jhon’, ’123’); User.username = ’jhon’ AND User.password = ’123’; $this->Cake->findById(7); Cake.id = 7 findBy() functions return results like find(’first’) 236 Chapter 8. Models
- 243. CakePHP Cookbook Documentation,Release 2.x Model::query() query(string $query) SQL calls that you can’t or don’t want to make via other model methods can be made using the model’s query() method (though this should only rarely be necessary). If you use this method, be sure to properly escape all parameters using the value() method on the database driver. Failing to escape parameters will create SQL injection vulnerabilities. Note: query() does not honor $Model->cacheQueries as its functionality is inherently disjoint from that of the calling model. To avoid caching calls to query, supply a second argument of false, ie: query($query, $cachequeries = false) query() uses the table name in the query as the array key for the returned data, rather than the model name. For example: $this->Picture->query("SELECT * FROM pictures LIMIT 2;"); might return: Array ( [0] => Array ( [pictures] => Array ( [id] => 1304 [user_id] => 759 ) ) [1] => Array ( [pictures] => Array ( [id] => 1305 [user_id] => 759 ) ) ) To use the model name as the array key, and get a result consistent with that returned by the Find methods, the query can be rewritten: $this->Picture->query("SELECT * FROM pictures AS Picture LIMIT 2;"); which returns: Array ( [0] => Array ( More on models 237
- 244. CakePHP Cookbook Documentation,Release 2.x [Picture] => Array ( [id] => 1304 [user_id] => 759 ) ) [1] => Array ( [Picture] => Array ( [id] => 1305 [user_id] => 759 ) ) ) Note: This syntax and the corresponding array structure is valid for MySQL only. CakePHP does not provide any data abstraction when running queries manually, so exact results will vary between databases. Model::field() field(string $name, array $conditions = null, string $order = null) Returns the value of a single field, specified as $name, from the first record matched by $conditions as ordered by $order. If no conditions are passed and the model id is set, it will return the field value for the current model result. If no matching record is found, it returns false. $this->Post->id = 22; echo $this->Post->field(’name’); // echo the name for row id 22 // echo the name of the last created instance echo $this->Post->field( ’name’, array(’created <’ => date(’Y-m-d H:i:s’)), ’created DESC’ ); Model::read() read($fields, $id) read() is a method used to set the current model data (Model::$data)–such as during edits–but it can also be used in other circumstances to retrieve a single record from the database. $fields is used to pass a single field name, as a string, or an array of field names; if left empty, all fields will be fetched. $id specifies the ID of the record to be read. By default, the currently selected record, as specified by Model::$id, is used. Passing a different value to $id will cause that record to be selected. 238 Chapter 8. Models
- 245. CakePHP Cookbook Documentation,Release 2.x read() always returns an array (even if only a single field name is requested). Use field to retrieve the value of a single field. Warning: As the read method overwrites any information stored in the data and id property of the model, you should be very careful when using this function in general, especially using it in the model callback functions such as beforeValidate and beforeSave. Generally the find function provides a more robust and easy to work with API than the read method. Complex Find Conditions Most of the model’s find calls involve passing sets of conditions in one way or another. In general, CakePHP prefers using arrays for expressing any conditions that need to be put after the WHERE clause in any SQL query. Using arrays is clearer and easier to read, and also makes it very easy to build queries. This syntax also breaks out the elements of your query (fields, values, operators, etc.) into discrete, manipulatable parts. This allows CakePHP to generate the most efficient query possible, ensure proper SQL syntax, and properly escape each individual part of the query. Using the array syntax also enables CakePHP to secure your queries against any SQL injection attack. Warning: CakePHP only escapes the array values. You should never put user data into the keys. Doing so will make you vulnerable to SQL injections. At its most basic, an array-based query looks like this: $conditions = array("Post.title" => "This is a post", "Post.author_id" => 1); // Example usage with a model: $this->Post->find(’first’, array(’conditions’ => $conditions)); The structure here is fairly self-explanatory: it will find any post where the title equals “This is a post” and the author id is equal to 1. Note that we could have used just “title” as the field name, but when building queries, it is good practice to always specify the model name, as it improves the clarity of the code, and helps prevent collisions in the future, should you choose to change your schema. What about other types of matches? These are equally simple. Let’s say we wanted to find all the posts where the title is not “This is a post”: array("Post.title !=" => "This is a post") Notice the ‘!=’ that follows the field name. CakePHP can parse out any valid SQL comparison operator, including match expressions using LIKE, BETWEEN, or REGEX, as long as you leave a space between field name and the operator. The one exception here is IN (...)-style matches. Let’s say you wanted to find posts where the title was in a given set of values: array( "Post.title" => array("First post", "Second post", "Third post") ) To do a NOT IN(...) match to find posts where the title is not in the given set of values, do the following: More on models 239
- 246. CakePHP Cookbook Documentation,Release 2.x array( "NOT" => array( "Post.title" => array("First post", "Second post", "Third post") ) ) Adding additional filters to the conditions is as simple as adding additional key/value pairs to the array: array ( "Post.title" => array("First post", "Second post", "Third post"), "Post.created >" => date(’Y-m-d’, strtotime("-2 weeks")) ) You can also create finds that compare two fields in the database: array("Post.created = Post.modified") The above example will return posts where the created date is equal to the modified date (that is, it will return posts that have never been modified). Remember that if you find yourself unable to form a WHERE clause in this method (for example, boolean operations), you can always specify it as a string like: array( ’Model.field & 8 = 1’, // other conditions as usual ) By default, CakePHP joins multiple conditions with boolean AND. This means the snippet above would only match posts that have been created in the past two weeks, and have a title that matches one in the given set. However, we could just as easily find posts that match either condition: array("OR" => array( "Post.title" => array("First post", "Second post", "Third post"), "Post.created >" => date(’Y-m-d’, strtotime("-2 weeks")) )) CakePHP accepts all valid SQL boolean operations, including AND, OR, NOT, XOR, etc., and they can be upper or lower case, whichever you prefer. These conditions are also infinitely nestable. Let’s say you had a belongsTo relationship between Posts and Authors. Let’s say you wanted to find all the posts that contained a certain keyword (“magic”) or were created in the past two weeks, but you wanted to restrict your search to posts written by Bob: array( "Author.name" => "Bob", "OR" => array( "Post.title LIKE" => "%magic%", "Post.created >" => date(’Y-m-d’, strtotime("-2 weeks")) ) ) If you need to set multiple conditions on the same field, like when you want to do a LIKE search with multiple terms, you can do so by using conditions similar to: 240 Chapter 8. Models
- 247. CakePHP Cookbook Documentation,Release 2.x array(’OR’ => array( array(’Post.title LIKE’ => ’%one%’), array(’Post.title LIKE’ => ’%two%’) )) CakePHP can also check for null fields. In this example, the query will return records where the post title is not null: array("NOT" => array( "Post.title" => null ) ) To handle BETWEEN queries, you can use the following: array(’Post.read_count BETWEEN ? AND ?’ => array(1,10)) Note: CakePHP will quote the numeric values depending on the field type in your DB. How about GROUP BY?: array( ’fields’ => array( ’Product.type’, ’MIN(Product.price) as price’ ), ’group’ => ’Product.type’ ) The data returned for this would be in the following format: Array ( [0] => Array ( [Product] => Array ( [type] => Clothing ) [0] => Array ( [price] => 32 ) ) [1] => Array ... A quick example of doing a DISTINCT query. You can use other operators, such as MIN(), MAX(), etc., in a similar fashion: array( ’fields’ => array(’DISTINCT (User.name) AS my_column_name’), ’order’ = >array(’User.id DESC’) ) More on models 241
- 248. CakePHP Cookbook Documentation,Release 2.x You can create very complex conditions by nesting multiple condition arrays: array( ’OR’ => array( array(’Company.name’ => ’Future Holdings’), array(’Company.city’ => ’CA’) ), ’AND’ => array( array( ’OR’ => array( array(’Company.status’ => ’active’), ’NOT’ => array( array(’Company.status’ => array(’inactive’, ’suspended’)) ) ) ) ) ) which produces the following SQL: SELECT ‘Company‘.‘id‘, ‘Company‘.‘name‘, ‘Company‘.‘description‘, ‘Company‘.‘location‘, ‘Company‘.‘created‘, ‘Company‘.‘status‘, ‘Company‘.‘size‘ FROM ‘companies‘ AS ‘Company‘ WHERE ((‘Company‘.‘name‘ = ’Future Holdings’) OR (‘Company‘.‘city‘ = ’CA’)) AND ((‘Company‘.‘status‘ = ’active’) OR (NOT (‘Company‘.‘status‘ IN (’inactive’, ’suspended’)))) Sub-queries For this example, imagine that we have a “users” table with “id”, “name” and “status”. The status can be “A”, “B” or “C”. We want to retrieve all the users that have status other than “B” using a sub-query. In order to achieve that, we are going to get the model data source and ask it to build the query as if we were calling a find() method, but it will just return the SQL statement. After that we make an expression and add it to the conditions array: $conditionsSubQuery[’"User2"."status"’] = ’B’; $db = $this->User->getDataSource(); $subQuery = $db->buildStatement( array( ’fields’ => array(’"User2"."id"’), 242 Chapter 8. Models
- 249. CakePHP Cookbook Documentation,Release 2.x ’table’ => $db->fullTableName($this->User), ’alias’ => ’User2’, ’limit’ => null, ’offset’ => null, ’joins’ => array(), ’conditions’ => $conditionsSubQuery, ’order’ => null, ’group’ => null ), $this->User ); $subQuery = ’ "User"."id" NOT IN (’ . $subQuery . ’) ’; $subQueryExpression = $db->expression($subQuery); $conditions[] = $subQueryExpression; $this->User->find(’all’, compact(’conditions’)); This should generate the following SQL: SELECT "User"."id" AS "User__id", "User"."name" AS "User__name", "User"."status" AS "User__status" FROM "users" AS "User" WHERE "User"."id" NOT IN ( SELECT "User2"."id" FROM "users" AS "User2" WHERE "User2"."status" = ’B’ ) Also, if you need to pass just part of your query as raw SQL as above, datasource expressions with raw SQL work for any part of the find query. Prepared Statements Should you need even more control over your queries, you can make use of prepared statements. This allows you to talk directly to the database driver and send any custom query you like: $db = $this->getDataSource(); $db->fetchAll( ’SELECT * from users where username = ? AND password = ?’, array(’jhon’, ’12345’) ); $db->fetchAll( ’SELECT * from users where username = :username AND password = :password’, More on models 243
- 250. CakePHP Cookbook Documentation,Release 2.x array(’username’ => ’jhon’,’password’ => ’12345’) ); Saving Your Data CakePHP makes saving model data a snap. Data ready to be saved should be passed to the model’s save() method using the following basic format: Array ( [ModelName] => Array ( [fieldname1] => ’value’ [fieldname2] => ’value’ ) ) Most of the time you won’t even need to worry about this format: CakePHP’s FormHelper, and model find methods all package data in this format. If you’re using FormHelper, the data is also conveniently available in $this->request->data for quick usage. Here’s a quick example of a controller action that uses a CakePHP model to save data to a database table: public function edit($id) { // Has any form data been POSTed? if ($this->request->is(’post’)) { // If the form data can be validated and saved... if ($this->Recipe->save($this->request->data)) { // Set a session flash message and redirect. $this->Session->setFlash(’Recipe Saved!’); return $this->redirect(’/recipes’); } } // If no form data, find the recipe to be edited // and hand it to the view. $this->set(’recipe’, $this->Recipe->findById($id)); } When save is called, the data passed to it in the first parameter is validated using CakePHP’s validation mechanism (see Data Validation chapter for more information). If for some reason your data isn’t saving, be sure to check to see if some validation rules are being broken. You can debug this situation by outputting Model::$validationErrors: if ($this->Recipe->save($this->request->data)) { // handle the success. } debug($this->Recipe->validationErrors); There are a few other save-related methods in the model that you’ll find useful: 244 Chapter 8. Models
- 251. CakePHP Cookbook Documentation,Release 2.x Model::set($one, $two = null) Model::set() can be used to set one or many fields of data to the data array inside a model. This is useful when using models with the ActiveRecord features offered by Model: $this->Post->read(null, 1); $this->Post->set(’title’, ’New title for the article’); $this->Post->save(); Is an example of how you can use set() to update single fields, in an ActiveRecord approach. You can also use set() to assign new values to multiple fields: $this->Post->read(null, 1); $this->Post->set(array( ’title’ => ’New title’, ’published’ => false )); $this->Post->save(); The above would update the title and published fields and save the record to the database. Model::clear() This method can be used to reset model state and clear out any unsaved data and validation errors. New in version 2.4. Model::save(array $data = null, boolean $validate = true, array $fieldList = array()) Featured above, this method saves array-formatted data. The second parameter allows you to sidestep val- idation, and the third allows you to supply a list of model fields to be saved. For added security, you can limit the saved fields to those listed in $fieldList. Note: If $fieldList is not supplied, a malicious user can add additional fields to the form data (if you are not using SecurityComponent), and by this change fields that were not originally intended to be changed. The save method also has an alternate syntax: save(array $data = null, array $params = array()) $params array can have any of the following available options as keys: • validate Set to true/false to enable/disable validation. • fieldList An array of fields you want to allow for saving. • callbacks Set to false to disable callbacks. Using ‘before’ or ‘after’ will enable only those call- backs. More on models 245
- 252. CakePHP Cookbook Documentation,Release 2.x • counterCache (since 2.4) Boolean to control updating of counter caches (if any) More information about model callbacks is available here Tip: If you don’t want the modified field to be automatically updated when saving some data add ’modified’ => false to your $data array Once a save has been completed, the ID for the object can be found in the $id attribute of the model object - something especially handy when creating new objects. $this->Ingredient->save($newData); $newIngredientId = $this->Ingredient->id; Creating or updating is controlled by the model’s id field. If $Model->id is set, the record with this primary key is updated. Otherwise a new record is created: // Create: id isn’t set or is null $this->Recipe->create(); $this->Recipe->save($this->request->data); // Update: id is set to a numerical value $this->Recipe->id = 2; $this->Recipe->save($this->request->data); Tip: When calling save in a loop, don’t forget to call clear(). If you want to update a value, rather than create a new one, make sure you are passing the primary key field into the data array: $data = array(’id’ => 10, ’title’ => ’My new title’); // This will update Recipe with id 10 $this->Recipe->save($data); Model::create(array $data = array()) This method resets the model state for saving new information. It does not actually create a record in the database but clears Model::$id and sets Model::$data based on your database field defaults. If you have not defined defaults for your database fields, Model::$data will be set to an empty array. If the $data parameter (using the array format outlined above) is passed, it will be merged with the database field defaults and the model instance will be ready to save with that data (accessible at $this->data). If false or null are passed for the $data parameter, Model::data will be set to an empty array. Tip: If you want to insert a new row instead of updating an existing one you should always call create() first. This avoids conflicts with possible prior save calls in callbacks or other places. 246 Chapter 8. Models
- 253. CakePHP Cookbook Documentation,Release 2.x Model::saveField(string $fieldName, string $fieldValue, $validate = false) Used to save a single field value. Set the ID of the model ($this->ModelName->id = $id) just before calling saveField(). When using this method, $fieldName should only contain the name of the field, not the name of the model and field. For example, to update the title of a blog post, the call to saveField from a controller might look some- thing like this: $this->Post->saveField(’title’, ’A New Title for a New Day’); Warning: You can’t stop the modified field being updated with this method, you need to use the save() method. The saveField method also has an alternate syntax: saveField(string $fieldName, string $fieldValue, array $params = array()) $params array can have any of the following available options as keys: • validate Set to true/false to enable/disable validation. • callbacks Set to false to disable callbacks. Using ‘before’ or ‘after’ will enable only those call- backs. • counterCache (since 2.4) Boolean to control updating of counter caches (if any) Model::updateAll(array $fields, mixed $conditions) Updates one or more records in a single call. Fields to be updated, along with their values, are identified by the $fields array. Records to be updated are identified by the $conditions array. If $conditions argument is not supplied or it is set to true, all records will be updated. For example, to approve all bakers who have been members for over a year, the update call might look something like: $thisYear = date(’Y-m-d H:i:s’, strtotime(’-1 year’)); $this->Baker->updateAll( array(’Baker.approved’ => true), array(’Baker.created <=’ => $thisYear) ); The $fields array accepts SQL expressions. Literal values should be quoted manually using DboSource::value(). For example if one of your model methods was calling updateAll() you would do the following: $db = $this->getDataSource(); $value = $db->value($value, ’string’); $this->updateAll( array(’Baker.approved’ => true), More on models 247
- 254. CakePHP Cookbook Documentation,Release 2.x array(’Baker.created <=’ => $value) ); Note: Even if the modified field exists for the model being updated, it is not going to be updated automati- cally by the ORM. Just add it manually to the array if you need it to be updated. For example, to close all tickets that belong to a certain customer: $this->Ticket->updateAll( array(’Ticket.status’ => "’closed’"), array(’Ticket.customer_id’ => 453) ); By default, updateAll() will automatically join any belongsTo association for databases that support joins. To prevent this, temporarily unbind the associations. Model::saveMany(array $data = null, array $options = array()) Method used to save multiple rows of the same model at once. The following options may be used: • validate: Set to false to disable validation, true to validate each record before saving, ‘first’ to validate all records before any are saved (default), • atomic: If true (default), will attempt to save all records in a single transaction. Should be set to false if database/table does not support transactions. • fieldList: Equivalent to the $fieldList parameter in Model::save() • deep: (since 2.1) If set to true, also associated data is saved, see also saveAssociated • callbacks Set to false to disable callbacks. Using ‘before’ or ‘after’ will enable only those call- backs. • counterCache (since 2.4) Boolean to control updating of counter caches (if any) For saving multiple records of single model, $data needs to be a numerically indexed array of records like this: $data = array( array(’title’ => ’title 1’), array(’title’ => ’title 2’), ); Note: Note that we are passing numerical indexes instead of usual $data containing the Article key. When saving multiple records of same model the records arrays should be just numerically indexed without the model key. It is also acceptable to have the data in the following format: $data = array( array(’Article’ => array(’title’ => ’title 1’)), 248 Chapter 8. Models
- 255. CakePHP Cookbook Documentation,Release 2.x array(’Article’ => array(’title’ => ’title 2’)), ); To save also associated data with $options[’deep’] = true (since 2.1), the two above examples would look like: $data = array( array(’title’ => ’title 1’, ’Assoc’ => array(’field’ => ’value’)), array(’title’ => ’title 2’), ); $data = array( array( ’Article’ => array(’title’ => ’title 1’), ’Assoc’ => array(’field’ => ’value’) ), array(’Article’ => array(’title’ => ’title 2’)), ); $Model->saveMany($data, array(’deep’ => true)); Keep in mind that if you want to update a record instead of creating a new one you just need to add the primary key index to the data row: $data = array( array( // This creates a new row ’Article’ => array(’title’ => ’New article’)), array( // This updates an existing row ’Article’ => array(’id’ => 2, ’title’ => ’title 2’)), ); Model::saveAssociated(array $data = null, array $options = array()) Method used to save multiple model associations at once. The following options may be used: • validate: Set to false to disable validation, true to validate each record before saving, ‘first’ to validate all records before any are saved (default), • atomic: If true (default), will attempt to save all records in a single transaction. Should be set to false if database/table does not support transactions. • fieldList: Equivalent to the $fieldList parameter in Model::save() • deep: (since 2.1) If set to true, not only directly associated data is saved, but deeper nested associated data as well. Defaults to false. • counterCache (since 2.4) Boolean to control updating of counter caches (if any) For saving a record along with its related record having a hasOne or belongsTo association, the data array should be like this: $data = array( ’User’ => array(’username’ => ’billy’), More on models 249
- 256. CakePHP Cookbook Documentation,Release 2.x ’Profile’ => array(’sex’ => ’Male’, ’occupation’ => ’Programmer’), ); For saving a record along with its related records having hasMany association, the data array should be like this: $data = array( ’Article’ => array(’title’ => ’My first article’), ’Comment’ => array( array(’body’ => ’Comment 1’, ’user_id’ => 1), array(’body’ => ’Comment 2’, ’user_id’ => 12), array(’body’ => ’Comment 3’, ’user_id’ => 40), ), ); And for saving a record along with its related records having hasMany with more than two levels deep associations, the data array should be as follow: $data = array( ’User’ => array(’email’ => ’[email protected]’), ’Cart’ => array( array( ’payment_status_id’ => 2, ’total_cost’ => 250, ’CartItem’ => array( array( ’cart_product_id’ => 3, ’quantity’ => 1, ’cost’ => 100, ), array( ’cart_product_id’ => 5, ’quantity’ => 1, ’cost’ => 150, ) ) ) ) ); Note: If successful, the foreign key of the main model will be stored in the related models’ id field, i.e. $this->RelatedModel->id. Warning: Be careful when checking saveAssociated calls with atomic option set to false. It returns an array instead of boolean. Changed in version 2.1: You can now save deeper associated data as well with setting $options[’deep’] = true; For saving a record along with its related records having hasMany association and deeper associated Com- ment belongsTo User data as well, the data array should be like this: 250 Chapter 8. Models
- 257. CakePHP Cookbook Documentation,Release 2.x $data = array( ’Article’ => array(’title’ => ’My first article’), ’Comment’ => array( array(’body’ => ’Comment 1’, ’user_id’ => 1), array( ’body’ => ’Save a new user as well’, ’User’ => array(’first’ => ’mad’, ’last’ => ’coder’) ), ), ); And save this data with: $Article->saveAssociated($data, array(’deep’ => true)); Changed in version 2.1: Model::saveAll() and friends now support passing the fieldList for multiple models. Example of using fieldList with multiple models: $this->SomeModel->saveAll($data, array( ’fieldList’ => array( ’SomeModel’ => array(’field_1’), ’AssociatedModel’ => array(’field_2’, ’field_3’) ) )); The fieldList will be an array of model aliases as keys and arrays with fields as values. The model names are not nested like in the data to be saved. Model::saveAll(array $data = null, array $options = array()) The saveAll function is just a wrapper around the saveMany and saveAssociated methods. it will inspect the data and determine what type of save it should perform. If data is formatted in a numerical indexed array, saveMany will be called, otherwise saveAssociated is used. This function receives the same options as the former two, and is generally a backwards compatible function. It is recommended using either saveMany or saveAssociated depending on the case. Saving Related Model Data (hasOne, hasMany, belongsTo) When working with associated models, it is important to realize that saving model data should always be done by the corresponding CakePHP model. If you are saving a new Post and its associated Comments, then you would use both Post and Comment models during the save operation. If neither of the associated model records exists in the system yet (for example, you want to save a new User and their related Profile records at the same time), you’ll need to first save the primary, or parent model. To get an idea of how this works, let’s imagine that we have an action in our UsersController that handles the saving of a new User and a related Profile. The example action shown below will assume that you’ve POSTed enough data (using the FormHelper) to create a single User and a single Profile: More on models 251
- 258. CakePHP Cookbook Documentation,Release 2.x public function add() { if (!empty($this->request->data)) { // We can save the User data: // it should be in $this->request->data[’User’] $user = $this->User->save($this->request->data); // If the user was saved, Now we add this information to the data // and save the Profile. if (!empty($user)) { // The ID of the newly created user has been set // as $this->User->id. $this->request->data[’Profile’][’user_id’] = $this->User->id; // Because our User hasOne Profile, we can access // the Profile model through the User model: $this->User->Profile->save($this->request->data); } } } As a rule, when working with hasOne, hasMany, and belongsTo associations, it’s all about keying. The basic idea is to get the key from one model and place it in the foreign key field on the other. Sometimes this might involve using the $id attribute of the model class after a save(), but other times it might just involve gathering the ID from a hidden input on a form that’s just been POSTed to a controller action. To supplement the basic approach used above, CakePHP also offers a very handy method saveAssociated(), which allows you to validate and save multiple models in one shot. In addition, saveAssociated() provides transactional support to ensure data integrity in your database (i.e. if one model fails to save, the other models will not be saved either). Note: For transactions to work correctly in MySQL your tables must use InnoDB engine. Remember that MyISAM tables do not support transactions. Let’s see how we can use saveAssociated() to save Company and Account models at the same time. First, you need to build your form for both Company and Account models (we’ll assume that Company hasMany Account): echo $this->Form->create(’Company’, array(’action’ => ’add’)); echo $this->Form->input(’Company.name’, array(’label’ => ’Company name’)); echo $this->Form->input(’Company.description’); echo $this->Form->input(’Company.location’); echo $this->Form->input(’Account.0.name’, array(’label’ => ’Account name’)); echo $this->Form->input(’Account.0.username’); echo $this->Form->input(’Account.0.email’); echo $this->Form->end(’Add’); Take a look at the way we named the form fields for the Account model. If Company is our main model, 252 Chapter 8. Models
- 259. CakePHP Cookbook Documentation,Release 2.x saveAssociated() will expect the related model’s (Account) data to arrive in a specific format. And having Account.0.fieldName is exactly what we need. Note: The above field naming is required for a hasMany association. If the association between the models is hasOne, you have to use ModelName.fieldName notation for the associated model. Now, in our CompaniesController we can create an add() action: public function add() { if (!empty($this->request->data)) { // Use the following to avoid validation errors: unset($this->Company->Account->validate[’company_id’]); $this->Company->saveAssociated($this->request->data); } } That’s all there is to it. Now our Company and Account models will be validated and saved all at the same time. By default saveAssociated will validate all values passed and then try to perform a save for each. Saving hasMany through data Let’s see how data stored in a join table for two models is saved. As shown in the hasMany through (The Join Model) section, the join table is associated to each model using a hasMany type of relationship. Our example involves the Head of Cake School asking us to write an application that allows him to log a student’s attendance on a course with days attended and grade. Take a look at the following code.: // Controller/CourseMembershipController.php class CourseMembershipsController extends AppController { public $uses = array(’CourseMembership’); public function index() { $this->set( ’courseMembershipsList’, $this->CourseMembership->find(’all’) ); } public function add() { if ($this->request->is(’post’)) { if ($this->CourseMembership->saveAssociated($this->request->data)) { return $this->redirect(array(’action’ => ’index’)); } } } } // View/CourseMemberships/add.ctp <?php echo $this->Form->create(’CourseMembership’); ?> <?php echo $this->Form->input(’Student.first_name’); ?> <?php echo $this->Form->input(’Student.last_name’); ?> More on models 253
- 260. CakePHP Cookbook Documentation,Release 2.x <?php echo $this->Form->input(’Course.name’); ?> <?php echo $this->Form->input(’CourseMembership.days_attended’); ?> <?php echo $this->Form->input(’CourseMembership.grade’); ?> <button type="submit">Save</button> <?php echo $this->Form->end(); ?> The data array will look like this when submitted.: Array ( [Student] => Array ( [first_name] => Joe [last_name] => Bloggs ) [Course] => Array ( [name] => Cake ) [CourseMembership] => Array ( [days_attended] => 5 [grade] => A ) ) CakePHP will happily be able to save the lot together and assign the foreign keys of the Student and Course into CourseMembership with a saveAssociated call with this data structure. If we run the index action of our CourseMembershipsController the data structure received now from a find(‘all’) is: Array ( [0] => Array ( [CourseMembership] => Array ( [id] => 1 [student_id] => 1 [course_id] => 1 [days_attended] => 5 [grade] => A ) [Student] => Array ( [id] => 1 [first_name] => Joe [last_name] => Bloggs ) [Course] => Array 254 Chapter 8. Models
- 261. CakePHP Cookbook Documentation,Release 2.x ( [id] => 1 [name] => Cake ) ) ) There are of course many ways to work with a join model. The version above assumes you want to save everything at-once. There will be cases where you want to create the Student and Course independently and at a later point associate the two together with a CourseMembership. So you might have a form that allows selection of existing students and courses from pick lists or ID entry and then the two meta-fields for the CourseMembership, e.g.: // View/CourseMemberships/add.ctp <?php echo $this->Form->create(’CourseMembership’); ?> <?php echo $this->Form->input( ’Student.id’, array( ’type’ => ’text’, ’label’ => ’Student ID’, ’default’ => 1 ) ); ?> <?php echo $this->Form->input( ’Course.id’, array( ’type’ => ’text’, ’label’ => ’Course ID’, ’default’ => 1 ) ); ?> <?php echo $this->Form->input(’CourseMembership.days_attended’); ?> <?php echo $this->Form->input(’CourseMembership.grade’); ?> <button type="submit">Save</button> <?php echo $this->Form->end(); ?> And the resultant POST: Array ( [Student] => Array ( [id] => 1 ) [Course] => Array ( [id] => 1 More on models 255
- 262. CakePHP Cookbook Documentation,Release 2.x ) [CourseMembership] => Array ( [days_attended] => 10 [grade] => 5 ) ) Again CakePHP is good to us and pulls the Student id and Course id into the CourseMembership with the saveAssociated. Saving Related Model Data (HABTM) Saving models that are associated by hasOne, belongsTo, and hasMany is pretty simple: you just populate the foreign key field with the ID of the associated model. Once that’s done, you just call the save() method on the model, and everything gets linked up correctly. An example of the required format for the data array passed to save() for the Tag model is shown below: Array ( [Recipe] => Array ( [id] => 42 ) [Tag] => Array ( [name] => Italian ) ) You can also use this format to save several records and their HABTM associations with saveAll(), using an array like the following: Array ( [0] => Array ( [Recipe] => Array ( [id] => 42 ) [Tag] => Array ( [name] => Italian ) ) [1] => Array ( [Recipe] => Array ( [id] => 43 256 Chapter 8. Models
- 263. CakePHP Cookbook Documentation,Release 2.x ) [Tag] => Array ( [name] => Pasta ) ) [2] => Array ( [Recipe] => Array ( [id] => 51 ) [Tag] => Array ( [name] => Mexican ) ) [3] => Array ( [Recipe] => Array ( [id] => 17 ) [Tag] => Array ( [name] => American (new) ) ) ) Passing the above array to saveAll() will create the contained tags, each associated with their respective recipes. Another example that is helpful is when you need to save many Tags to a Post. You need to pass the associated HABTM data in the following HABTM array format. Note you only need to pass in the id’s of the associated HABTM model however it needs to be nested again: Array ( [0] => Array ( [Post] => Array ( [title] => ’Saving HABTM arrays’ ) [Tag] => Array ( [Tag] => Array(1, 2, 5, 9) ) ) [1] => Array ( [Post] => Array More on models 257
- 264. CakePHP Cookbook Documentation,Release 2.x ( [title] => ’Dr Who’s Name is Revealed’ ) [Tag] => Array ( [Tag] => Array(7, 9, 15, 19) ) ) [2] => Array ( [Post] => Array ( [title] => ’I Came, I Saw and I Conquered’ ) [Tag] => Array ( [Tag] => Array(11, 12, 15, 19) ) ) [3] => Array ( [Post] => Array ( [title] => ’Simplicity is the Ultimate Sophistication ’ ) [Tag] => Array ( [Tag] => Array(12, 22, 25, 29) ) ) ) Passing the above array to saveAll($data, array(’deep’ => true)) will populate the posts_tags join table with the Tag to Post associations. As an example, we’ll build a form that creates a new tag and generates the proper data array to associate it on the fly with some recipe. The simplest form might look something like this (we’ll assume that $recipe_id is already set to some- thing): <?php echo $this->Form->create(’Tag’); ?> <?php echo $this->Form->input( ’Recipe.id’, array(’type’ => ’hidden’, ’value’ => $recipe_id) ); ?> <?php echo $this->Form->input(’Tag.name’); ?> <?php echo $this->Form->end(’Add Tag’); ?> In this example, you can see the Recipe.id hidden field whose value is set to the ID of the recipe we want to link the tag to. When the save() method is invoked within the controller, it’ll automatically save the HABTM data to the database: 258 Chapter 8. Models
- 265. CakePHP Cookbook Documentation,Release 2.x public function add() { // Save the association if ($this->Tag->save($this->request->data)) { // do something on success } } With the preceding code, our new Tag is created and associated with a Recipe, whose ID was set in $this->request->data[’Recipe’][’id’]. Other ways we might want to present our associated data can include a select drop down list. The data can be pulled from the model using the find(’list’) method and assigned to a view variable of the model name. An input with the same name will automatically pull in this data into a <select>: // in the controller: $this->set(’tags’, $this->Recipe->Tag->find(’list’)); // in the view: $this->Form->input(’tags’); A more likely scenario with a HABTM relationship would include a <select> set to allow multiple selections. For example, a Recipe can have multiple Tags assigned to it. In this case, the data is pulled out of the model the same way, but the form input is declared slightly different. The tag name is defined using the ModelName convention: // in the controller: $this->set(’tags’, $this->Recipe->Tag->find(’list’)); // in the view: $this->Form->input(’Tag’); Using the preceding code, a multiple select drop down is created, allowing for multiple choices to automat- ically be saved to the existing Recipe being added or saved to the database. Self HABTM Normally HABTM is used to bring 2 models together but it can also be used with only 1 model, though it requires some extra attention. The key is in the model setup the className. Simply adding a Project HABTM Project relation causes issues saving data. By setting the className to the models name and use the alias as key we avoid those issues.: class Project extends AppModel { public $hasAndBelongsToMany = array( ’RelatedProject’ => array( ’className’ => ’Project’, ’foreignKey’ => ’projects_a_id’, ’associationForeignKey’ => ’projects_b_id’, ), ); } Creating form elements and saving the data works the same as before but you use the alias instead. This: More on models 259
- 266. CakePHP Cookbook Documentation,Release 2.x $this->set(’projects’, $this->Project->find(’list’)); $this->Form->input(’Project’); Becomes this: $this->set(’relatedProjects’, $this->Project->find(’list’)); $this->Form->input(’RelatedProject’); What to do when HABTM becomes complicated? By default when saving a HasAndBelongsToMany relationship, CakePHP will delete all rows on the join table before saving new ones. For example if you have a Club that has 10 Children associated. You then update the Club with 2 children. The Club will only have 2 Children, not 12. Also note that if you want to add more fields to the join (when it was created or meta information) this is possible with HABTM join tables, but it is important to understand that you have an easy option. HasAndBelongsToMany between two models is in reality shorthand for three models associated through both a hasMany and a belongsTo association. Consider this example: Child hasAndBelongsToMany Club Another way to look at this is adding a Membership model: Child hasMany Membership Membership belongsTo Child, Club Club hasMany Membership. These two examples are almost the exact same. They use the same amount of named fields in the database and the same amount of models. The important differences are that the “join” model is named differently and its behavior is more predictable. Tip: When your join table contains extra fields besides two foreign keys, you can prevent losing the extra field values by setting ’unique’ array key to ’keepExisting’. You could think of this similar to ‘unique’ => true, but without losing data from the extra fields during save operation. Additionally, if you used bake in order to create the models, this is set automatically. See: HABTM association arrays. However, in most cases it’s easier to make a model for the join table and setup hasMany, belongsTo associ- ations as shown in example above instead of using HABTM association. Datatables While CakePHP can have datasources that aren’t database driven, most of the time, they are. CakePHP is designed to be agnostic and will work with MySQL, MSSQL, PostgreSQL and others. You can create your database tables as you normally would. When you create your Model classes, they’ll automatically map to the tables that you’ve created. Table names are by convention lowercase and pluralized with multi-word table names separated by underscores. For example, a Model name of Ingredient expects the table name in- gredients. A Model name of EventRegistration would expect a table name of event_registrations. CakePHP 260 Chapter 8. Models
- 267. CakePHP Cookbook Documentation,Release 2.x will inspect your tables to determine the data type of each field and uses this information to automate various features such as outputting form fields in the view. Field names are by convention lowercase and separated by underscores. Using created and modified By defining a created and/or modified field in your database table as datetime fields (default null), CakePHP will recognize those fields and populate them automatically whenever a record is created or saved to the database (unless the data being saved already contains a value for these fields). The created and modified fields will be set to the current date and time when the record is initially added. The modified field will be updated with the current date and time whenever the existing record is saved. If you have created or modified data in your $this->data (e.g. from a Model::read or Model::set) before a Model::save() then the values will be taken from $this->data and not automagically updated. If you don’t want that you can use unset($this->data[’Model’][’modified’]), etc. Alternatively you can override the Model::save() to always do it for you: class AppModel extends Model { public function save($data = null, $validate = true, $fieldList = array()) { // Clear modified field value before each save $this->set($data); if (isset($this->data[$this->alias][’modified’])) { unset($this->data[$this->alias][’modified’]); } return parent::save($this->data, $validate, $fieldList); } } Deleting Data CakePHP’s Model class offers a few ways to delete records from your database. delete delete(integer $id = null, boolean $cascade = true); Deletes the record identified by $id. By default, also deletes records dependent on the record specified to be deleted. For example, when deleting a User record that is tied to many Recipe records (User ‘hasMany’ or ‘hasAnd- BelongsToMany’ Recipes): • if $cascade is set to true, the related Recipe records are also deleted if the model’s dependent-value is set to true. • if $cascade is set to false, the Recipe records will remain after the User has been deleted. More on models 261
- 268. CakePHP Cookbook Documentation,Release 2.x If your database supports foreign keys and cascading deletes, it’s often more efficient to rely on that feature than CakePHP’s cascading. The one benefit to using the cascade feature of Model::delete() is that it allows you to leverage behaviors and model callbacks: $this->Comment->delete($this->request->data(’Comment.id’)); You can hook custom logic into the delete process using the beforeDelete and afterDelete call- backs present in both Models and Behaviors. See Callback Methods for more information. deleteAll deleteAll(mixed $conditions, $cascade = true, $callbacks = false) deleteAll() is similar to delete(), except that deleteAll() will delete all records that match the supplied conditions. The $conditions array should be supplied as a SQL fragment or array. • conditions Conditions to match • cascade Boolean, Set to true to delete records that depend on this record • callbacks Boolean, Run callbacks Return boolean True on success, false on failure. Example: // Delete with array conditions similar to find() $this->Comment->deleteAll(array(’Comment.spam’ => true), false); If you delete with either callbacks and/or cascade, rows will be found and then deleted. This will often result in more queries being issued. Associations will be reset before the matched records are deleted in deleteAll(). If you use bindModel() or unbindModel() to change the associations, you should set reset to false. Note: deleteAll() will return true even if no records are deleted, as the conditions for the delete query were successful and no matching records remain. Data Validation Data validation is an important part of any application, as it helps to make sure that the data in a Model conforms to the business rules of the application. For example, you might want to make sure that passwords are at least eight characters long, or ensure that usernames are unique. Defining validation rules makes form handling much, much easier. There are many different aspects to the validation process. What we’ll cover in this section is the model side of things. Essentially: what happens when you call the save() method of your model. For more information about how to handle the displaying of validation errors, check out FormHelper. The first step to data validation is creating the validation rules in the Model. To do that, use the Model::validate array in the Model definition, for example: 262 Chapter 8. Models
- 269. CakePHP Cookbook Documentation,Release 2.x class User extends AppModel { public $validate = array(); } In the example above, the $validate array is added to the User Model, but the array contains no validation rules. Assuming that the users table has login, password, email and born fields, the example below shows some simple validation rules that apply to those fields: class User extends AppModel { public $validate = array( ’login’ => ’alphaNumeric’, ’email’ => ’email’, ’born’ => ’date’ ); } This last example shows how validation rules can be added to model fields. For the login field, only letters and numbers will be accepted, the email should be valid, and born should be a valid date. Defining validation rules enables CakePHP’s automagic showing of error messages in forms if the data submitted does not follow the defined rules. CakePHP has many validation rules and using them can be quite easy. Some of the built-in rules allow you to verify the formatting of emails, URLs, and credit card numbers – but we’ll cover these in detail later on. Here is a more complex validation example that takes advantage of some of these built-in validation rules: class User extends AppModel { public $validate = array( ’login’ => array( ’alphaNumeric’ => array( ’rule’ => ’alphaNumeric’, ’required’ => true, ’message’ => ’Letters and numbers only’ ), ’between’ => array( ’rule’ => array(’between’, 5, 15), ’message’ => ’Between 5 to 15 characters’ ) ), ’password’ => array( ’rule’ => array(’minLength’, ’8’), ’message’ => ’Minimum 8 characters long’ ), ’email’ => ’email’, ’born’ => array( ’rule’ => ’date’, ’message’ => ’Enter a valid date’, ’allowEmpty’ => true ) ); } Two validation rules are defined for login: it should contain letters and numbers only, and its length should be between 5 and 15. The password field should be a minimum of 8 characters long. The email should More on models 263
- 270. CakePHP Cookbook Documentation,Release 2.x be a valid email address, and born should be a valid date. Also, notice how you can define specific error messages that CakePHP will use when these validation rules fail. As the example above shows, a single field can have multiple validation rules. And if the built-in rules do not match your criteria, you can always add your own validation rules as required. Now that you’ve seen the big picture on how validation works, let’s look at how these rules are defined in the model. There are three different ways that you can define validation rules: simple arrays, single rule per field, and multiple rules per field. Simple Rules As the name suggests, this is the simplest way to define a validation rule. The general syntax for defining rules this way is: public $validate = array(’fieldName’ => ’ruleName’); Where, ‘fieldName’ is the name of the field the rule is defined for, and ‘ruleName’ is a pre-defined rule name, such as ‘alphaNumeric’, ‘email’ or ‘isUnique’. For example, to ensure that the user is giving a well formatted email address, you could use this rule: public $validate = array(’user_email’ => ’email’); One Rule Per Field This definition technique allows for better control of how the validation rules work. But before we discuss that, let’s see the general usage pattern adding a rule for a single field: public $validate = array( ’fieldName1’ => array( // or: array(’ruleName’, ’param1’, ’param2’ ...) ’rule’ => ’ruleName’, ’required’ => true, ’allowEmpty’ => false, // or: ’update’ ’on’ => ’create’, ’message’ => ’Your Error Message’ ) ); The ‘rule’ key is required. If you only set ‘required’ => true, the form validation will not function correctly. This is because ‘required’ is not actually a rule. As you can see here, each field (only one field shown above) is associated with an array that contains five keys: ‘rule’, ‘required’, ‘allowEmpty’, ‘on’ and ‘message’. Let’s have a closer look at these keys. 264 Chapter 8. Models
- 271. CakePHP Cookbook Documentation,Release 2.x rule The ‘rule’ key defines the validation method and takes either a single value or an array. The specified ‘rule’ may be the name of a method in your model, a method of the core Validation class, or a regular expression. For more information on the rules available by default, see Core Validation Rules. If the rule does not require any parameters, ‘rule’ can be a single value e.g.: public $validate = array( ’login’ => array( ’rule’ => ’alphaNumeric’ ) ); If the rule requires some parameters (like the max, min or range), ‘rule’ should be an array: public $validate = array( ’password’ => array( ’rule’ => array(’minLength’, 8) ) ); Remember, the ‘rule’ key is required for array-based rule definitions. required This key accepts either a boolean, or create or update. Setting this key to true will make the field always required. While setting it to create or update will make the field required only for update or create operations. If ‘required’ is evaluated to true, the field must be present in the data array. For example, if the validation rule has been defined as follows: public $validate = array( ’login’ => array( ’rule’ => ’alphaNumeric’, ’required’ => true ) ); The data sent to the model’s save() method must contain data for the login field. If it doesn’t, validation will fail. The default value for this key is boolean false. required => true does not mean the same as the validation rule notEmpty(). required => true indicates that the array key must be present - it does not mean it must have a value. Therefore validation will fail if the field is not present in the dataset, but may (depending on the rule) succeed if the value submitted is empty (‘’). Changed in version 2.1: Support for create and update were added. More on models 265
- 272. CakePHP Cookbook Documentation,Release 2.x allowEmpty If set to false, the field value must be nonempty, where “nonempty” is defined as !empty($value) || is_numeric($value). The numeric check is so that CakePHP does the right thing when $value is zero. The difference between required and allowEmpty can be confusing. ’required’ => true means that you cannot save the model without the key for this field being present in $this->data (the check is performed with isset); whereas, ’allowEmpty’ => false makes sure that the current field value is nonempty, as described above. on The ‘on’ key can be set to either one of the following values: ‘update’ or ‘create’. This provides a mechanism that allows a certain rule to be applied either during the creation of a new record, or during update of a record. If a rule has defined ‘on’ => ‘create’, the rule will only be enforced during the creation of a new record. Likewise, if it is defined as ‘on’ => ‘update’, it will only be enforced during the updating of a record. The default value for ‘on’ is null. When ‘on’ is null, the rule will be enforced during both creation and update. message The message key allows you to define a custom validation error message for the rule: public $validate = array( ’password’ => array( ’rule’ => array(’minLength’, 8), ’message’ => ’Password must be at least 8 characters long’ ) ); Note: Regardless of the rule, validation failure without a defined message defaults to “This field cannot be left blank.” Multiple Rules per Field The technique outlined above gives us much more flexibility than simple rules assignment, but there’s an extra step we can take in order to gain more fine-grained control of data validation. The next technique we’ll outline allows us to assign multiple validation rules per model field. If you would like to assign multiple validation rules to a single field, this is basically how it should look: public $validate = array( ’fieldName’ => array( ’ruleName’ => array( ’rule’ => ’ruleName’, 266 Chapter 8. Models
- 273. CakePHP Cookbook Documentation,Release 2.x // extra keys like on, required, etc. go here... ), ’ruleName2’ => array( ’rule’ => ’ruleName2’, // extra keys like on, required, etc. go here... ) ) ); As you can see, this is quite similar to what we did in the previous section. There, for each field we had only one array of validation parameters. In this case, each ‘fieldName’ consists of an array of rule indexes. Each ‘ruleName’ contains a separate array of validation parameters. This is better explained with a practical example: public $validate = array( ’login’ => array( ’loginRule-1’ => array( ’rule’ => ’alphaNumeric’, ’message’ => ’Only alphabets and numbers allowed’, ), ’loginRule-2’ => array( ’rule’ => array(’minLength’, 8), ’message’ => ’Minimum length of 8 characters’ ) ) ); The above example defines two rules for the login field: loginRule-1 and loginRule-2. As you can see, each rule is identified with an arbitrary name. When using multiple rules per field the ‘required’ and ‘allowEmpty’ keys need to be used only once in the first rule. last In case of multiple rules per field by default if a particular rule fails error message for that rule is returned and the following rules for that field are not processed. If you want validation to continue in spite of a rule failing set key last to false for that rule. In the following example even if “rule1” fails “rule2” will be processed and error messages for both failing rules will be returned if “rule2” also fails: public $validate = array( ’login’ => array( ’rule1’ => array( ’rule’ => ’alphaNumeric’, ’message’ => ’Only alphabets and numbers allowed’, ’last’ => false ), ’rule2’ => array( ’rule’ => array(’minLength’, 8), More on models 267
- 274. CakePHP Cookbook Documentation,Release 2.x ’message’ => ’Minimum length of 8 characters’ ) ) ); When specifying validation rules in this array form it’s possible to avoid providing the message key. Consider this example: public $validate = array( ’login’ => array( ’Only alphabets and numbers allowed’ => array( ’rule’ => ’alphaNumeric’, ), ) ); If the alphaNumeric rules fails the array key for this rule ‘Only alphabets and numbers allowed’ will be returned as error message since the message key is not set. Custom Validation Rules If you haven’t found what you need thus far, you can always create your own validation rules. There are two ways you can do this: by defining custom regular expressions, or by creating custom validation methods. Custom Regular Expression Validation If the validation technique you need to use can be completed by using regular expression matching, you can define a custom expression as a field validation rule: public $validate = array( ’login’ => array( ’rule’ => ’/^[a-z0-9]{3,}$/i’, ’message’ => ’Only letters and integers, min 3 characters’ ) ); The example above checks if the login contains only letters and integers, with a minimum of three characters. The regular expression in the rule must be delimited by slashes. The optional trailing ‘i’ after the last slash means the reg-exp is case insensitive. Adding your own Validation Methods Sometimes checking data with regular expression patterns is not enough. For example, if you want to ensure that a promotional code can only be used 25 times, you need to add your own validation function, as shown below: 268 Chapter 8. Models
- 275. CakePHP Cookbook Documentation,Release 2.x class User extends AppModel { public $validate = array( ’promotion_code’ => array( ’rule’ => array(’limitDuplicates’, 25), ’message’ => ’This code has been used too many times.’ ) ); public function limitDuplicates($check, $limit) { // $check will have value: array(’promotion_code’ => ’some-value’) // $limit will have value: 25 $existingPromoCount = $this->find(’count’, array( ’conditions’ => $check, ’recursive’ => -1 )); return $existingPromoCount < $limit; } } The current field to be validated is passed into the function as first parameter as an associated array with field name as key and posted data as value. If you want to pass extra parameters to your validation function, add elements onto the ‘rule’ array, and handle them as extra params (after the main $check param) in your function. Your validation function can be in the model (as in the example above), or in a behavior that the model implements. This includes mapped methods. Model/behavior methods are checked first, before looking for a method on the Validation class. This means that you can override existing validation methods (such as alphaNumeric()) at an application level (by adding the method to AppModel), or at model level. When writing a validation rule which can be used by multiple fields, take care to extract the field value from the $check array. The $check array is passed with the form field name as its key and the field value as its value. The full record being validated is stored in $this->data member variable: class Post extends AppModel { public $validate = array( ’slug’ => array( ’rule’ => ’alphaNumericDashUnderscore’, ’message’ => ’Slug can only be letters,’ . ’ numbers, dash and underscore’ ) ); public function alphaNumericDashUnderscore($check) { // $data array is passed using the form field name as the key // have to extract the value to make the function generic $value = array_values($check); $value = $value[0]; return preg_match(’|^[0-9a-zA-Z_-]*$|’, $value); More on models 269
- 276. CakePHP Cookbook Documentation,Release 2.x } } Note: Your own validation methods must have public visibility. Validation methods that are protected and private are not supported. The method should return true if the value is valid. If the validation failed, return false. The other valid return value are strings which will be shown as the error message. Returning a string means the validation failed. The string will overwrite the message set in the $validate array and be shown in the view’s form as the reason why the field was not valid. Dynamically change validation rules Using the $validate property to declare validation rules is a good way of statically defining rules for each model. Nevertheless, there are cases when you want to dynamically add, change or remove validation rules from the predefined set. All validation rules are stored in a ModelValidator object, which holds every rule set for each field in your model. Defining new validation rules is as easy as telling this object to store new validation methods for the fields you want to. Adding new validation rules New in version 2.2. The ModelValidator objects allows several ways for adding new fields to the set. The first one is using the add method: // Inside a model class $this->validator()->add(’password’, ’required’, array( ’rule’ => ’notEmpty’, ’required’ => ’create’ )); This will add a single rule to the password field in the model. You can chain multiple calls to add to create as many rules as you like: // Inside a model class $this->validator() ->add(’password’, ’required’, array( ’rule’ => ’notEmpty’, ’required’ => ’create’ )) ->add(’password’, ’size’, array( ’rule’ => array(’between’, 8, 20), ’message’ => ’Password should be at least 8 chars long’ )); It is also possible to add multiple rules at once for a single field: 270 Chapter 8. Models
- 277. CakePHP Cookbook Documentation,Release 2.x $this->validator()->add(’password’, array( ’required’ => array( ’rule’ => ’notEmpty’, ’required’ => ’create’ ), ’size’ => array( ’rule’ => array(’between’, 8, 20), ’message’ => ’Password should be at least 8 chars long’ ) )); Alternatively, you can use the validator object to set rules directly to fields using the array interface: $validator = $this->validator(); $validator[’username’] = array( ’unique’ => array( ’rule’ => ’isUnique’, ’required’ => ’create’ ), ’alphanumeric’ => array( ’rule’ => ’alphanumeric’ ) ); Modifying current validation rules New in version 2.2. Modifying current validation rules is also possible using the validator object, there are several ways in which you can alter current rules, append methods to a field or completely remove a rule from a field rule set: // In a model class $this->validator()->getField(’password’)->setRule(’required’, array( ’rule’ => ’required’, ’required’ => true )); You can also completely replace all the rules for a field using a similar method: // In a model class $this->validator()->getField(’password’)->setRules(array( ’required’ => array(...), ’otherRule’ => array(...) )); If you wish to just modify a single property in a rule you can set properties directly into the CakeValidationRule object: // In a model class $this->validator()->getField(’password’) ->getRule(’required’)->message = ’This field cannot be left blank’; More on models 271
- 278. CakePHP Cookbook Documentation,Release 2.x Properties in any CakeValidationRule get their name from the array keys one is allowed to use when defining a validation rule’s properties, such as the array keys ‘message’ and ‘allowEmpty’ for example. As with adding new rule to the set, it is also possible to modify existing rules using the array interface: $validator = $this->validator(); $validator[’username’][’unique’] = array( ’rule’ => ’isUnique’, ’required’ => ’create’ ); $validator[’username’][’unique’]->last = true; $validator[’username’][’unique’]->message = ’Name already taken’; Removing rules from the set New in version 2.2. It is possible to both completely remove all rules for a field and to delete a single rule in a field’s rule set: // Completely remove all rules for a field $this->validator()->remove(’username’); // Remove ’required’ rule from password $this->validator()->remove(’password’, ’required’); Optionally, you can use the array interface to delete rules from the set: $validator = $this->validator(); // Completely remove all rules for a field unset($validator[’username’]); // Remove ’required’ rule from password unset($validator[’password’][’required’]); Core Validation Rules class Validation The Validation class in CakePHP contains many validation rules that can make model data validation much easier. This class contains many oft-used validation techniques you won’t need to write on your own. Below, you’ll find a complete list of all the rules, along with usage examples. static Validation::alphaNumeric(mixed $check) The data for the field must only contain letters and numbers.: public $validate = array( ’login’ => array( ’rule’ => ’alphaNumeric’, ’message’ => ’Usernames must only contain letters and numbers.’ ) ); 272 Chapter 8. Models
- 279. CakePHP Cookbook Documentation,Release 2.x static Validation::between(string $check, integer $min, integer $max) The length of the data for the field must fall within the specified numeric range. Both minimum and maximum values must be supplied. Uses = not.: public $validate = array( ’password’ => array( ’rule’ => array(’between’, 5, 15), ’message’ => ’Passwords must be between 5 and 15 characters long.’ ) ); The length of data is “the number of bytes in the string representation of the data”. Be careful that it may be larger than the number of characters when handling non-ASCII characters. static Validation::blank(mixed $check) This rule is used to make sure that the field is left blank or only white space characters are present in its value. White space characters include space, tab, carriage return, and newline.: public $validate = array( ’id’ => array( ’rule’ => ’blank’, ’on’ => ’create’ ) ); static Validation::boolean(string $check) The data for the field must be a boolean value. Valid values are true or false, integers 0 or 1 or strings ‘0’ or ‘1’.: public $validate = array( ’myCheckbox’ => array( ’rule’ => array(’boolean’), ’message’ => ’Incorrect value for myCheckbox’ ) ); static Validation::cc(mixed $check, mixed $type = ‘fast’, boolean $deep = false, string $regex = null) This rule is used to check whether the data is a valid credit card number. It takes three parameters: ‘type’, ‘deep’ and ‘regex’. The ‘type’ key can be assigned to the values of ‘fast’, ‘all’ or any of the following: •amex •bankcard •diners •disc •electron •enroute •jcb More on models 273
- 280. CakePHP Cookbook Documentation,Release 2.x •maestro •mc •solo •switch •visa •voyager If ‘type’ is set to ‘fast’, it validates the data against the major credit cards’ numbering formats. Setting ‘type’ to ‘all’ will check with all the credit card types. You can also set ‘type’ to an array of the types you wish to match. The ‘deep’ key should be set to a boolean value. If it is set to true, the validation will check the Luhn algorithm of the credit card (http://en.wikipedia.org/wiki/Luhn_algorithm). It defaults to false. The ‘regex’ key allows you to supply your own regular expression that will be used to validate the credit card number: public $validate = array( ’ccnumber’ => array( ’rule’ => array(’cc’, array(’visa’, ’maestro’), false, null), ’message’ => ’The credit card number you supplied was invalid.’ ) ); static Validation::comparison(mixed $check1, string $operator = null, integer $check2 = null) Comparison is used to compare numeric values. It supports “is greater”, “is less”, “greater or equal”, “less or equal”, “equal to”, and “not equal”. Some examples are shown below: public $validate = array( ’age’ => array( ’rule’ => array(’comparison’, ’>=’, 18), ’message’ => ’Must be at least 18 years old to qualify.’ ) ); public $validate = array( ’age’ => array( ’rule’ => array(’comparison’, ’greater or equal’, 18), ’message’ => ’Must be at least 18 years old to qualify.’ ) ); static Validation::custom(mixed $check, string $regex = null) Used when a custom regular expression is needed: public $validate = array( ’infinite’ => array( ’rule’ => array(’custom’, ’u221E’), ’message’ => ’Please enter an infinite number.’ 274 Chapter 8. Models
- 281. CakePHP Cookbook Documentation,Release 2.x ) ); static Validation::date(string $check, mixed $format = ‘ymd’, string $regex = null) This rule ensures that data is submitted in valid date formats. A single parameter (which can be an array) can be passed that will be used to check the format of the supplied date. The value of the parameter can be one of the following: •‘dmy’ e.g. 27-12-2006 or 27-12-06 (separators can be a space, period, dash, forward slash) •‘mdy’ e.g. 12-27-2006 or 12-27-06 (separators can be a space, period, dash, forward slash) •‘ymd’ e.g. 2006-12-27 or 06-12-27 (separators can be a space, period, dash, forward slash) •‘dMy’ e.g. 27 December 2006 or 27 Dec 2006 •‘Mdy’ e.g. December 27, 2006 or Dec 27, 2006 (comma is optional) •‘My’ e.g. (December 2006 or Dec 2006) •‘my’ e.g. 12/2006 or 12/06 (separators can be a space, period, dash, forward slash) •‘ym’ e.g. 2006/12 or 06/12 (separators can be a space, period, dash, forward slash) •‘y’ e.g. 2006 (separators can be a space, period, dash, forward slash) If no keys are supplied, the default key that will be used is ‘ymd’: public $validate = array( ’born’ => array( ’rule’ => array(’date’, ’ymd’), ’message’ => ’Enter a valid date in YY-MM-DD format.’, ’allowEmpty’ => true ) ); While many data stores require a certain date format, you might consider doing the heavy lifting by accepting a wide-array of date formats and trying to convert them, rather than forcing users to supply a given format. The more work you can do for your users, the better. Changed in version 2.4: The ym and y formats were added. static Validation::datetime(array $check, mixed $dateFormat = ‘ymd’, string $regex = null) This rule ensures that the data is a valid datetime format. A parameter (which can be an array) can be passed to specify the format of the date. The value of the parameter can be one or more of the following: •‘dmy’ e.g. 27-12-2006 or 27-12-06 (separators can be a space, period, dash, forward slash) •‘mdy’ e.g. 12-27-2006 or 12-27-06 (separators can be a space, period, dash, forward slash) •‘ymd’ e.g. 2006-12-27 or 06-12-27 (separators can be a space, period, dash, forward slash) •‘dMy’ e.g. 27 December 2006 or 27 Dec 2006 •‘Mdy’ e.g. December 27, 2006 or Dec 27, 2006 (comma is optional) More on models 275
- 282. CakePHP Cookbook Documentation,Release 2.x •‘My’ e.g. (December 2006 or Dec 2006) •‘my’ e.g. 12/2006 or 12/06 (separators can be a space, period, dash, forward slash) If no keys are supplied, the default key that will be used is ‘ymd’: public $validate = array( ’birthday’ => array( ’rule’ => array(’datetime’, ’dmy’), ’message’ => ’Please enter a valid date and time.’ ) ); Also a second parameter can be passed to specify a custom regular expression. If this parameter is used, this will be the only validation that will occur. Note that unlike date(), datetime() will validate a date and a time. static Validation::decimal(string $check, integer $places = null, string $regex = null) This rule ensures that the data is a valid decimal number. A parameter can be passed to specify the number of digits required after the decimal point. If no parameter is passed, the data will be validated as a scientific float, which will cause validation to fail if no digits are found after the decimal point: public $validate = array( ’price’ => array( ’rule’ => array(’decimal’, 2) ) ); static Validation::email(string $check, boolean $deep = false, string $regex = null) This checks whether the data is a valid email address. Passing a boolean true as the second parameter for this rule will also attempt to verify that the host for the address is valid: public $validate = array(’email’ => array(’rule’ => ’email’)); public $validate = array( ’email’ => array( ’rule’ => array(’email’, true), ’message’ => ’Please supply a valid email address.’ ) ); static Validation::equalTo(mixed $check, mixed $compareTo) This rule will ensure that the value is equal to, and of the same type as the given value. public $validate = array( ’food’ => array( ’rule’ => array(’equalTo’, ’cake’), ’message’ => ’This value must be the string cake’ ) ); static Validation::extension(mixed $check, array $extensions = array(‘gif’, ‘jpeg’, ‘png’, ‘jpg’)) This rule checks for valid file extensions like .jpg or .png. Allow multiple extensions by passing them 276 Chapter 8. Models
- 283. CakePHP Cookbook Documentation,Release 2.x in array form. public $validate = array( ’image’ => array( ’rule’ => array( ’extension’, array(’gif’, ’jpeg’, ’png’, ’jpg’) ), ’message’ => ’Please supply a valid image.’ ) ); static Validation::fileSize($check, $operator = null, $size = null) This rule allows you to check filesizes. You can use $operator to decide the type of comparison you want to use. All the operators supported by comparison() are supported here as well. This method will automatically handle array values from $_FILES by reading from the tmp_name key if $check is an array an contains that key: public $validate = array( ’image’ => array( ’rule’ => array(’fileSize’, ’<=’, ’1MB’), ’message’ => ’Image must be less than 1MB’ ) ); New in version 2.3: This method was added in 2.3 static Validation::inList(string $check, array $list, boolean $caseInsensitive = false) This rule will ensure that the value is in a given set. It needs an array of values. The field is valid if the field’s value matches one of the values in the given array. Example: public $validate = array( ’function’ => array( ’allowedChoice’ => array( ’rule’ => array(’inList’, array(’Foo’, ’Bar’)), ’message’ => ’Enter either Foo or Bar.’ ) ) ); Comparison is case sensitive by default. You can set $caseInsensitive to true if you need case insensitive comparison. static Validation::ip(string $check, string $type = ‘both’) This rule will ensure that a valid IPv4 or IPv6 address has been submitted. Accepts as option ‘both’ (default), ‘IPv4’ or ‘IPv6’. public $validate = array( ’clientip’ => array( ’rule’ => array(’ip’, ’IPv4’), // or ’IPv6’ or ’both’ (default) ’message’ => ’Please supply a valid IP address.’ ) More on models 277
- 284. CakePHP Cookbook Documentation,Release 2.x ); Model::isUnique() The data for the field must be unique, it cannot be used by any other rows: public $validate = array( ’login’ => array( ’rule’ => ’isUnique’, ’message’ => ’This username has already been taken.’ ) ); You can validate that a set of fields are unique by providing multiple fields and set $or to false: public $validate = array( ’email’ => array( ’rule’ => array(’isUnique’, array(’email’, ’username’), false), ’message’ => ’This username & email combination has already been used.’ ) ); Make sure to include the original field in the list of fields when making a unique rule across multiple fields. If a listed field isn’t included in the model data, then it’s treated as a null value. You may consider marking the listed fields as required. static Validation::luhn(string|array $check, boolean $deep = false) The Luhn algorithm: A checksum formula to validate a variety of identification numbers. See http://en.wikipedia.org/wiki/Luhn_algorithm for more information. static Validation::maxLength(string $check, integer $max) This rule ensures that the data stays within a maximum length requirement. public $validate = array( ’login’ => array( ’rule’ => array(’maxLength’, 15), ’message’ => ’Usernames must be no larger than 15 characters long.’ ) ); The length here is “the number of bytes in the string representation of the data”. Be careful that it may be larger than the number of characters when handling non-ASCII characters. static Validation::mimeType(mixed $check, array|string $mimeTypes) New in version 2.2. This rule checks for valid mime types. Comparison is case sensitive. Changed in version 2.5. Since 2.5 $mimeTypes can be a regex string. public $validate = array( ’image’ => array( 278 Chapter 8. Models
- 285. CakePHP Cookbook Documentation,Release 2.x ’rule’ => array(’mimeType’, array(’image/gif’)), ’message’ => ’Invalid mime type.’ ), ’logo’ => array( ’rule’ => array(’mimeType’, ’#image/.+#’), ’message’ => ’Invalid mime type.’ ), ); static Validation::minLength(string $check, integer $min) This rule ensures that the data meets a minimum length requirement. public $validate = array( ’login’ => array( ’rule’ => array(’minLength’, 8), ’message’ => ’Usernames must be at least 8 characters long.’ ) ); The length here is “the number of bytes in the string representation of the data”. Be careful that it may be larger than the number of characters when handling non-ASCII characters. static Validation::money(string $check, string $symbolPosition = ‘left’) This rule will ensure that the value is in a valid monetary amount. Second parameter defines where symbol is located (left/right). public $validate = array( ’salary’ => array( ’rule’ => array(’money’, ’left’), ’message’ => ’Please supply a valid monetary amount.’ ) ); static Validation::multiple(mixed $check, mixed $options = array(), boolean $caseInsensi- tive = false) Use this for validating a multiple select input. It supports parameters “in”, “max” and “min”. public $validate = array( ’multiple’ => array( ’rule’ => array(’multiple’, array( ’in’ => array(’do’, ’re’, ’mi’, ’fa’, ’sol’, ’la’, ’ti’), ’min’ => 1, ’max’ => 3 )), ’message’ => ’Please select one, two or three options’ ) ); Comparison is case sensitive by default. You can set $caseInsensitive to true if you need case insensitive comparison. static Validation::notEmpty(mixed $check) The basic rule to ensure that a field is not empty.: More on models 279
- 286. CakePHP Cookbook Documentation,Release 2.x public $validate = array( ’title’ => array( ’rule’ => ’notEmpty’, ’message’ => ’This field cannot be left blank’ ) ); Do not use this for a multiple select input as it will cause an error. Instead, use “multiple”. static Validation::numeric(string $check) Checks if the data passed is a valid number.: public $validate = array( ’cars’ => array( ’rule’ => ’numeric’, ’message’ => ’Please supply the number of cars.’ ) ); static Validation::naturalNumber(mixed $check, boolean $allowZero = false) New in version 2.2. This rule checks if the data passed is a valid natural number. If $allowZero is set to true, zero is also accepted as a value. public $validate = array( ’wheels’ => array( ’rule’ => ’naturalNumber’, ’message’ => ’Please supply the number of wheels.’ ), ’airbags’ => array( ’rule’ => array(’naturalNumber’, true), ’message’ => ’Please supply the number of airbags.’ ), ); static Validation::phone(mixed $check, string $regex = null, string $country = ‘all’) Phone validates US phone numbers. If you want to validate non-US phone numbers, you can provide a regular expression as the second parameter to cover additional number formats. public $validate = array( ’phone’ => array( ’rule’ => array(’phone’, null, ’us’) ) ); static Validation::postal(mixed $check, string $regex = null, string $country = ‘us’) Postal is used to validate ZIP codes from the U.S. (us), Canada (ca), U.K (uk), Italy (it), Germany (de) and Belgium (be). For other ZIP code formats, you may provide a regular expression as the second parameter. public $validate = array( ’zipcode’ => array( ’rule’ => array(’postal’, null, ’us’) 280 Chapter 8. Models
- 287. CakePHP Cookbook Documentation,Release 2.x ) ); static Validation::range(string $check, integer $lower = null, integer $upper = null) This rule ensures that the value is in a given range. If no range is supplied, the rule will check to ensure the value is a legal finite on the current platform. public $validate = array( ’number’ => array( ’rule’ => array(’range’, -1, 11), ’message’ => ’Please enter a number between -1 and 11’ ) ); The above example will accept any value which is larger than -1 (e.g., -0.99) and less than 11 (e.g., 10.99). Note: The range lower/upper are not inclusive static Validation::ssn(mixed $check, string $regex = null, string $country = null) Ssn validates social security numbers from the U.S. (us), Denmark (dk), and the Netherlands (nl). For other social security number formats, you may provide a regular expression. public $validate = array( ’ssn’ => array( ’rule’ => array(’ssn’, null, ’us’) ) ); static Validation::time(string $check) Time validation, determines if the string passed is a valid time. Validates time as 24hr (HH:MM) or am/pm ([H]H:MM[a|p]m) Does not allow/validate seconds. static Validation::uploadError(mixed $check) New in version 2.2. This rule checks if a file upload has an error. public $validate = array( ’image’ => array( ’rule’ => ’uploadError’, ’message’ => ’Something went wrong with the upload.’ ), ); static Validation::url(string $check, boolean $strict = false) This rule checks for valid URL formats. Supports http(s), ftp(s), file, news, and gopher protocols: public $validate = array( ’website’ => array( ’rule’ => ’url’ ) ); More on models 281
- 288. CakePHP Cookbook Documentation,Release 2.x To ensure that a protocol is in the url, strict mode can be enabled like so: public $validate = array( ’website’ => array( ’rule’ => array(’url’, true) ) ); This validation method uses a complex regular expression that can sometimes cause issues with Apache2 on Windows using mod_php. static Validation::userDefined(mixed $check, object $object, string $method, array $args = null) Runs an user-defined validation. static Validation::uuid(string $check) Checks that a value is a valid UUID: http://tools.ietf.org/html/rfc4122 Localized Validation The validation rules phone() and postal() will pass off any country prefix they do not know how to handle to another class with the appropriate name. For example if you lived in the Netherlands you would create a class like: class NlValidation { public static function phone($check) { // ... } public static function postal($check) { // ... } } This file could be placed in APP/Validation/ or App/PluginName/Validation/, but must be imported via App::uses() before attempting to use it. In your model validation you could use your NlVali- dation class by doing the following: public $validate = array( ’phone_no’ => array(’rule’ => array(’phone’, null, ’nl’)), ’postal_code’ => array(’rule’ => array(’postal’, null, ’nl’)), ); When your model data is validated, Validation will see that it cannot handle the nl locale and will attempt to delegate out to NlValidation::postal() and the return of that method will be used as the pass/fail for the validation. This approach allows you to create classes that handle a subset or group of locales, something that a large switch would not have. The usage of the individual validation methods has not changed, the ability to pass off to another validator has been added. Tip: The Localized Plugin already contains a lot of rules ready to use: https://github.com/cakephp/localized Also feel free to contribute with your localized validation rules. 282 Chapter 8. Models
- 289. CakePHP Cookbook Documentation,Release 2.x Validating Data from the Controller While normally you would just use the save method of the model, there may be times where you wish to validate the data without saving it. For example, you may wish to display some additional information to the user before actually saving the data to the database. Validating data requires a slightly different process than just saving the data. First, set the data to the model: $this->ModelName->set($this->request->data); Then, to check if the data validates, use the validates method of the model, which will return true if it validates and false if it doesn’t: if ($this->ModelName->validates()) { // it validated logic } else { // didn’t validate logic $errors = $this->ModelName->validationErrors; } It may be desirable to validate your model only using a subset of the validations specified in your model. For example say you had a User model with fields for first_name, last_name, email and password. In this instance when creating or editing a user you would want to validate all 4 field rules. Yet when a user logs in you would validate just email and password rules. To do this you can pass an options array specifying the fields to validate: if ($this->User->validates(array(’fieldList’ => array(’email’, ’password’)))) { // valid } else { // invalid } The validates method invokes the invalidFields method which populates the validationErrors property of the model. The invalidFields method also returns that data as the result: $errors = $this->ModelName->invalidFields(); // contains validationErrors array The validation errors list is not cleared between successive calls to invalidFields() So if you are validating in a loop and want each set of errors separately don’t use invalidFields(). Instead use validates() and access the validationErrors model property. It is important to note that the data must be set to the model before the data can be validated. This is different from the save method which allows the data to be passed in as a parameter. Also, keep in mind that it is not required to call validates prior to calling save as save will automatically validate the data before actually saving. To validate multiple models, the following approach should be used: if ($this->ModelName->saveAll( $this->request->data, array(’validate’ => ’only’) )) { // validates More on models 283
- 290. CakePHP Cookbook Documentation,Release 2.x } else { // does not validate } If you have validated data before save, you can turn off validation to avoid second check: if ($this->ModelName->saveAll( $this->request->data, array(’validate’ => false) )) { // saving without validation } Callback Methods If you want to sneak in some logic just before or after a CakePHP model operation, use model callbacks. These functions can be defined in model classes (including your AppModel) class. Be sure to note the expected return values for each of these special functions. When using callback methods you should remember that behavior callbacks are fired before model callbacks are. beforeFind beforeFind(array $query) Called before any find-related operation. The $query passed to this callback contains information about the current query: conditions, fields, etc. If you do not wish the find operation to begin (possibly based on a decision relating to the $query options), return false. Otherwise, return the possibly modified $query, or anything you want to get passed to find and its counterparts. You might use this callback to restrict find operations based on a user’s role, or make caching decisions based on the current load. afterFind afterFind(array $results, boolean $primary = false) Use this callback to modify results that have been returned from a find operation, or to perform any other post-find logic. The $results parameter passed to this callback contains the returned results from the model’s find operation, i.e. something like: $results = array( 0 => array( ’ModelName’ => array( ’field1’ => ’value1’, ’field2’ => ’value2’, ), 284 Chapter 8. Models
- 291. CakePHP Cookbook Documentation,Release 2.x ), ); The return value for this callback should be the (possibly modified) results for the find operation that trig- gered this callback. The $primary parameter indicates whether or not the current model was the model that the query origi- nated on or whether or not this model was queried as an association. If a model is queried as an association the format of $results can differ; instead of the result you would normally get from a find operation, you may get this: $results = array( ’field_1’ => ’value1’, ’field_2’ => ’value2’ ); Warning: Code expecting $primary to be true will probably get a “Cannot use string offset as an array” fatal error from PHP if a recursive find is used. Below is an example of how afterfind can be used for date formatting: public function afterFind($results, $primary = false) { foreach ($results as $key => $val) { if (isset($val[’Event’][’begindate’])) { $results[$key][’Event’][’begindate’] = $this->dateFormatAfterFind( $val[’Event’][’begindate’] ); } } return $results; } public function dateFormatAfterFind($dateString) { return date(’d-m-Y’, strtotime($dateString)); } beforeValidate beforeValidate(array $options = array()) Use this callback to modify model data before it is validated, or to modify validation rules if required. This function must also return true, otherwise the current save() execution will abort. afterValidate afterValidate() Called after data has been checked for errors. Use this callback to perform any data cleanup or preparation if needed. More on models 285
- 292. CakePHP Cookbook Documentation,Release 2.x beforeSave beforeSave(array $options = array()) Place any pre-save logic in this function. This function executes immediately after model data has been successfully validated, but just before the data is saved. This function should also return true if you want the save operation to continue. This callback is especially handy for any data-massaging logic that needs to happen before your data is stored. If your storage engine needs dates in a specific format, access it at $this->data and modify it. Below is an example of how beforeSave can be used for date conversion. The code in the example is used for an application with a begindate formatted like YYYY-MM-DD in the database and is displayed like DD-MM-YYYY in the application. Of course this can be changed very easily. Use the code below in the appropriate model. public function beforeSave($options = array()) { if (!empty($this->data[’Event’][’begindate’]) && !empty($this->data[’Event’][’enddate’]) ) { $this->data[’Event’][’begindate’] = $this->dateFormatBeforeSave( $this->data[’Event’][’begindate’] ); $this->data[’Event’][’enddate’] = $this->dateFormatBeforeSave( $this->data[’Event’][’enddate’] ); } return true; } public function dateFormatBeforeSave($dateString) { return date(’Y-m-d’, strtotime($dateString)); } Tip: Be sure that beforeSave() returns true, or your save is going to fail. afterSave afterSave(boolean $created, array $options = array()) If you have logic you need to be executed just after every save operation, place it in this callback method. The saved data will be available in $this->data. The value of $created will be true if a new record was created (rather than an update). The $options array is the same one passed to Model::save(). beforeDelete beforeDelete(boolean $cascade = true) 286 Chapter 8. Models
- 293. CakePHP Cookbook Documentation,Release 2.x Place any pre-deletion logic in this function. This function should return true if you want the deletion to continue, and false if you want to abort. The value of $cascade will be true if records that depend on this record will also be deleted. Tip: Be sure that beforeDelete() returns true, or your delete is going to fail. // using app/Model/ProductCategory.php // In the following example, do not let a product category be deleted if it // still contains products. // A call of $this->Product->delete($id) from ProductsController.php has set // $this->id . // Assuming ’ProductCategory hasMany Product’, we can access $this->Product // in the model. public function beforeDelete($cascade = true) { $count = $this->Product->find("count", array( "conditions" => array("product_category_id" => $this->id) )); if ($count == 0) { return true; } else { return false; } } afterDelete afterDelete() Place any logic that you want to be executed after every deletion in this callback method. // perhaps after deleting a record from the database, you also want to delete // an associated file public function afterDelete() { $file = new File($this->data[’SomeModel’][’file_path’]); $file->delete(); } onError onError() Called if any problems occur. Behaviors Model behaviors are a way to organize some of the functionality defined in CakePHP models. They allow us to separate and reuse logic that creates a type of behavior, and they do this without requiring inheritance. For example creating tree structures. By providing a simple yet powerful way to enhance models, behaviors More on models 287
- 294. CakePHP Cookbook Documentation,Release 2.x allow us to attach functionality to models by defining a simple class variable. That’s how behaviors allow models to get rid of all the extra weight that might not be part of the business contract they are modeling, or that is also needed in different models and can then be extrapolated. As an example, consider a model that gives us access to a database table which stores structural information about a tree. Removing, adding, and migrating nodes in the tree is not as simple as deleting, inserting, and editing rows in the table. Many records may need to be updated as things move around. Rather than creating those tree-manipulation methods on a per model basis (for every model that needs that functionality), we could simply tell our model to use the TreeBehavior, or in more formal terms, we tell our model to behave as a Tree. This is known as attaching a behavior to a model. With just one line of code, our CakePHP model takes on a whole new set of methods that allow it to interact with the underlying structure. CakePHP already includes behaviors for tree structures, translated content, access control list interac- tion, not to mention the community-contributed behaviors already available in the CakePHP Bakery (http://bakery.cakephp.org). In this section, we’ll cover the basic usage pattern for adding behaviors to models, how to use CakePHP’s built-in behaviors, and how to create our own. In essence, Behaviors are Mixins1 with callbacks. There are a number of Behaviors included in CakePHP. To find out more about each one, reference the chapters below: ACL class AclBehavior The Acl behavior provides a way to seamlessly integrate a model with your ACL system. It can create both AROs or ACOs transparently. To use the new behavior, you can add it to the $actsAs property of your model. When adding it to the actsAs array you choose to make the related Acl entry an ARO or an ACO. The default is to create ACOs: class User extends AppModel { public $actsAs = array(’Acl’ => array(’type’ => ’requester’)); } This would attach the Acl behavior in ARO mode. To join the ACL behavior in ACO mode use: class Post extends AppModel { public $actsAs = array(’Acl’ => array(’type’ => ’controlled’)); } For User and Group models it is common to have both ACO and ARO nodes, to achieve this use: class User extends AppModel { public $actsAs = array(’Acl’ => array(’type’ => ’both’)); } You can also attach the behavior on the fly like so: 1 http://en.wikipedia.org/wiki/Mixin 288 Chapter 8. Models
- 295. CakePHP Cookbook Documentation,Release 2.x $this->Post->Behaviors->load(’Acl’, array(’type’ => ’controlled’)); Changed in version 2.1: You can now safely attach AclBehavior to AppModel. Aco, Aro and AclNode now extend Model instead of AppModel, which would cause an infinite loop. If your application depends on having those models to extend AppModel for some reason, then copy AclNode to your application and have it extend AppModel again. Using the AclBehavior Most of the AclBehavior works transparently on your Model’s afterSave(). However, using it requires that your Model has a parentNode() method defined. This is used by the AclBehavior to determine parent->child relationships. A model’s parentNode() method must return null or return a parent Model reference: public function parentNode() { return null; } If you want to set an ACO or ARO node as the parent for your Model, parentNode() must return the alias of the ACO or ARO node: public function parentNode() { return ’root_node’; } A more complete example. Using an example User Model, where User belongsTo Group: public function parentNode() { if (!$this->id && empty($this->data)) { return null; } $data = $this->data; if (empty($this->data)) { $data = $this->read(); } if (!$data[’User’][’group_id’]) { return null; } else { return array(’Group’ => array(’id’ => $data[’User’][’group_id’])); } } In the above example the return is an array that looks similar to the results of a model find. It is important to have the id value set or the parentNode relation will fail. The AclBehavior uses this data to construct its tree structure. node() The AclBehavior also allows you to retrieve the Acl node associated with a model record. After setting $model->id. You can use $model->node() to retrieve the associated Acl node. More on models 289
- 296. CakePHP Cookbook Documentation,Release 2.x You can also retrieve the Acl Node for any row, by passing in a data array: $this->User->id = 1; $node = $this->User->node(); $user = array(’User’ => array( ’id’ => 1 )); $node = $this->User->node($user); Will both return the same Acl Node information. If you had setup AclBehavior to create both ACO and ARO nodes, you need to specify which node type you want: $this->User->id = 1; $node = $this->User->node(null, ’Aro’); $user = array(’User’ => array( ’id’ => 1 )); $node = $this->User->node($user, ’Aro’); Containable class ContainableBehavior A new addition to the CakePHP 1.2 core is the ContainableBehavior. This model behavior allows you to filter and limit model find operations. Using Containable will help you cut down on needless wear and tear on your database, increasing the speed and overall performance of your application. The class will also help you search and filter your data for your users in a clean and consistent way. Containable allows you to streamline and simplify operations on your model bindings. It works by temporar- ily or permanently altering the associations of your models. It does this by using supplied the containments to generate a series of bindModel and unbindModel calls. Since Containable only modifies existing relationships it will not allow you to restrict results by distant associations. Instead you should refer to Joining tables. To use the new behavior, you can add it to the $actsAs property of your model: class Post extends AppModel { public $actsAs = array(’Containable’); } You can also attach the behavior on the fly: $this->Post->Behaviors->load(’Containable’); Using Containable To see how Containable works, let’s look at a few examples. First, we’ll start off with a find() call on a model named ‘Post’. Let’s say that ‘Post’ hasMany ‘Comment’, and ‘Post’ hasAndBelongsToMany ‘Tag’. 290 Chapter 8. Models
- 297. CakePHP Cookbook Documentation,Release 2.x The amount of data fetched in a normal find() call is rather extensive: debug($this->Post->find(’all’)); [0] => Array ( [Post] => Array ( [id] => 1 [title] => First article [content] => aaa [created] => 2008-05-18 00:00:00 ) [Comment] => Array ( [0] => Array ( [id] => 1 [post_id] => 1 [author] => Daniel [email] => [email protected] [website] => http://example.com [comment] => First comment [created] => 2008-05-18 00:00:00 ) [1] => Array ( [id] => 2 [post_id] => 1 [author] => Sam [email] => [email protected] [website] => http://example.net [comment] => Second comment [created] => 2008-05-18 00:00:00 ) ) [Tag] => Array ( [0] => Array ( [id] => 1 [name] => Awesome ) [1] => Array ( [id] => 2 [name] => Baking ) ) ) [1] => Array ( [Post] => Array (... More on models 291
- 298. CakePHP Cookbook Documentation,Release 2.x For some interfaces in your application, you may not need that much information from the Post model. One thing the ContainableBehavior does is help you cut down on what find() returns. For example, to get only the post-related information, you can do the following: $this->Post->contain(); $this->Post->find(’all’); You can also invoke Containable’s magic from inside the find() call: $this->Post->find(’all’, array(’contain’ => false)); Having done that, you end up with something a lot more concise: [0] => Array ( [Post] => Array ( [id] => 1 [title] => First article [content] => aaa [created] => 2008-05-18 00:00:00 ) ) [1] => Array ( [Post] => Array ( [id] => 2 [title] => Second article [content] => bbb [created] => 2008-05-19 00:00:00 ) ) This sort of help isn’t new: in fact, you can do that without the ContainableBehavior doing something like this: $this->Post->recursive = -1; $this->Post->find(’all’); Containable really shines when you have complex associations, and you want to pare down things that sit at the same level. The model’s $recursive property is helpful if you want to hack off an entire level of recursion, but not when you want to pick and choose what to keep at each level. Let’s see how it works by using the contain() method. The contain method’s first argument accepts the name, or an array of names, of the models to keep in the find operation. If we wanted to fetch all posts and their related tags (without any comment information), we’d try something like this: $this->Post->contain(’Tag’); $this->Post->find(’all’); Again, we can use the contain key inside a find() call: 292 Chapter 8. Models
- 299. CakePHP Cookbook Documentation,Release 2.x $this->Post->find(’all’, array(’contain’ => ’Tag’)); Without Containable, you’d end up needing to use the unbindModel() method of the model, multiple times if you’re paring off multiple models. Containable creates a cleaner way to accomplish this same task. Containing deeper associations Containable also goes a step deeper: you can filter the data of the associated models. If you look at the results of the original find() call, notice the author field in the Comment model. If you are interested in the posts and the names of the comment authors — and nothing else — you could do something like the following: $this->Post->contain(’Comment.author’); $this->Post->find(’all’); // or.. $this->Post->find(’all’, array(’contain’ => ’Comment.author’)); Here, we’ve told Containable to give us our post information, and just the author field of the associated Comment model. The output of the find call might look something like this: [0] => Array ( [Post] => Array ( [id] => 1 [title] => First article [content] => aaa [created] => 2008-05-18 00:00:00 ) [Comment] => Array ( [0] => Array ( [author] => Daniel [post_id] => 1 ) [1] => Array ( [author] => Sam [post_id] => 1 ) ) ) [1] => Array (... As you can see, the Comment arrays only contain the author field (plus the post_id which is needed by CakePHP to map the results). You can also filter the associated Comment data by specifying a condition: More on models 293
- 300. CakePHP Cookbook Documentation,Release 2.x $this->Post->contain(’Comment.author = "Daniel"’); $this->Post->find(’all’); //or... $this->Post->find(’all’, array(’contain’ => ’Comment.author = "Daniel"’)); This gives us a result that gives us posts with comments authored by Daniel: [0] => Array ( [Post] => Array ( [id] => 1 [title] => First article [content] => aaa [created] => 2008-05-18 00:00:00 ) [Comment] => Array ( [0] => Array ( [id] => 1 [post_id] => 1 [author] => Daniel [email] => [email protected] [website] => http://example.com [comment] => First comment [created] => 2008-05-18 00:00:00 ) ) ) There is an important caveat to using Containable when filtering on a deeper association. In the previous example, assume you had 3 posts in your database and Daniel had commented on 2 of those posts. The operation $this->Post->find(‘all’, array(‘contain’ => ‘Comment.author = “Daniel”’)); would return ALL 3 posts, not just the 2 posts that Daniel had commented on. It won’t return all comments however, just comments by Daniel.: [0] => Array ( [Post] => Array ( [id] => 1 [title] => First article [content] => aaa [created] => 2008-05-18 00:00:00 ) [Comment] => Array ( [0] => Array ( [id] => 1 294 Chapter 8. Models
- 301. CakePHP Cookbook Documentation,Release 2.x [post_id] => 1 [author] => Daniel [email] => [email protected] [website] => http://example.com [comment] => First comment [created] => 2008-05-18 00:00:00 ) ) ) [1] => Array ( [Post] => Array ( [id] => 2 [title] => Second article [content] => bbb [created] => 2008-05-18 00:00:00 ) [Comment] => Array ( ) ) [2] => Array ( [Post] => Array ( [id] => 3 [title] => Third article [content] => ccc [created] => 2008-05-18 00:00:00 ) [Comment] => Array ( [0] => Array ( [id] => 22 [post_id] => 3 [author] => Daniel [email] => [email protected] [website] => http://example.com [comment] => Another comment [created] => 2008-05-18 00:00:00 ) ) ) If you want to filter the posts by the comments, so that posts without a comment by Daniel won’t be returned, the easiest way is to find all the comments by Daniel and contain the Posts.: $this->Comment->find(’all’, array( ’conditions’ => ’Comment.author = "Daniel"’, ’contain’ => ’Post’ )); More on models 295
- 302. CakePHP Cookbook Documentation,Release 2.x Additional filtering can be performed by supplying the standard find options: $this->Post->find(’all’, array(’contain’ => array( ’Comment’ => array( ’conditions’ => array(’Comment.author =’ => "Daniel"), ’order’ => ’Comment.created DESC’ ) ))); Here’s an example of using the ContainableBehavior when you’ve got deep and complex model relationships. Let’s consider the following model associations: User->Profile User->Account->AccountSummary User->Post->PostAttachment->PostAttachmentHistory->HistoryNotes User->Post->Tag This is how we retrieve the above associations with Containable: $this->User->find(’all’, array( ’contain’ => array( ’Profile’, ’Account’ => array( ’AccountSummary’ ), ’Post’ => array( ’PostAttachment’ => array( ’fields’ => array(’id’, ’name’), ’PostAttachmentHistory’ => array( ’HistoryNotes’ => array( ’fields’ => array(’id’, ’note’) ) ) ), ’Tag’ => array( ’conditions’ => array(’Tag.name LIKE’ => ’%happy%’) ) ) ) )); Keep in mind that contain key is only used once in the main model, you don’t need to use ‘contain’ again for related models. Note: When using ‘fields’ and ‘contain’ options - be careful to include all foreign keys that your query directly or indirectly requires. Please also note that because Containable must to be attached to all models used in containment, you may consider attaching it to your AppModel. 296 Chapter 8. Models
- 303. CakePHP Cookbook Documentation,Release 2.x ContainableBehavior options The ContainableBehavior has a number of options that can be set when the Behavior is attached to a model. The settings allow you to fine tune the behavior of Containable and work with other behaviors more easily. • recursive (boolean, optional) set to true to allow containable to automatically determine the recur- siveness level needed to fetch specified models, and set the model recursiveness to this level. setting it to false disables this feature. The default value is true. • notices (boolean, optional) issues E_NOTICES for bindings referenced in a containable call that are not valid. The default value is true. • autoFields: (boolean, optional) auto-add needed fields to fetch requested bindings. The default value is true. • order: (string, optional) the order of how the contained elements are sorted. From the previous example, this is an example of how to force the posts to be ordered by the date when they were last updated: $this->User->find(’all’, array( ’contain’ => array( ’Profile’, ’Post’ => array( ’order’ => ’Post.updated DESC’ ) ) )); You can change ContainableBehavior settings at run time by reattaching the behavior as seen in Behaviors (Using Behaviors). ContainableBehavior can sometimes cause issues with other behaviors or queries that use aggregate func- tions and/or GROUP BY statements. If you get invalid SQL errors due to mixing of aggregate and non- aggregate fields, try disabling the autoFields setting.: $this->Post->Behaviors->load(’Containable’, array(’autoFields’ => false)); Using Containable with pagination By including the ‘contain’ parameter in the $paginate property it will apply to both the find(‘count’) and the find(‘all’) done on the model. See the section Using Containable for further details. Here’s an example of how to contain associations when paginating: $this->paginate[’User’] = array( ’contain’ => array(’Profile’, ’Account’), ’order’ => ’User.username’ ); $users = $this->paginate(’User’); More on models 297
- 304. CakePHP Cookbook Documentation,Release 2.x Note: If you contained the associations through the model instead, it will not honor Containable’s recursive option. So if you set recursive to -1 for example for the model, it won’t work: $this->User->recursive = -1; $this->User->contain(array(’Profile’, ’Account’)); $users = $this->paginate(’User’); Translate class TranslateBehavior TranslateBehavior is actually quite easy to setup and works out of the box with very little configuration. In this section, you will learn how to add and setup the behavior to use in any model. If you are using TranslateBehavior in alongside containable issue, be sure to set the ‘fields’ key for your queries. Otherwise you could end up with invalid SQL generated. Initializing the i18n Database Tables You can either use the CakePHP console or you can manually create it. It is advised to use the console for this, because it might happen that the layout changes in future versions of CakePHP. Sticking to the console will make sure that you have the correct layout.: ./cake i18n Select [I] which will run the i18n database initialization script. You will be asked if you want to drop any existing and if you want to create it. Answer with yes if you are sure there is no i18n table already, and answer with yes again to create the table. Attaching the Translate Behavior to your Models Add it to your model by using the $actsAs property like in the following example.: class Post extends AppModel { public $actsAs = array( ’Translate’ ); } This will do nothing yet, because it expects a couple of options before it begins to work. You need to define which fields of the current model should be tracked in the translation table we’ve created in the first step. Defining the Fields You can set the fields by simply extending the ’Translate’ value with another array, like so: 298 Chapter 8. Models
- 305. CakePHP Cookbook Documentation,Release 2.x class Post extends AppModel { public $actsAs = array( ’Translate’ => array( ’fieldOne’, ’fieldTwo’, ’and_so_on’ ) ); } After you have done that (for example putting “title” as one of the fields) you already finished the basic setup. Great! According to our current example the model should now look something like this: class Post extends AppModel { public $actsAs = array( ’Translate’ => array( ’title’ ) ); } When defining fields for TranslateBehavior to translate, be sure to omit those fields from the translated model’s schema. If you leave the fields in, there can be issues when retrieving data with fallback locales. Note: If all the fields in your model are translated be sure to add created and modified columns to your table. CakePHP requires at least one non primary key field before it will save a record. Conclusion From now on each record update/creation will cause TranslateBehavior to copy the value of “title” to the translation table (default: i18n) along with the current locale. A locale is the identifier of the language, so to speak. Reading translated content By default the TranslateBehavior will automatically fetch and add in data based on the current locale. The current locale is read from Configure::read(’Config.language’) which is assigned by the L10n class. You can override this default on the fly using $Model->locale. Retrieve translated fields in a specific locale By setting $Model->locale you can read translations for a specific locale: // Read the spanish locale data. $this->Post->locale = ’es’; $results = $this->Post->find(’first’, array( ’conditions’ => array(’Post.id’ => $id) )); // $results will contain the spanish translation. More on models 299
- 306. CakePHP Cookbook Documentation,Release 2.x Retrieve all translation records for a field If you want to have all translation records attached to the current model record you simply extend the field array in your behavior setup as shown below. The naming is completely up to you.: class Post extends AppModel { public $actsAs = array( ’Translate’ => array( ’title’ => ’titleTranslation’ ) ); } With this setup the result of $this->Post->find() should look something like this: Array ( [Post] => Array ( [id] => 1 [title] => Beispiel Eintrag [body] => lorem ipsum... [locale] => de_de ) [titleTranslation] => Array ( [0] => Array ( [id] => 1 [locale] => en_us [model] => Post [foreign_key] => 1 [field] => title [content] => Example entry ) [1] => Array ( [id] => 2 [locale] => de_de [model] => Post [foreign_key] => 1 [field] => title [content] => Beispiel Eintrag ) ) ) Note: The model record contains a virtual field called “locale”. It indicates which locale is used in this result. Note that only fields of the model you are directly doing ‘find‘ on will be translated. Models attached via as- 300 Chapter 8. Models
- 307. CakePHP Cookbook Documentation,Release 2.x sociations won’t be translated because triggering callbacks on associated models is currently not supported. Using the bindTranslation method You can also retrieve all translations, only when you need them, using the bindTranslation method TranslateBehavior::bindTranslation($fields, $reset) $fields is a named-key array of field and association name, where the key is the translatable field and the value is the fake association name.: $this->Post->bindTranslation(array(’title’ => ’titleTranslation’)); // need at least recursive 1 for this to work. $this->Post->find(’all’, array(’recursive’ => 1)); With this setup the result of your find() should look something like this: Array ( [Post] => Array ( [id] => 1 [title] => Beispiel Eintrag [body] => lorem ipsum... [locale] => de_de ) [titleTranslation] => Array ( [0] => Array ( [id] => 1 [locale] => en_us [model] => Post [foreign_key] => 1 [field] => title [content] => Example entry ) [1] => Array ( [id] => 2 [locale] => de_de [model] => Post [foreign_key] => 1 [field] => title [content] => Beispiel Eintrag ) ) ) More on models 301
- 308. CakePHP Cookbook Documentation,Release 2.x Saving in another language You can force the model which is using the TranslateBehavior to save in a language other than the one detected. To tell a model in what language the content is going to be you simply change the value of the $locale property on the model before you save the data to the database. You can do that either in your controller or you can define it directly in the model. Example A: In your controller: class PostsController extends AppController { public function add() { if (!empty($this->request->data)) { // we are going to save the german version $this->Post->locale = ’de_de’; $this->Post->create(); if ($this->Post->save($this->request->data)) { return $this->redirect(array(’action’ => ’index’)); } } } } Example B: In your model: class Post extends AppModel { public $actsAs = array( ’Translate’ => array( ’title’ ) ); // Option 1) just define the property directly public $locale = ’en_us’; // Option 2) create a simple method public function setLanguage($locale) { $this->locale = $locale; } } Multiple Translation Tables If you expect a lot entries you probably wonder how to deal with a rapidly growing database table. There are two properties introduced by TranslateBehavior that allow to specify which “Model” to bind as the model containing the translations. These are $translateModel and $translateTable. Lets say we want to save our translations for all posts in the table “post_i18ns” instead of the default “i18n” table. To do so you need to setup your model like this: 302 Chapter 8. Models
- 309. CakePHP Cookbook Documentation,Release 2.x class Post extends AppModel { public $actsAs = array( ’Translate’ => array( ’title’ ) ); // Use a different model (and table) public $translateModel = ’PostI18n’; } Note: It is important that you to pluralize the table. It is now a usual model and can be treated as such and thus comes with the conventions involved. The table schema itself must be identical with the one generated by the CakePHP console script. To make sure it fits one could just initialize a empty i18n table using the console and rename the table afterwards. Create the TranslateModel For this to work you need to create the actual model file in your models folder. Reason is that there is no property to set the displayField directly in the model using this behavior yet. Make sure that you change the $displayField to ’field’.: class PostI18n extends AppModel { public $displayField = ’field’; // important } // filename: PostI18n.php That’s all it takes. You can also add all other model stuff here like $useTable. But for better consis- tency we could do that in the model which actually uses this translation model. This is where the optional $translateTable comes into play. Changing the Table If you want to change the name of the table you simply define $translateTable in your model, like so: class Post extends AppModel { public $actsAs = array( ’Translate’ => array( ’title’ ) ); // Use a different model public $translateModel = ’PostI18n’; // Use a different table for translateModel public $translateTable = ’post_translations’; } Please note that you can’t use $translateTable alone. If you don’t intend to use a custom $translateModel then leave this property untouched. Reason is that it would break your setup and More on models 303
- 310. CakePHP Cookbook Documentation,Release 2.x show you a “Missing Table” message for the default I18n model which is created in runtime. Tree class TreeBehavior It’s fairly common to want to store hierarchical data in a database table. Examples of such data might be categories with unlimited subcategories, data related to a multilevel menu system or a literal representation of hierarchy such as is used to store access control objects with ACL logic. For small trees of data, or where the data is only a few levels deep it is simple to add a parent_id field to your database table and use this to keep track of which item is the parent of what. Bundled with cake however, is a powerful behavior which allows you to use the benefits of MPTT logic2 without worrying about any of the intricacies of the technique - unless you want to ;). Requirements To use the tree behavior, your database table needs 3 fields as listed below (all are ints): • parent - default fieldname is parent_id, to store the id of the parent object • left - default fieldname is lft, to store the lft value of the current row. • right - default fieldname is rght, to store the rght value of the current row. If you are familiar with MPTT logic you may wonder why a parent field exists - quite simply it’s easier to do certain tasks if a direct parent link is stored on the database - such as finding direct children. Note: The parent field must be able to have a NULL value! It might seem to work if you just give the top elements a parent value of zero, but reordering the tree (and possible other operations) will fail. Basic Usage The tree behavior has a lot packed into it, but let’s start with a simple example - create the following database table and put some data in it: CREATE TABLE categories ( id INTEGER(10) UNSIGNED NOT NULL AUTO_INCREMENT, parent_id INTEGER(10) DEFAULT NULL, lft INTEGER(10) DEFAULT NULL, rght INTEGER(10) DEFAULT NULL, name VARCHAR(255) DEFAULT ’’, PRIMARY KEY (id) ); INSERT INTO ‘categories‘ (‘id‘, ‘name‘, ‘parent_id‘, ‘lft‘, ‘rght‘) VALUES 2 http://www.sitepoint.com/hierarchical-data-database-2/ 304 Chapter 8. Models
- 311. CakePHP Cookbook Documentation,Release 2.x (1, ’My Categories’, NULL, 1, 30); INSERT INTO ‘categories‘ (‘id‘, ‘name‘, ‘parent_id‘, ‘lft‘, ‘rght‘) VALUES (2, ’Fun’, 1, 2, 15); INSERT INTO ‘categories‘ (‘id‘, ‘name‘, ‘parent_id‘, ‘lft‘, ‘rght‘) VALUES (3, ’Sport’, 2, 3, 8); INSERT INTO ‘categories‘ (‘id‘, ‘name‘, ‘parent_id‘, ‘lft‘, ‘rght‘) VALUES (4, ’Surfing’, 3, 4, 5); INSERT INTO ‘categories‘ (‘id‘, ‘name‘, ‘parent_id‘, ‘lft‘, ‘rght‘) VALUES (5, ’Extreme knitting’, 3, 6, 7); INSERT INTO ‘categories‘ (‘id‘, ‘name‘, ‘parent_id‘, ‘lft‘, ‘rght‘) VALUES (6, ’Friends’, 2, 9, 14); INSERT INTO ‘categories‘ (‘id‘, ‘name‘, ‘parent_id‘, ‘lft‘, ‘rght‘) VALUES (7, ’Gerald’, 6, 10, 11); INSERT INTO ‘categories‘ (‘id‘, ‘name‘, ‘parent_id‘, ‘lft‘, ‘rght‘) VALUES (8, ’Gwendolyn’, 6, 12, 13); INSERT INTO ‘categories‘ (‘id‘, ‘name‘, ‘parent_id‘, ‘lft‘, ‘rght‘) VALUES (9, ’Work’, 1, 16, 29); INSERT INTO ‘categories‘ (‘id‘, ‘name‘, ‘parent_id‘, ‘lft‘, ‘rght‘) VALUES (10, ’Reports’, 9, 17, 22); INSERT INTO ‘categories‘ (‘id‘, ‘name‘, ‘parent_id‘, ‘lft‘, ‘rght‘) VALUES (11, ’Annual’, 10, 18, 19); INSERT INTO ‘categories‘ (‘id‘, ‘name‘, ‘parent_id‘, ‘lft‘, ‘rght‘) VALUES (12, ’Status’, 10, 20, 21); INSERT INTO ‘categories‘ (‘id‘, ‘name‘, ‘parent_id‘, ‘lft‘, ‘rght‘) VALUES (13, ’Trips’, 9, 23, 28); INSERT INTO ‘categories‘ (‘id‘, ‘name‘, ‘parent_id‘, ‘lft‘, ‘rght‘) VALUES (14, ’National’, 13, 24, 25); More on models 305
- 312. CakePHP Cookbook Documentation,Release 2.x INSERT INTO ‘categories‘ (‘id‘, ‘name‘, ‘parent_id‘, ‘lft‘, ‘rght‘) VALUES (15, ’International’, 13, 26, 27); For the purpose of checking that everything is setup correctly, we can create a test method and output the contents of our category tree to see what it looks like. With a simple controller: class CategoriesController extends AppController { public function index() { $data = $this->Category->generateTreeList( null, null, null, ’ ’ ); debug($data); die; } } and an even simpler model definition: // app/Model/Category.php class Category extends AppModel { public $actsAs = array(’Tree’); } We can check what our category tree data looks like by visiting /categories You should see something like this: • My Categories – Fun * Sport · Surfing · Extreme knitting * Friends · Gerald · Gwendolyn – Work * Reports · Annual · Status * Trips · National 306 Chapter 8. Models
- 313. CakePHP Cookbook Documentation,Release 2.x · International Adding data In the previous section, we used existing data and checked that it looked hierarchal via the method generateTreeList. However, usually you would add your data in exactly the same way as you would for any model. For example: // pseudo controller code $data[’Category’][’parent_id’] = 3; $data[’Category’][’name’] = ’Skating’; $this->Category->save($data); When using the tree behavior it’s not necessary to do any more than set the parent_id, and the tree behavior will take care of the rest. If you don’t set the parent_id, the tree behavior will add to the tree making your new addition a new top level entry: // pseudo controller code $data = array(); $data[’Category’][’name’] = ’Other People’s Categories’; $this->Category->save($data); Running the above two code snippets would alter your tree as follows: • My Categories – Fun * Sport · Surfing · Extreme knitting · Skating New * Friends · Gerald · Gwendolyn – Work * Reports · Annual · Status * Trips · National · International • Other People’s Categories New More on models 307
- 314. CakePHP Cookbook Documentation,Release 2.x Modifying data Modifying data is as transparent as adding new data. If you modify something, but do not change the parent_id field - the structure of your data will remain unchanged. For example: // pseudo controller code $this->Category->id = 5; // id of Extreme knitting $this->Category->save(array(’name’ => ’Extreme fishing’)); The above code did not affect the parent_id field - even if the parent_id is included in the data that is passed to save if the value doesn’t change, neither does the data structure. Therefore the tree of data would now look like: • My Categories • Fun • Sport – Surfing – Extreme fishing Updated – Skating • Friends – Gerald – Gwendolyn • Work • Reports – Annual – Status • Trips – National – International • Other People’s Categories Moving data around in your tree is also a simple affair. Let’s say that Extreme fishing does not belong under Sport, but instead should be located under Other People’s Categories. With the following code: // pseudo controller code $this->Category->id = 5; // id of Extreme fishing $newParentId = $this->Category->field( ’id’, array(’name’ => ’Other People’s Categories’) ); $this->Category->save(array(’parent_id’ => $newParentId)); As would be expected the structure would be modified to: • My Categories 308 Chapter 8. Models
- 315. CakePHP Cookbook Documentation,Release 2.x • Fun – Sport * Surfing * Skating – Friends * Gerald * Gwendolyn • Work – Reports * Annual * Status – Trips * National * International • Other People’s Categories • Extreme fishing Moved Deleting data The tree behavior provides a number of ways to manage deleting data. To start with the simplest example; let’s say that the reports category is no longer useful. To remove it and any children it may have just call delete as you would for any model. For example with the following code: // pseudo controller code $this->Category->id = 10; $this->Category->delete(); The category tree would be modified as follows: • My Categories • Fun – Sport * Surfing * Skating – Friends * Gerald * Gwendolyn • Work More on models 309
- 316. CakePHP Cookbook Documentation,Release 2.x – Trips * National * International • Other People’s Categories • Extreme fishing Querying and using your data Using and manipulating hierarchical data can be a tricky business. In addition to the core find methods, with the tree behavior there are a few more tree-orientated permutations at your disposal. Note: Most tree behavior methods return and rely on data being sorted by the lft field. If you call find() and do not order by lft, or call a tree behavior method and pass a sort order, you may get undesirable results. class TreeBehavior children($id = null, $direct = false, $fields = null, $order = null, $limit = null, $page = 1, $recursive = null) Parameters • $id – The ID of the record to look up • $direct – Set to true to return only the direct descendants • $fields – Single string field name or array of fields to include in the return • $order – SQL string of ORDER BY conditions • $limit – SQL LIMIT statement • $page – for accessing paged results • $recursive – Number of levels deep for recursive associated Models The children method takes the primary key value (the id) of a row and returns the children, by default in the order they appear in the tree. The second optional parameter defines whether or not only direct children should be returned. Using the example data from the previous section: $allChildren = $this->Category->children(1); // a flat array with 11 items // -- or -- $this->Category->id = 1; $allChildren = $this->Category->children(); // a flat array with 11 items // Only return direct children $directChildren = $this->Category->children(1, true); // a flat array with // 2 items Note: If you want a recursive array use find(’threaded’) 310 Chapter 8. Models
- 317. CakePHP Cookbook Documentation,Release 2.x childCount($id = null, $direct = false) As with the method children, childCount takes the primary key value (the id) of a row and returns how many children it has. The second optional parameter defines whether or not only direct children are counted. Using the example data from the previous section: $totalChildren = $this->Category->childCount(1); // will output 11 // -- or -- $this->Category->id = 1; $directChildren = $this->Category->childCount(); // will output 11 // Only counts the direct descendants of this category $numChildren = $this->Category->childCount(1, true); // will output 2 generateTreeList($conditions=null, $keyPath=null, $valuePath=null, $spacer= ‘_’, $recursive=null) Parameters • $conditions – Uses the same conditional options as find(). • $keyPath – Path to the field to use for the key. • $valuePath – Path to the field to use for the label. • $spacer – The string to use in front of each item to indicate depth. • $recursive – The number of levels deep to fetch associated records This method will return data similar to find(‘list’) but with a nested prefix that is specified in the spacer option to show the structure of your data. Below is an example of what you can expect this method to return: $treelist = $this->Category->generateTreeList(); Output: array( [1] => "My Categories", [2] => "_Fun", [3] => "__Sport", [4] => "___Surfing", [16] => "___Skating", [6] => "__Friends", [7] => "___Gerald", [8] => "___Gwendolyn", [9] => "_Work", [13] => "__Trips", [14] => "___National", [15] => "___International", [17] => "Other People’s Categories", [5] => "_Extreme fishing" ) More on models 311
- 318. CakePHP Cookbook Documentation,Release 2.x getParentNode() This convenience function will, as the name suggests, return the parent node for any node, or false if the node has no parent (it’s the root node). For example: $parent = $this->Category->getParentNode(2); //<- id for fun // $parent contains All categories getPath($id = null, $fields = null, $recursive = null) The ‘path’ when referring to hierarchal data is how you get from where you are to the top. So for example the path from the category “International” is: •My Categories •... •Work –Trips *... *International Using the id of “International” getPath will return each of the parents in turn (starting from the top).: $parents = $this->Category->getPath(15); // contents of $parents array( [0] => array( ’Category’ => array(’id’ => 1, ’name’ => ’My Categories’, ..) ), [1] => array( ’Category’ => array(’id’ => 9, ’name’ => ’Work’, ..) ), [2] => array( ’Category’ => array(’id’ => 13, ’name’ => ’Trips’, ..) ), [3] => array( ’Category’ => array(’id’ => 15, ’name’ => ’International’, ..) ), ) Advanced Usage The tree behavior doesn’t only work in the background, there are a number of specific meth- ods defined in the behavior to cater for all your hierarchical data needs, and any unexpected problems that might arise in the process. TreeBehavior::moveDown() 312 Chapter 8. Models
- 319. CakePHP Cookbook Documentation,Release 2.x Used to move a single node down the tree. You need to provide the ID of the element to be moved and a positive number of how many positions the node should be moved down. All child nodes for the specified node will also be moved. Here is an example of a controller action (in a controller named Categories) that moves a spec- ified node down the tree: public function movedown($id = null, $delta = null) { $this->Category->id = $id; if (!$this->Category->exists()) { throw new NotFoundException(__(’Invalid category’)); } if ($delta > 0) { $this->Category->moveDown($this->Category->id, abs($delta)); } else { $this->Session->setFlash( ’Please provide the number of positions the field should be’ . ’moved down.’ ); } return $this->redirect(array(’action’ => ’index’)); } For example, if you’d like to move the “Sport” ( id of 3 ) category one position down, you would request: /categories/movedown/3/1. TreeBehavior::moveUp() Used to move a single node up the tree. You need to provide the ID of the element to be moved and a positive number of how many positions the node should be moved up. All child nodes will also be moved. Here’s an example of a controller action (in a controller named Categories) that moves a node up the tree: public function moveup($id = null, $delta = null) { $this->Category->id = $id; if (!$this->Category->exists()) { throw new NotFoundException(__(’Invalid category’)); } if ($delta > 0) { $this->Category->moveUp($this->Category->id, abs($delta)); } else { $this->Session->setFlash( ’Please provide a number of positions the category should’ . ’be moved up.’ ); } return $this->redirect(array(’action’ => ’index’)); } More on models 313
- 320. CakePHP Cookbook Documentation,Release 2.x For example, if you would like to move the category “Gwendolyn” ( id of 8 ) up one position you would request /categories/moveup/8/1. Now the order of Friends will be Gwendolyn, Gerald. TreeBehavior::removeFromTree($id = null, $delete = false) Using this method will either delete or move a node but retain its sub-tree, which will be re- parented one level higher. It offers more control than delete, which for a model using the tree behavior will remove the specified node and all of its children. Taking the following tree as a starting point: • My Categories – Fun * Sport · Surfing · Extreme knitting · Skating Running the following code with the id for ‘Sport’: $this->Node->removeFromTree($id); The Sport node will be become a top level node: • My Categories – Fun * Surfing * Extreme knitting * Skating • Sport Moved This demonstrates the default behavior of removeFromTree of moving the node to have no parent, and re-parenting all children. If however the following code snippet was used with the id for ‘Sport’: $this->Node->removeFromTree($id, true); The tree would become • My Categories – Fun * Surfing * Extreme knitting * Skating 314 Chapter 8. Models
- 321. CakePHP Cookbook Documentation,Release 2.x This demonstrates the alternate use for removeFromTree, the children have been reparented and ‘Sport’ has been deleted. TreeBehavior::reorder(array(‘id’ => null, ‘field’ => $Model->displayField, ‘order’ => ‘ASC’, ‘verify’ => true)) Reorders the nodes (and child nodes) of the tree according to the field and direction specified in the parameters. This method does not change the parent of any node.: $model->reorder(array( //id of record to use as top node for reordering, default: $Model->id ’id’ => , //which field to use in reordering, default: $Model->displayField ’field’ => , //direction to order, default: ’ASC’ ’order’ => , //whether or not to verify the tree before reorder, default: true ’verify’ => )); Note: If you have saved your data or made other operations on the model, you might want to set $model->id = null before calling reorder. Otherwise only the current node and it’s children will be reordered. Data Integrity Due to the nature of complex self referential data structures such as trees and linked lists, they can occasionally become broken by a careless call. Take heart, for all is not lost! The Tree Behavior contains several previously undocumented features designed to recover from such situations. TreeBehavior::recover($mode = ‘parent’, $missingParentAction = null) The mode parameter is used to specify the source of info that is valid/correct. The opposite source of data will be populated based upon that source of info. E.g. if the MPTT fields are corrupt or empty, with the $mode ’parent’ the values of the parent_id field will be used to populate the left and right fields. The missingParentAction parameter only applies to “parent” mode and determines what to do if the parent field contains an id that is not present. Available $mode options: • ’parent’ - use the existing parent_id‘s to update the lft and rght fields • ’tree’ - use the existing lft and rght fields to update parent_id Available missingParentActions options when using mode=’parent’: • null - do nothing and carry on • ’return’ - do nothing and return • ’delete’ - delete the node • int - set the parent_id to this id More on models 315
- 322. CakePHP Cookbook Documentation,Release 2.x Example: // Rebuild all the left and right fields based on the parent_id $this->Category->recover(); // or $this->Category->recover(’parent’); // Rebuild all the parent_id’s based on the lft and rght fields $this->Category->recover(’tree’); TreeBehavior::reorder($options = array()) Reorders the nodes (and child nodes) of the tree according to the field and direction specified in the parameters. This method does not change the parent of any node. Reordering affects all nodes in the tree by default, however the following options can affect the process: • ’id’ - only reorder nodes below this node. • ’field‘ - field to use for sorting, default is the displayField for the model. • ’order’ - ’ASC’ for ascending, ’DESC’ for descending sort. • ’verify’ - whether or not to verify the tree prior to resorting. $options is used to pass all extra parameters, and has the following possible keys by default, all of which are optional: array( ’id’ => null, ’field’ => $model->displayField, ’order’ => ’ASC’, ’verify’ => true ) TreeBehavior::verify() Returns true if the tree is valid otherwise an array of errors, with fields for type, incorrect index and message. Each record in the output array is an array of the form (type, id, message) • type is either ’index’ or ’node’ • ’id’ is the id of the erroneous node. • ’message’ depends on the error Example Use: $this->Category->verify(); Example output: Array ( [0] => Array 316 Chapter 8. Models
- 323. CakePHP Cookbook Documentation,Release 2.x ( [0] => node [1] => 3 [2] => left and right values identical ) [1] => Array ( [0] => node [1] => 2 [2] => The parent node 999 doesn ’ t exist ) [10] => Array ( [0] => index [1] => 123 [2] => missing ) [99] => Array ( [0] => node [1] => 163 [2] => left greater than right ) ) Using Behaviors Behaviors are attached to models through the $actsAs model class variable: class Category extends AppModel { public $actsAs = array(’Tree’); } This example shows how a Category model could be managed in a tree structure using the TreeBehavior. Once a behavior has been specified, use the methods added by the behavior as if they always existed as part of the original model: // Set ID $this->Category->id = 42; // Use behavior method, children(): $kids = $this->Category->children(); Some behaviors may require or allow settings to be defined when the behavior is attached to the model. Here, we tell our TreeBehavior the names of the “left” and “right” fields in the underlying database table: class Category extends AppModel { public $actsAs = array(’Tree’ => array( ’left’ => ’left_node’, ’right’ => ’right_node’ More on models 317
- 324. CakePHP Cookbook Documentation,Release 2.x )); } We can also attach several behaviors to a model. There’s no reason why, for example, our Category model should only behave as a tree, it may also need internationalization support: class Category extends AppModel { public $actsAs = array( ’Tree’ => array( ’left’ => ’left_node’, ’right’ => ’right_node’ ), ’Translate’ ); } So far we have been adding behaviors to models using a model class variable. That means that our behaviors will be attached to our models throughout the model’s lifetime. However, we may need to “detach” behaviors from our models at runtime. Let’s say that on our previous Category model, which is acting as a Tree and a Translate model, we need for some reason to force it to stop acting as a Translate model: // Detach a behavior from our model: $this->Category->Behaviors->unload(’Translate’); That will make our Category model stop behaving as a Translate model from thereon. We may need, instead, to just disable the Translate behavior from acting upon our normal model operations: our finds, our saves, etc. In fact, we are looking to disable the behavior from acting upon our CakePHP model callbacks. Instead of detaching the behavior, we then tell our model to stop informing of these callbacks to the Translate behavior: // Stop letting the behavior handle our model callbacks $this->Category->Behaviors->disable(’Translate’); We may also need to find out if our behavior is handling those model callbacks, and if not we then restore its ability to react to them: // If our behavior is not handling model callbacks if (!$this->Category->Behaviors->enabled(’Translate’)) { // Tell it to start doing so $this->Category->Behaviors->enable(’Translate’); } Just as we could completely detach a behavior from a model at runtime, we can also attach new behaviors. Say that our familiar Category model needs to start behaving as a Christmas model, but only on Christmas day: // If today is Dec 25 if (date(’m/d’) === ’12/25’) { // Our model needs to behave as a Christmas model $this->Category->Behaviors->load(’Christmas’); } We can also use the load method to override behavior settings: 318 Chapter 8. Models
- 325. CakePHP Cookbook Documentation,Release 2.x // We will change one setting from our already attached behavior $this->Category->Behaviors->load(’Tree’, array(’left’ => ’new_left_node’)); There’s also a method to obtain the list of behaviors a model has attached. If we pass the name of a behavior to the method, it will tell us if that behavior is attached to the model, otherwise it will give us the list of attached behaviors: // If the Translate behavior is not attached if (!$this->Category->Behaviors->loaded(’Translate’)) { // Get the list of all behaviors the model has attached $behaviors = $this->Category->Behaviors->loaded(); } Creating Behaviors Behaviors that are attached to Models get their callbacks called automatically. The callbacks are sim- ilar to those found in Models: beforeFind, afterFind, beforeValidate, afterValidate, beforeSave, afterSave, beforeDelete, afterDelete and onError - see Callback Methods. Your behaviors should be placed in app/Model/Behavior. They are named in CamelCase and postfixed by Behavior, ex. NameBehavior.php. It’s often helpful to use a core behavior as a template when creating your own. Find them in lib/Cake/Model/Behavior/. Every callback and behavior method takes a reference to the model it is being called from as the first parameter. Besides implementing the callbacks, you can add settings per behavior and/or model behavior attachment. Information about specifying settings can be found in the chapters about core behaviors and their configu- ration. A quick example that illustrates how behavior settings can be passed from the model to the behavior: class Post extends AppModel { public $actsAs = array( ’YourBehavior’ => array( ’option1_key’ => ’option1_value’ ) ); } Since behaviors are shared across all the model instances that use them, it’s a good practice to store the settings per alias/model name that is using the behavior. When created behaviors will have their setup() method called: public function setup(Model $Model, $settings = array()) { if (!isset($this->settings[$Model->alias])) { $this->settings[$Model->alias] = array( ’option1_key’ => ’option1_default_value’, ’option2_key’ => ’option2_default_value’, ’option3_key’ => ’option3_default_value’, ); } More on models 319
- 326. CakePHP Cookbook Documentation,Release 2.x $this->settings[$Model->alias] = array_merge( $this->settings[$Model->alias], (array)$settings); } Creating behavior methods Behavior methods are automatically available on any model acting as the behavior. For example if you had: class Duck extends AppModel { public $actsAs = array(’Flying’); } You would be able to call FlyingBehavior methods as if they were methods on your Duck model. When creating behavior methods you automatically get passed a reference of the calling model as the first parameter. All other supplied parameters are shifted one place to the right. For example: $this->Duck->fly(’toronto’, ’montreal’); Although this method takes two parameters, the method signature should look like: public function fly(Model $Model, $from, $to) { // Do some flying. } Keep in mind that methods called in a $this->doIt() fashion from inside a behavior method will not get the $model parameter automatically appended. Mapped methods In addition to providing ‘mixin’ methods, behaviors can also provide pattern matching methods. Behaviors can also define mapped methods. Mapped methods use pattern matching for method invocation. This allows you to create methods similar to Model::findAllByXXX methods on your behaviors. Mapped methods need to be declared in your behaviors $mapMethods array. The method signature for a mapped method is slightly different than a normal behavior mixin method: class MyBehavior extends ModelBehavior { public $mapMethods = array(’/do(w+)/’ => ’doSomething’); public function doSomething(Model $model, $method, $arg1, $arg2) { debug(func_get_args()); //do something } } The above will map every doXXX() method call to the behavior. As you can see, the model is still the first parameter, but the called method name will be the 2nd parameter. This allows you to munge the method name for additional information, much like Model::findAllByXX. If the above behavior was attached to a model the following would happen: 320 Chapter 8. Models
- 327. CakePHP Cookbook Documentation,Release 2.x $model->doReleaseTheHounds(’homer’, ’lenny’); // would output ’ReleaseTheHounds’, ’homer’, ’lenny’ Behavior callbacks Model Behaviors can define a number of callbacks that are triggered before the model callbacks of the same name. Behavior callbacks allow your behaviors to capture events in attached models and augment the parameters or splice in additional behavior. All behavior callbacks are fired before the model callbacks are: • beforeFind • afterFind • beforeValidate • afterValidate • beforeSave • afterSave • beforeDelete • afterDelete Creating a behavior callback class ModelBehavior Model behavior callbacks are defined as simple methods in your behavior class. Much like regular behavior methods, they receive a $Model parameter as the first argument. This parameter is the model that the behavior method was invoked on. ModelBehavior::setup(Model $Model, array $settings = array()) Called when a behavior is attached to a model. The settings come from the attached model’s $actsAs property. ModelBehavior::cleanup(Model $Model) Called when a behavior is detached from a model. The base method removes model settings based on $model->alias. You can override this method and provide custom cleanup functionality. ModelBehavior::beforeFind(Model $Model, array $query) If a behavior’s beforeFind return’s false it will abort the find(). Returning an array will augment the query parameters used for the find operation. ModelBehavior::afterFind(Model $Model, mixed $results, boolean $primary = false) You can use the afterFind to augment the results of a find. The return value will be passed on as the results to either the next behavior in the chain or the model’s afterFind. More on models 321
- 328. CakePHP Cookbook Documentation,Release 2.x ModelBehavior::beforeValidate(Model $Model, array $options = array()) You can use beforeValidate to modify a model’s validate array or handle any other pre-validation logic. Returning false from a beforeValidate callback will abort the validation and cause it to fail. ModelBehavior::afterValidate(Model $Model) You can use afterValidate to perform any data cleanup or preparation if needed. ModelBehavior::beforeSave(Model $Model, array $options = array()) You can return false from a behavior’s beforeSave to abort the save. Return true to allow it continue. ModelBehavior::afterSave(Model $Model, boolean $created, array $options = array()) You can use afterSave to perform clean up operations related to your behavior. $created will be true when a record is created, and false when a record is updated. ModelBehavior::beforeDelete(Model $Model, boolean $cascade = true) You can return false from a behavior’s beforeDelete to abort the delete. Return true to allow it con- tinue. ModelBehavior::afterDelete(Model $Model) You can use afterDelete to perform clean up operations related to your behavior. DataSources DataSources are the link between models and the source of data that models represent. In many cases, the data is retrieved from a relational database such as MySQL, PostgreSQL or MSSQL. CakePHP is distributed with several database-specific datasources (see the class files in lib/Cake/Model/Datasource/Database), a summary of which is listed here for your conve- nience: • MySql • Postgres • Sqlite • Sqlserver Note: You can find additional community contributed datasources in the CakePHP DataSources repository on GitHub3. When specifying a database connection configuration in app/Config/database.php, CakePHP trans- parently uses the corresponding database datasource for all model operations. So, even though you might not have known about datasources, you’ve been using them all along. All of the above sources derive from a base DboSource class, which aggregates some logic that is common to most relational databases. If you decide to write a RDBMS datasource, working from one of these (e.g. Mysql, or Sqlite) is your best bet. Most people, however, are interested in writing datasources for external sources of data, such as remote REST APIs or even an LDAP server. So that’s what we’re going to look at now. 3 https://github.com/cakephp/datasources/tree/2.0 322 Chapter 8. Models
- 329. CakePHP Cookbook Documentation,Release 2.x Basic API For DataSources A datasource can, and should implement at least one of the following methods: create, read, update and/or delete (the actual method signatures & implementation details are not important for the moment, and will be described later). You need not implement more of the methods listed above than necessary - if you need a read-only datasource, there’s no reason to implement create, update, and delete. Methods that must be implemented for all CRUD methods: • describe($model) • listSources($data = null) • calculate($model, $func, $params) • At least one of: – create(Model $model, $fields = null, $values = null) – read(Model $model, $queryData = array(), $recursive = null) – update(Model $model, $fields = null, $values = null, $conditions = null) – delete(Model $model, $id = null) It is also possible (and sometimes quite useful) to define the $_schema class attribute inside the datasource itself, instead of in the model. And that’s pretty much all there is to it. By coupling this datasource to a model, you are then able to use Model::find()/save()/delete() as you would normally, and the appropriate data and/or parame- ters used to call those methods will be passed on to the datasource itself, where you can decide to implement whichever features you need (e.g. Model::find options such as ’conditions’ parsing, ’limit’ or even your own custom parameters). An Example A common reason you would want to write your own datasource is when you would like to access a 3rd party API using the usual Model::find()/save()/delete() methods. Let’s write a datasource that will access a fictitious remote JSON based API. We’ll call it FarAwaySource and we’ll put it in app/Model/Datasource/FarAwaySource.php: App::uses(’HttpSocket’, ’Network/Http’); class FarAwaySource extends DataSource { /** * An optional description of your datasource */ public $description = ’A far away datasource’; /** * Our default config options. These options will be customized in our * ‘‘app/Config/database.php‘‘ and will be merged in the ‘‘__construct()‘‘. More on models 323
- 330. CakePHP Cookbook Documentation,Release 2.x */ public $config = array( ’apiKey’ => ’’, ); /** * If we want to create() or update() we need to specify the fields * available. We use the same array keys as we do with CakeSchema, eg. * fixtures and schema migrations. */ protected $_schema = array( ’id’ => array( ’type’ => ’integer’, ’null’ => false, ’key’ => ’primary’, ’length’ => 11, ), ’name’ => array( ’type’ => ’string’, ’null’ => true, ’length’ => 255, ), ’message’ => array( ’type’ => ’text’, ’null’ => true, ), ); /** * Create our HttpSocket and handle any config tweaks. */ public function __construct($config) { parent::__construct($config); $this->Http = new HttpSocket(); } /** * Since datasources normally connect to a database there are a few things * we must change to get them to work without a database. */ /** * listSources() is for caching. You’ll likely want to implement caching in * your own way with a custom datasource. So just ‘‘return null‘‘. */ public function listSources($data = null) { return null; } /** * describe() tells the model your schema for ‘‘Model::save()‘‘. * * You may want a different schema for each model but still use a single 324 Chapter 8. Models
- 331. CakePHP Cookbook Documentation,Release 2.x * datasource. If this is your case then set a ‘‘schema‘‘ property on your * models and simply return ‘‘$model->schema‘‘ here instead. */ public function describe($model) { return $this->_schema; } /** * calculate() is for determining how we will count the records and is * required to get ‘‘update()‘‘ and ‘‘delete()‘‘ to work. * * We don’t count the records here but return a string to be passed to * ‘‘read()‘‘ which will do the actual counting. The easiest way is to just * return the string ’COUNT’ and check for it in ‘‘read()‘‘ where * ‘‘$data[’fields’] === ’COUNT’‘‘. */ public function calculate(Model $model, $func, $params = array()) { return ’COUNT’; } /** * Implement the R in CRUD. Calls to ‘‘Model::find()‘‘ arrive here. */ public function read(Model $model, $queryData = array(), $recursive = null) { /** * Here we do the actual count as instructed by our calculate() * method above. We could either check the remote source or some * other way to get the record count. Here we’ll simply return 1 so * ‘‘update()‘‘ and ‘‘delete()‘‘ will assume the record exists. */ if ($queryData[’fields’] === ’COUNT’) { return array(array(array(’count’ => 1))); } /** * Now we get, decode and return the remote data. */ $queryData[’conditions’][’apiKey’] = $this->config[’apiKey’]; $json = $this->Http->get( ’http://example.com/api/list.json’, $queryData[’conditions’] ); $res = json_decode($json, true); if (is_null($res)) { $error = json_last_error(); throw new CakeException($error); } return array($model->alias => $res); } /** * Implement the C in CRUD. Calls to ‘‘Model::save()‘‘ without $model->id * set arrive here. More on models 325
- 332. CakePHP Cookbook Documentation,Release 2.x */ public function create(Model $model, $fields = null, $values = null) { $data = array_combine($fields, $values); $data[’apiKey’] = $this->config[’apiKey’]; $json = $this->Http->post(’http://example.com/api/set.json’, $data); $res = json_decode($json, true); if (is_null($res)) { $error = json_last_error(); throw new CakeException($error); } return true; } /** * Implement the U in CRUD. Calls to ‘‘Model::save()‘‘ with $Model->id * set arrive here. Depending on the remote source you can just call * ‘‘$this->create()‘‘. */ public function update(Model $model, $fields = null, $values = null, $conditions = null) { return $this->create($model, $fields, $values); } /** * Implement the D in CRUD. Calls to ‘‘Model::delete()‘‘ arrive here. */ public function delete(Model $model, $id = null) { $json = $this->Http->get(’http://example.com/api/remove.json’, array( ’id’ => $id[$model->alias . ’.id’], ’apiKey’ => $this->config[’apiKey’], )); $res = json_decode($json, true); if (is_null($res)) { $error = json_last_error(); throw new CakeException($error); } return true; } } We can then configure the datasource in our app/Config/database.php file by adding something like this: public $faraway = array( ’datasource’ => ’FarAwaySource’, ’apiKey’ => ’1234abcd’, ); Then use the database config in our models like this: class MyModel extends AppModel { public $useDbConfig = ’faraway’; } 326 Chapter 8. Models
- 333. CakePHP Cookbook Documentation,Release 2.x We can retrieve data from our remote source using the familiar model methods: // Get all messages from ’Some Person’ $messages = $this->MyModel->find(’all’, array( ’conditions’ => array(’name’ => ’Some Person’), )); Tip: Using find types other than ’all’ can have unexpected results if the result of your read method is not a numerically indexed array. Similarly we can save a new message: $this->MyModel->save(array( ’name’ => ’Some Person’, ’message’ => ’New Message’, )); Update the previous message: $this->MyModel->id = 42; $this->MyModel->save(array( ’message’ => ’Updated message’, )); And delete the message: $this->MyModel->delete(42); Plugin DataSources You can also package Datasources into plugins. Simply place your datasource file into Plugin/[YourPlugin]/Model/Datasource/[YourSource].php and refer to it using the plugin notation: public $faraway = array( ’datasource’ => ’MyPlugin.FarAwaySource’, ’apiKey’ => ’abcd1234’, ); Connecting to SQL Server The Sqlserver datasource depends on Microsoft’s PHP extension called pdo_sqlsrv. This PHP Extension is not included in the base installation of PHP and must be installed separately. Also the SQL Server Native Client must be installed for the extension to work. As the Native Client is available only for Windows you will not be able to install it on Linux, Mac OS X or FreeBSD. So if the Sqlserver Datasource errors out with: More on models 327
- 334. CakePHP Cookbook Documentation,Release 2.x Error: Database connection "Sqlserver" is missing, or could not be created. First check if the SQL Server PHP extension pdo_sqlsrv and the SQL Server Native Client are installed properly. Model Attributes Model attributes allow you to set properties that can override the default model behavior. For a complete list of model attributes and their descriptions visit the CakePHP API4. useDbConfig The useDbConfig property is a string that specifies the name of the database connection to use to bind your model class to the related database table. You can set it to any of the database con- nections defined within your database configuration file. The database configuration file is stored in /app/Config/database.php. The useDbConfig property is defaulted to the ‘default’ database connection. Example usage: class Example extends AppModel { public $useDbConfig = ’alternate’; } useTable The useTable property specifies the database table name. By default, the model uses the lowercase, plural form of the model’s class name. Set this attribute to the name of an alternate table, or set it to false if you wish the model to use no database table. Example usage: class Example extends AppModel { public $useTable = false; // This model does not use a database table } Alternatively: class Example extends AppModel { public $useTable = ’exmp’; // This model uses a database table ’exmp’ } 4 http://api.cakephp.org/2.4/class-Model.html 328 Chapter 8. Models
- 335. CakePHP Cookbook Documentation,Release 2.x tablePrefix The name of the table prefix used for the model. The table prefix is initially set in the database connection file at /app/Config/database.php. The default is no prefix. You can override the default by setting the tablePrefix attribute in the model. Example usage: class Example extends AppModel { public $tablePrefix = ’alternate_’; // will look for ’alternate_examples’ } primaryKey Each table normally has a primary key, id. You may change which field name the model uses as its primary key. This is common when setting CakePHP to use an existing database table. Example usage: class Example extends AppModel { // example_id is the field name in the database public $primaryKey = ’example_id’; } displayField The displayField attribute specifies which database field should be used as a label for the record. The label is used in scaffolding and in find(’list’) calls. The model will use name or title, by default. For example, to use the username field: class User extends AppModel { public $displayField = ’username’; } Multiple field names cannot be combined into a single display field. For example, you cannot specify, array(’first_name’, ’last_name’) as the display field. Instead create a virtual field with the Model attribute virtualFields recursive The recursive property defines how deep CakePHP should go to fetch associated model data via find(), and read() methods. Imagine your application features Groups which belong to a domain and have many Users which in turn have many Articles. You can set $recursive to different values based on the amount of data you want back from a $this->Group->find() call: • -1 CakePHP fetches Group data only, no joins. • 0 CakePHP fetches Group data and its domain More on models 329
- 336. CakePHP Cookbook Documentation,Release 2.x • 1 CakePHP fetches a Group, its domain and its associated Users • 2 CakePHP fetches a Group, its domain, its associated Users, and the Users’ associated Articles Set it no higher than you need. Having CakePHP fetch data you aren’t going to use slows your app unnec- essarily. Also note that the default recursive level is 1. Note: If you want to combine $recursive with the fields functionality, you will have to add the columns containing the required foreign keys to the fields array manually. In the example above, this could mean adding domain_id. Tip: The recommended recursive level for your application should be -1. This avoids retrieving related data where that is unnecessary or even unwanted. This is most likely the case for most of your find() calls. Raise it only when needed or use Containable behavior. You can achieve that by adding it to the AppModel: public $recursive = -1; order The default ordering of data for any find operation. Possible values include: $order = "field" $order = "Model.field"; $order = "Model.field asc"; $order = "Model.field ASC"; $order = "Model.field DESC"; $order = array("Model.field" => "asc", "Model.field2" => "DESC"); data The container for the model’s fetched data. While data returned from a model class is normally used as returned from a find() call, you may need to access information stored in $data inside of model callbacks. _schema Contains metadata describing the model’s database table fields. Each field is described by: • name • type (integer, string, datetime, etc.) • null • default value • length 330 Chapter 8. Models
- 337. CakePHP Cookbook Documentation,Release 2.x Example Usage: protected $_schema = array( ’first_name’ => array( ’type’ => ’string’, ’length’ => 30 ), ’last_name’ => array( ’type’ => ’string’, ’length’ => 30 ), ’email’ => array( ’type’ => ’string’, ’length’ => 30 ), ’message’ => array(’type’ => ’text’) ); validate This attribute holds rules that allow the model to make data validation decisions before saving. Keys named after fields hold regex values allowing the model to try to make matches. Note: It is not necessary to call validate() before save() as save() will automatically validate your data before actually saving. For more information on validation, see the Data Validation later on in this manual. virtualFields Array of virtual fields this model has. Virtual fields are aliased SQL expressions. Fields added to this property will be read as other fields in a model but will not be saveable. Example usage for MySQL: public $virtualFields = array( ’name’ => "CONCAT(User.first_name, ’ ’, User.last_name)" ); In subsequent find operations, your User results would contain a name key with the result of the concate- nation. It is not advisable to create virtual fields with the same names as columns on the database, this can cause SQL errors. For more information on the virtualFields property, its proper usage, as well as limitations, see Virtual fields. name Name of the model. If you do not specify it in your model file it will be set to the class name by constructor. More on models 331
- 338. CakePHP Cookbook Documentation,Release 2.x Example usage: class Example extends AppModel { public $name = ’Example’; } cacheQueries If set to true, data fetched by the model during a single request is cached. This caching is in-memory only, and only lasts for the duration of the request. Any duplicate requests for the same data is handled by the cache. Additional Methods and Properties While CakePHP’s model functions should get you where you need to go, don’t forget that model classes are just that: classes that allow you to write your own methods or define your own properties. Any operation that handles the saving and fetching of data is best housed in your model classes. This concept is often referred to as the fat model. class Example extends AppModel { public function getRecent() { $conditions = array( ’created BETWEEN (curdate() - interval 7 day)’ . ’ and (curdate() - interval 0 day))’ ); return $this->find(’all’, compact(’conditions’)); } } This getRecent() method can now be used within the controller. $recent = $this->Example->getRecent(); Model::associations() Get associations: $result = $this->Example->associations(); // $result equals array(’belongsTo’, ’hasOne’, ’hasMany’, ’hasAndBelongsToMany’) Model::buildQuery(string $type = ’first’, array $query = array()) Builds the query array that is used by the data source to generate the query to fetch the data. Model::deconstruct(string $field, mixed $data) Deconstructs a complex data type (array or object) into a single field value. 332 Chapter 8. Models
- 339. CakePHP Cookbook Documentation,Release 2.x Model::escapeField(string $field = null, string $alias = null) Escapes the field name and prepends the model name. Escaping is done according to the current database driver’s rules. Model::exists($id) Returns true if a record with the particular ID exists. If ID is not provided it calls Model::getID() to obtain the current record ID to verify, and then performs a Model::find(’count’) on the currently configured datasource to ascertain the existence of the record in persistent storage. Note: Parameter $id was added in 2.1. Prior to that it does not take any parameter. $this->Example->id = 9; if ($this->Example->exists()) { // ... } $exists = $this->Foo->exists(2); Model::getAffectedRows() Returns the number of rows affected by the last query. Model::getAssociated(string $type = null) Gets all the models with which this model is associated. Model::getColumnType(string $column) Returns the column type of a column in the model. Model::getColumnTypes() Returns an associative array of field names and column types. Model::getID(integer $list = 0) Returns the current record’s ID. More on models 333
- 340. CakePHP Cookbook Documentation,Release 2.x Model::getInsertID() Returns the ID of the last record this model inserted. Model::getLastInsertID() Alias to getInsertID(). Virtual fields Virtual fields allow you to create arbitrary SQL expressions and assign them as fields in a Model. These fields cannot be saved, but will be treated like other model fields for read operations. They will be indexed under the model’s key alongside other model fields. Creating virtual fields Creating virtual fields is easy. In each model you can define a $virtualFields property that contains an array of field => expressions. An example of a virtual field definition using MySQL would be: public $virtualFields = array( ’name’ => ’CONCAT(User.first_name, " ", User.last_name)’ ); And with PostgreSQL: public $virtualFields = array( ’name’ => "User.first_name || ’ ’ || User.last_name" ); In subsequent find operations, your User results would contain a name key with the result of the concate- nation. It is not advisable to create virtual fields with the same names as columns on the database, this can cause SQL errors. It is not always useful to have User.first_name fully qualified. If you do not follow the convention (i.e. you have multiple relations to other tables) this would result in an error. In this case it may be better to just use first_name || ’ ’ || last_name without the Model Name. Using virtual fields Creating virtual fields is straightforward and easy, interacting with virtual fields can be done through a few different methods. Model::hasField() Model::hasField() will return true if the model has a concrete field passed by the first parameter. By setting the second parameter of hasField() to true, virtualFields will also be checked when checking if a model has a field. Using the example field above: 334 Chapter 8. Models
- 341. CakePHP Cookbook Documentation,Release 2.x // Will return false, as there is no concrete field called name $this->User->hasField(’name’); // Will return true as there is a virtual field called name $this->User->hasField(’name’, true); Model::isVirtualField() This method can be used to check if a field/column is a virtual field or a concrete field. Will return true if the column is virtual: $this->User->isVirtualField(’name’); //true $this->User->isVirtualField(’first_name’); //false Model::getVirtualField() This method can be used to access the SQL expression that comprises a virtual field. If no argument is supplied it will return all virtual fields in a Model: //returns ’CONCAT(User.first_name, ’ ’, User.last_name)’ $this->User->getVirtualField(’name’); Model::find() and virtual fields As stated earlier Model::find() will treat virtual fields much like any other field in a model. The value of a virtual field will be placed under the model’s key in the resultset: $results = $this->User->find(’first’); // results contains the following array( ’User’ => array( ’first_name’ => ’Mark’, ’last_name’ => ’Story’, ’name’ => ’Mark Story’, //more fields. ) ); Pagination and virtual fields Since virtual fields behave much like regular fields when doing find’s, Controller::paginate() will be able to sort by virtual fields too. More on models 335
- 342. CakePHP Cookbook Documentation,Release 2.x Virtual fields and model aliases When you are using virtualFields and models with aliases that are not the same as their name, you can run into problems as virtualFields do not update to reflect the bound alias. If you are using virtualFields in models that have more than one alias it is best to define the virtualFields in your model’s constructor: public function __construct($id = false, $table = null, $ds = null) { parent::__construct($id, $table, $ds); $this->virtualFields[’name’] = sprintf( ’CONCAT(%s.first_name, " ", %s.last_name)’, $this->alias, $this->alias ); } This will allow your virtualFields to work for any alias you give a model. Virtual fields in SQL queries Using functions in direct SQL queries will prevent data from being returned in the same array as your model’s data. For example this: $this->Timelog->query( "SELECT project_id, SUM(id) as TotalHours FROM timelogs AS Timelog GROUP BY project_id;" ); would return something like this: Array ( [0] => Array ( [Timelog] => Array ( [project_id] => 1234 ) [0] => Array ( [TotalHours] => 25.5 ) ) ) If we want to group TotalHours into our Timelog array we should specify a virtual field for our aggregate column. We can add this new virtual field on the fly rather than permanently declaring it in the model. We will provide a default value of 0 in case another query attempts to use this virtual field. If that were to occur, 0 would be returned in the TotalHours column: 336 Chapter 8. Models
- 343. CakePHP Cookbook Documentation,Release 2.x $this->Timelog->virtualFields[’TotalHours’] = 0; In addition to adding the virtual field we also need to alias our column using the form of MyModel__MyField like this: $this->Timelog->query( "SELECT project_id, SUM(id) as Timelog__TotalHours FROM timelogs AS Timelog GROUP BY project_id;" ); Running the query again after specifying the virtual field should result in a cleaner grouping of values: Array ( [0] => Array ( [Timelog] => Array ( [project_id] => 1234 [TotalHours] => 25.5 ) ) ) Limitations of virtualFields The implementation of virtualFields has a few limitations. First you cannot use virtualFields on associated models for conditions, order, or fields arrays. Doing so will generally result in an SQL error as the fields are not replaced by the ORM. This is because it difficult to estimate the depth at which an associated model might be found. A common workaround for this implementation issue is to copy virtualFields from one model to another at runtime when you need to access them: $this->virtualFields[’name’] = $this->Author->virtualFields[’name’]; or: $this->virtualFields += $this->Author->virtualFields; Transactions To perform a transaction, a model’s table must be of a datasource and type which supports transactions. More on models 337
- 344. CakePHP Cookbook Documentation,Release 2.x All transaction methods must be performed on a model’s DataSource object. To get a model’s DataSource from within the model, use: $dataSource = $this->getDataSource(); You can then use the data source to start, commit, or roll back transactions. $dataSource->begin(); // Perform some tasks if (/*all’s well*/) { $dataSource->commit(); } else { $dataSource->rollback(); } Nested Transactions It is possible to start a transaction several times using the Datasource::begin() method. The trans- action will finish only when the number of commit and rollback calls match with begin. $dataSource->begin(); // Perform some tasks $dataSource->begin(); // More few tasks if (/*latest task ok*/) { $dataSource->commit(); } else { $dataSource->rollback(); // Change something in main task } $dataSource->commit(); This will perform the real nested transaction if your database supports it and it is enabled in the datasource. The methods will always return true when in transaction mode and the nested is not supported or disabled. If you want to use multiple begin’s but not use the nested transaction from database, disable it using $dataSource->useNestedTransactions = false;. It will use only one global transaction. The real nested transaction is disabled by default. Enable it using $dataSource->useNestedTransactions = true;. 338 Chapter 8. Models
- 345. CHAPTER 9 Core Libraries CakePHPcomes with a plethora of built-in functions and classes. These classes and functions try to cover some of the most common features required in web applications. General Purpose General purpose libraries are available and reused in many places across CakePHP. General Purpose Global Constants and Functions While most of your day-to-day work in CakePHP will be utilizing core classes and methods, CakePHP features a number of global convenience functions that may come in handy. Many of these functions are for use with CakePHP classes (loading model or component classes), but many others make working with arrays or strings a little easier. We’ll also cover some of the constants available in CakePHP applications. Using these constants will help make upgrades more smooth, but are also convenient ways to point to certain files or directories in your CakePHP application. Global Functions Here are CakePHP’s globally available functions. Most of them are just convenience wrappers for other CakePHP functionality, such as debugging and translating content. __(string $string_id[, $formatArgs]) This function handles localization in CakePHP applications. The $string_id identifies the ID for a translation. Strings used for translations are treated as format strings for sprintf(). You can supply additional arguments to replace placeholders in your string: 339
- 346. CakePHP Cookbook Documentation,Release 2.x __(’You have %s unread messages’, $number); Note: Check out the Internationalization & Localization section for more information. __c(string $msg, integer $category, mixed $args = null) Note that the category must be specified with an I18n class constant, instead of only the constant name. The values are: •I18n::LC_ALL - LC_ALL •I18n::LC_COLLATE - LC_COLLATE •I18n::LC_CTYPE - LC_CTYPE •I18n::LC_MONETARY - LC_MONETARY •I18n::LC_NUMERIC - LC_NUMERIC •I18n::LC_TIME - LC_TIME •I18n::LC_MESSAGES - LC_MESSAGES __d(string $domain, string $msg, mixed $args = null) Allows you to override the current domain for a single message lookup. Useful when internationalizing a plugin: echo __d(’PluginName’, ’This is my plugin’); __dc(string $domain, string $msg, integer $category, mixed $args = null) Allows you to override the current domain for a single message lookup. It also allows you to specify a category. Note that the category must be specified with an I18n class constant, instead of only the constant name. The values are: •I18n::LC_ALL - LC_ALL •I18n::LC_COLLATE - LC_COLLATE •I18n::LC_CTYPE - LC_CTYPE •I18n::LC_MONETARY - LC_MONETARY •I18n::LC_NUMERIC - LC_NUMERIC •I18n::LC_TIME - LC_TIME •I18n::LC_MESSAGES - LC_MESSAGES __dcn(string $domain, string $singular, string $plural, integer $count, integer $category, mixed $args = null) Allows you to override the current domain for a single plural message lookup. It also allows you to specify a category. Returns correct plural form of message identified by $singular and $plural for count $count from domain $domain. Note that the category must be specified with an I18n class constant, instead of only the constant name. The values are: 340 Chapter 9. Core Libraries
- 347. CakePHP Cookbook Documentation,Release 2.x •I18n::LC_ALL - LC_ALL •I18n::LC_COLLATE - LC_COLLATE •I18n::LC_CTYPE - LC_CTYPE •I18n::LC_MONETARY - LC_MONETARY •I18n::LC_NUMERIC - LC_NUMERIC •I18n::LC_TIME - LC_TIME •I18n::LC_MESSAGES - LC_MESSAGES __dn(string $domain, string $singular, string $plural, integer $count, mixed $args = null) Allows you to override the current domain for a single plural message lookup. Returns correct plural form of message identified by $singular and $plural for count $count from domain $domain. __n(string $singular, string $plural, integer $count, mixed $args = null) Returns correct plural form of message identified by $singular and $plural for count $count. Some languages have more than one form for plural messages dependent on the count. am(array $one, $two, $three...) Merges all the arrays passed as parameters and returns the merged array. config() Can be used to load files from your application config-folder via include_once. Function checks for existence before include and returns boolean. Takes an optional number of arguments. Example: config(’some_file’, ’myconfig’); convertSlash(string $string) Converts forward slashes to underscores and removes the first and last underscores in a string. Returns the converted string. debug(mixed $var, boolean $showHtml = null, $showFrom = true) If the application’s DEBUG level is non-zero, $var is printed out. If $showHTML is true or left as null, the data is rendered to be browser-friendly. If $showFrom is not set to false, the debug output will start with the line from which it was called. Also see Debugging env(string $key) Gets an environment variable from available sources. Used as a backup if $_SERVER or $_ENV are disabled. This function also emulates PHP_SELF and DOCUMENT_ROOT on unsupporting servers. In fact, it’s a good idea to always use env() instead of $_SERVER or getenv() (especially if you plan to distribute the code), since it’s a full emulation wrapper. fileExistsInPath(string $file) Checks to make sure that the supplied file is within the current PHP include_path. Returns a boolean result. h(string $text, boolean $double = true, string $charset = null) Convenience wrapper for htmlspecialchars(). LogError(string $message) Shortcut to Log::write(). General Purpose 341
- 348. CakePHP Cookbook Documentation,Release 2.x pluginSplit(string $name, boolean $dotAppend = false, string $plugin = null) Splits a dot syntax plugin name into its plugin and class name. If $name does not have a dot, then index 0 will be null. Commonly used like list($plugin, $name) = pluginSplit(’Users.User’); pr(mixed $var) Convenience wrapper for print_r(), with the addition of wrapping <pre> tags around the output. sortByKey(array &$array, string $sortby, string $order = ‘asc’, integer $type = SORT_NUMERIC) Sorts given $array by key $sortby. stripslashes_deep(array $value) Recursively strips slashes from the supplied $value. Returns the modified array. Core Definition Constants Most of the following constants refer to paths in your application. constant APP Absolute path to your application directory, including a trailing slash. constant APP_DIR Equals app or the name of your application directory. constant APPLIBS Path to the application’s Lib directory. constant CACHE Path to the cache files directory. It can be shared between hosts in a multi-server setup. constant CAKE Path to the cake directory. constant CAKE_CORE_INCLUDE_PATH Path to the root lib directory. constant CORE_PATH Path to the root directory with ending directory slash. constant CSS Path to the public CSS directory. Deprecated since version 2.4. constant CSS_URL Web path to the CSS files directory. Deprecated since version 2.4: Use config value App.cssBaseUrl instead. constant DS Short for PHP’s DIRECTORY_SEPARATOR, which is / on Linux and on windows. 342 Chapter 9. Core Libraries
- 349. CakePHP Cookbook Documentation,Release 2.x constant FULL_BASE_URL Full URL prefix. Such as https://example.com Deprecated since version 2.4: This constant is deprecated, you should use Router::fullbaseUrl() instead. constant IMAGES Path to the public images directory. Deprecated since version 2.4. constant IMAGES_URL Web path to the public images directory. Deprecated since version 2.4: Use config value App.imageBaseUrl instead. constant JS Path to the public JavaScript directory. Deprecated since version 2.4. constant JS_URL Web path to the js files directory. Deprecated since version 2.4: Use config value App.jsBaseUrl instead. constant LOGS Path to the logs directory. constant ROOT Path to the root directory. constant TESTS Path to the tests directory. constant TMP Path to the temporary files directory. constant VENDORS Path to the vendors directory. constant WEBROOT_DIR Equals webroot or the name of your webroot directory. constant WWW_ROOT Full path to the webroot. Timing Definition Constants constant TIME_START Unix timestamp in microseconds as a float from when the application started. constant SECOND Equals 1 General Purpose 343
- 350. CakePHP Cookbook Documentation,Release 2.x constant MINUTE Equals 60 constant HOUR Equals 3600 constant DAY Equals 86400 constant WEEK Equals 604800 constant MONTH Equals 2592000 constant YEAR Equals 31536000 App Class class App The app class is responsible for path management, class location and class loading. Make sure you follow the File and Class Name Conventions. Packages CakePHP is organized around the idea of packages, each class belongs to a package or folder where other classes reside. You can configure each package location in your application using App::build(’APackage/SubPackage’, $paths) to inform the framework where should each class be loaded. Almost every class in the CakePHP framework can be swapped with your own compatible implementation. If you wish to use your own class instead of the classes the framework provides, just add the class to your libs folder emulating the directory location of where CakePHP expects to find it. For instance if you’d like to use your own HttpSocket class, put it under: app/Lib/Network/Http/HttpSocket.php Once you’ve done this App will load your override file instead of the file inside CakePHP. Loading classes static App::uses(string $class, string $package) Return type void Classes are lazily loaded in CakePHP, however before the autoloader can find your classes you need to tell App, where it can find the files. By telling App which package a class can be found in, it can properly locate the file and load it the first time a class is used. Some examples for common types of classes are: 344 Chapter 9. Core Libraries
- 351. CakePHP Cookbook Documentation,Release 2.x Controller App::uses(’PostsController’, ’Controller’); Component App::uses(’AuthComponent’, ’Controller/Component’); Model App::uses(’MyModel’, ’Model’); Behaviors App::uses(’TreeBehavior’, ’Model/Behavior’); Views App::uses(’ThemeView’, ’View’); Helpers App::uses(’HtmlHelper’, ’View/Helper’); Libs App::uses(’PaymentProcessor’, ’Lib’); Vendors App::uses(’Textile’, ’Vendor’); Utility App::uses(’String’, ’Utility’); So basically the second param should simply match the folder path of the class file in core or app. Note: Loading vendors usually means you are loading packages that do not follow conventions. For most vendor packages using App::import() is recommended. Loading files from plugins Loading classes in plugins works much the same as loading app and core classes except you must specify the plugin you are loading from: // Load the class Comment in app/Plugin/PluginName/Model/Comment.php App::uses(’Comment’, ’PluginName.Model’); // Load the class CommentComponent in // app/Plugin/PluginName/Controller/Component/CommentComponent.php App::uses(’CommentComponent’, ’PluginName.Controller/Component’); Finding paths to packages using App::path() static App::path(string $package, string $plugin = null) Return type array Used to read information stored path: // return the model paths in your application App::path(’Model’); This can be done for all packages that are apart of your application. You can also fetch paths for a plugin: // return the component paths in DebugKit App::path(’Component’, ’DebugKit’); static App::paths() Return type array General Purpose 345
- 352. CakePHP Cookbook Documentation,Release 2.x Get all the currently loaded paths from App. Useful for inspecting or storing all paths App knows about. For a paths to a specific package use App::path() static App::core(string $package) Return type array Used for finding the path to a package inside CakePHP: // Get the path to Cache engines. App::core(’Cache/Engine’); static App::location(string $className) Return type string Returns the package name where a class was defined to be located at. Adding paths for App to find packages in static App::build(array $paths = array(), mixed $mode = App::PREPEND) Return type void Sets up each package location on the file system. You can configure multiple search paths for each package, those will be used to look for files one folder at a time in the specified order. All paths must be terminated with a directory separator. Adding additional controller paths for example would alter where CakePHP looks for controllers. This allows you to split your application up across the filesystem. Usage: //will setup a new search path for the Model package App::build(array(’Model’ => array(’/a/full/path/to/models/’))); //will setup the path as the only valid path for searching models App::build(array(’Model’ => array(’/path/to/models/’)), App::RESET); //will setup multiple search paths for helpers App::build(array( ’View/Helper’ => array(’/path/to/helpers/’, ’/another/path/’) )); If reset is set to true, all loaded plugins will be forgotten and they will be needed to be loaded again. Examples: App::build(array(’controllers’ => array(’/full/path/to/controllers/’))); //becomes App::build(array(’Controller’ => array(’/full/path/to/Controller/’))); App::build(array(’helpers’ => array(’/full/path/to/views/helpers/’))); //becomes App::build(array(’View/Helper’ => array(’/full/path/to/View/Helper/’))); 346 Chapter 9. Core Libraries
- 353. CakePHP Cookbook Documentation,Release 2.x Changed in version 2.0: App::build() will not merge app paths with core paths anymore. Add new packages to an application App::build() can be used to add new package locations. This is useful when you want to add new top level packages or, sub-packages to your application: App::build(array( ’Service’ => array(’%s’ . ’Service’ . DS) ), App::REGISTER); The %s in newly registered packages will be replaced with the APP path. You must include a trailing / in registered packages. Once packages are registered, you can use App::build() to append/prepend/reset paths like any other package. Changed in version 2.1: Registering packages was added in 2.1 Finding which objects CakePHP knows about static App::objects(string $type, mixed $path = null, boolean $cache = true) Return type mixed Returns an array of objects of the given type or false if incorrect. You can find out which objects App knows about using App::objects(’Controller’) for example to find which application controllers App knows about. Example usage: //returns array(’DebugKit’, ’Blog’, ’User’); App::objects(’plugin’); //returns array(’PagesController’, ’BlogController’); App::objects(’Controller’); You can also search only within a plugin’s objects by using the plugin dot syntax.: // returns array(’MyPluginPost’, ’MyPluginComment’); App::objects(’MyPlugin.Model’); Changed in version 2.0. 1.Returns array() instead of false for empty results or invalid types 2.Does not return core objects anymore, App::objects(’core’) will return array(). 3.Returns the complete class name Locating plugins static App::pluginPath(string $plugin) Return type string General Purpose 347
- 354. CakePHP Cookbook Documentation,Release 2.x Plugins can be located with App as well. Using App::pluginPath(’DebugKit’); for exam- ple, will give you the full path to the DebugKit plugin: $path = App::pluginPath(’DebugKit’); Locating themes static App::themePath(string $theme) Return type string Themes can be found App::themePath(’purple’);, would give the full path to the purple theme. Including files with App::import() static App::import(mixed $type = null, string $name = null, mixed $parent = true, array $search = array(), string $file = null, boolean $return = false) Return type boolean At first glance App::import seems complex, however in most use cases only 2 arguments are required. Note: This method is equivalent to require‘ing the file. It is important to realize that the class subsequently needs to be initialized. // The same as require(’Controller/UsersController.php’); App::import(’Controller’, ’Users’); // We need to load the class $Users = new UsersController(); // If we want the model associations, components, etc to be loaded $Users->constructClasses(); All classes that were loaded in the past using App::import(‘Core’, $class) will need to be loaded using App::uses() referring to the correct package. This change has provided large performance gains to the framework. Changed in version 2.0. •The method no longer looks for classes recursively, it strictly uses the values for the paths defined in App::build() •It will not be able to load App::import(’Component’, ’Component’) use App::uses(’Component’, ’Controller’);. •Using App::import(’Lib’, ’CoreClass’); to load core classes is no longer possible. •Importing a non-existent file, supplying a wrong type or package name, or null values for $name and $file parameters will result in a false return value. 348 Chapter 9. Core Libraries
- 355. CakePHP Cookbook Documentation,Release 2.x •App::import(’Core’, ’CoreClass’) is no longer supported, use App::uses() in- stead and let the class autoloading do the rest. •Loading Vendor files does not look recursively in the vendors folder, it will also not convert the file to underscored anymore as it did in the past. Overriding classes in CakePHP You can override almost every class in the framework, exceptions are the App and Configure classes. Whenever you like to perform such overriding, just add your class to your app/Lib folder mimicking the internal structure of the framework. Some examples to follow: • To override the Dispatcher class, create app/Lib/Routing/Dispatcher.php • To override the CakeRoute class, create app/Lib/Routing/Route/CakeRoute.php • To override the Model class, create app/Lib/Model/Model.php When you load the overridden classes now, the files in app/Lib will be loaded instead of the built-in core ones. Loading Vendor Files You can use App::uses() to load classes in vendors directories. It follows the same conventions as loading other files: // Load the class Geshi in app/Vendor/Geshi.php App::uses(’Geshi’, ’Vendor’); To load classes in subdirectories, you’ll need to add those paths with App::build(): // Load the class ClassInSomePackage in // app/Vendor/SomePackage/ClassInSomePackage.php App::build(array(’Vendor’ => array(APP . ’Vendor’ . DS . ’SomePackage’))); App::uses(’ClassInSomePackage’, ’Vendor’); Your vendor files may not follow conventions, have a class that differs from the file name or does not contain classes. You can load those files using App::import(). The following examples illustrate how to load vendor files from a number of path structures. These vendor files could be located in any of the vendor folders. To load app/Vendor/geshi.php: App::import(’Vendor’, ’geshi’); Note: The geshi file must be a lower-case file name as CakePHP will not find it otherwise. To load app/Vendor/flickr/flickr.php: App::import(’Vendor’, ’flickr’, array(’file’ => ’flickr/flickr.php’)); General Purpose 349
- 356. CakePHP Cookbook Documentation,Release 2.x To load app/Vendor/some.name.php: App::import(’Vendor’, ’SomeName’, array(’file’ => ’some.name.php’)); To load app/Vendor/services/well.named.php: App::import( ’Vendor’, ’WellNamed’, array(’file’ => ’services’ . DS . ’well.named.php’) ); To load app/Plugin/Awesome/Vendor/services/well.named.php: App::import( ’Vendor’, ’Awesome.WellNamed’, array(’file’ => ’services’ . DS . ’well.named.php’) ); To load app/Plugin/Awesome/Vendor/Folder/Foo.php: App::import( ’Vendor’, ’Awesome.Foo’, array(’file’ => ’Folder’ . DS . ’Foo.php’)); It wouldn’t make a difference if your vendor files are inside your /vendors directory. CakePHP will auto- matically find it. To load vendors/vendorName/libFile.php: App::import( ’Vendor’, ’aUniqueIdentifier’, array(’file’ => ’vendorName’ . DS . ’libFile.php’) ); App Init/Load/Shutdown Methods static App::init() Return type void Initializes the cache for App, registers a shutdown function. static App::load(string $className) Return type boolean Method to handle the automatic class loading. It will look for each class’ package defined using App::uses() and with this information it will resolve the package name to a full path to load the class from. File name for each class should follow the class name. For instance, if a class is name MyCustomClass the file name should be MyCustomClass.php 350 Chapter 9. Core Libraries
- 357. CakePHP Cookbook Documentation,Release 2.x static App::shutdown() Return type void Object destructor. Writes cache file if changes have been made to the $_map. Events System New in version 2.1. Creating maintainable applications is both a science and an art. It is well-known that a key for having good quality code is making your objects loosely coupled and strongly cohesive at the same time. Cohesion means that all methods and properties for a class are strongly related to the class itself and it is not trying to do the job other objects should be doing, while loosely coupling is the measure of how little a class is “wired” to external objects, and how much that class is depending on them. There are certain cases where you need to cleanly communicate with other parts of an application, without having to hard code dependencies, thus losing cohesion and increasing class coupling. Using the Observer pattern, which allows objects to notify other objects and anonymous listeners about changes is a useful pattern to achieve this goal. Listeners in the observer pattern can subscribe to events and choose to act upon them if they are relevant. If you have used JavaScript, there is a good chance that you are already familiar with event driven program- ming. CakePHP emulates several aspects of how events are triggered and managed in popular JavaScript libraries such as jQuery. In the CakePHP implementation, an event object is dispatched to all listeners. The event object holds information about the event, and provides the ability to stop event propagation at any point. Listeners can register themselves or can delegate this task to other objects and have the chance to alter the state and the event itself for the rest of the callbacks. The event subsystem is at the heart of Model, Behavior, Controller, View and Helper callbacks. If you’ve ever used any of them, you are already somewhat familiar with events in CakePHP. Example event usage Let’s suppose you are building a Cart plugin, and you’d like to focus on just handling order logic. You don’t really want to include shipping logic, emailing the user or decrementing the item from the stock, but these are important tasks to the people using your plugin. If you were not using events, you may try to implement this by attaching behaviors to models, or adding components to your controllers. Doing so represents a challenge most of the time, since you would have to come up with the code for externally loading those behaviors or attaching hooks to your plugin controllers. Instead, you can use events to allow you to cleanly separate the concerns of your code and allow additional concerns to hook into your plugin using events. For example in your Cart plugin you have an Order model that deals with creating orders. You’d like to notify the rest of the application that an order has been created. To keep your Order model clean you could use events: // Cart/Model/Order.php App::uses(’CakeEvent’, ’Event’); class Order extends AppModel { General Purpose 351
- 358. CakePHP Cookbook Documentation,Release 2.x public function place($order) { if ($this->save($order)) { $this->Cart->remove($order); $event = new CakeEvent(’Model.Order.afterPlace’, $this, array( ’order’ => $order )); $this->getEventManager()->dispatch($event); return true; } return false; } } The above code allows you to easily notify the other parts of the application that an order has been created. You can then do tasks like send email notifications, update stock, log relevant statistics and other tasks in separate objects that focus on those concerns. Accessing event managers In CakePHP events are triggered against event managers. Event managers are available in every Model, View and Controller using getEventManager(): $events = $this->getEventManager(); Each model has a separate event manager, while the View and Controller share one. This allows model events to be self contained, and allow components or controllers to act upon events created in the view if necessary. Global event manager In addition to instance level event managers, CakePHP provides a global event manager that allows you to listen to any event fired in an application. This is useful when attaching listeners to a specific instance might be cumbersome or difficult. The global manager is a singleton instance of CakeEventManager. When an event is dispatched, it will be dispatched to the both the global and instance level listeners in priority order. You can access the global manager using a static method: // In any configuration file or piece of code that executes before the event App::uses(’CakeEventManager’, ’Event’); CakeEventManager::instance()->attach( $aCallback, ’Model.Order.afterPlace’ ); One important thing you should consider is that there are events that will be triggered having the same name but different subjects, so checking it in the event object is usually required in any function that gets attached globally in order to prevent some bugs. Remember that with the flexibility of using the global manager, some additional complexity is incurred. Changed in version 2.5: Prior to 2.5, listeners on the global manager were kept in a separate list and fired before instance listeners are. 352 Chapter 9. Core Libraries
- 359. CakePHP Cookbook Documentation,Release 2.x Dispatching events Once you have obtained an instance of an event manager you can dispatch events using dispatch(). This method takes an instance of the CakeEvent class. Let’s look at dispatching an event: // Create a new event and dispatch it. $event = new CakeEvent(’Model.Order.afterPlace’, $this, array( ’order’ => $order )); $this->getEventManager()->dispatch($event); CakeEvent accepts 3 arguments in its constructor. The first one is the event name, you should try to keep this name as unique as possible, while making it readable. We suggest a convention as fol- lows: Layer.eventName for general events happening at a layer level (e.g. Controller.startup, View.beforeRender) and Layer.Class.eventName for events happening in specific classes on a layer, for example Model.User.afterRegister or Controller.Courses.invalidAccess. The second argument is the subject, meaning the object associated to the event, usually when it is the same class triggering events about itself, using $this will be the most common case. Although a Component could trigger controller events too. The subject class is important because listeners will get immediate access to the object properties and have the chance to inspect or change them on the fly. Finally, the third argument is any additional event data.This can be any data you consider useful to pass around so listeners can act upon it. While this can be an argument of any type, we recommend passing an associative array. The dispatch() method accepts an event object as an argument and notifies all subscribed listeners. Registering listeners Listeners are the preferred way to register callbacks for an event. This is done by implementing the CakeEventListener interface in any class you wish to register some callbacks. Classes implement- ing it need to provide the implementedEvents() method. This method must return an associative array with all event names that the class will handle. To continue our previous example, let’s imagine we have a UserStatistic class responsible for calculating a user’s purchasing history, and compiling into global site statistics. This is a great place to use a listener class. Doing so allows you concentrate the statistics logic in one place and react to events as necessary. Our UserStatistics listener might start out like: App::uses(’CakeEventListener’, ’Event’); class UserStatistic implements CakeEventListener { public function implementedEvents() { return array( ’Model.Order.afterPlace’ => ’updateBuyStatistic’, ); } public function updateBuyStatistic($event) { // Code to update statistics General Purpose 353
- 360. CakePHP Cookbook Documentation,Release 2.x } } // Attach the UserStatistic object to the Order’s event manager $statistics = new UserStatistic(); $this->Order->getEventManager()->attach($statistics); As you can see in the above code, the attach function will accept instances of the CakeEventListener interface. Internally, the event manager will use implementedEvents to at- tach the correct callbacks. Registering anonymous listeners While event listener objects are generally a better way to implement listeners, you can also bind any callable as an event listener. For example if we wanted to put any orders into the log files, we could use a simple anonymous function to do so: // Anonymous functions require PHP 5.3+ $this->Order->getEventManager()->attach(function($event) { CakeLog::write( ’info’, ’A new order was placed with id: ’ . $event->subject()->id ); }, ’Model.Order.afterPlace’); In addition to anonymous functions you can use any other callable type that PHP supports: $events = array( ’email-sending’ => ’EmailSender::sendBuyEmail’, ’inventory’ => array($this->InventoryManager, ’decrement’), ); foreach ($events as $callable) { $eventManager->attach($callable, ’Model.Order.afterPlace’); } Establishing priorities In some cases you might want to control the order that listeners are invoked. For instance, if we go back to our user statistics example. It would ideal if this listener was called at the end of the stack. By calling it at the end of the listener stack, we can ensure that the event was not canceled, and that no other listeners raised exceptions. We can also get the final state of the objects in the case that other listeners have modified the subject or event object. Priorities are defined as an integer when adding a listener. The higher the number, the later the method will be fired. The default priority for all listeners is 10. If you need your method to be run earlier, using any value below this default will work. On the other hand if you desire to run the callback after the others, using a number above 10 will do. If two callbacks happen to have the same priority value, they will be executed with a the order they were attached. You set priorities using the attach method for callbacks, and declaring it in the implementedEvents function for event listeners: // Setting priority for a callback $callback = array($this, ’doSomething’); $this->getEventManager()->attach( 354 Chapter 9. Core Libraries
- 361. CakePHP Cookbook Documentation,Release 2.x $callback, ’Model.Order.afterPlace’, array(’priority’ => 2) ); // Setting priority for a listener class UserStatistic implements CakeEventListener { public function implementedEvents() { return array( ’Model.Order.afterPlace’ => array( ’callable’ => ’updateBuyStatistic’, ’priority’ => 100 ), ); } } As you see, the main difference for CakeEventListener objects is that you need to use an array for specifying the callable method and the priority preference. The callable key is an special array entry that the manager will read to know what function in the class it should be calling. Getting event data as function parameters By default listeners receive the event object as their only parameter. If you are building an event that doesn’t need access to the event object you may want to have the event data passed as function parameters. This feature is used by the callbacks CakePHP fires in order to preserve backwards compatibility. If you want to enable this feature, you have to add the passParams option to the third argument of the attach method, or declare it in the implementedEvents returned array similar to what you do with priorities: // Enabling passed parameters mode for an anonymous listener $callback = array($this, ’doSomething’); $this->getEventManager()->attach( $callback, ’Model.Order.afterPlace’, array(’passParams’ => true) ); // Enabling passed parameters mode for a listener class UserStatistic implements CakeEventListener { public function implementedEvents() { return array( ’Model.Order.afterPlace’ => array( ’callable’ => ’updateBuyStatistic’, ’passParams’ => true ), ); } public function updateBuyStatistic($orderData) { // ... } General Purpose 355
- 362. CakePHP Cookbook Documentation,Release 2.x } In the above code the doSomething function and updateBuyStatistic method will receive $orderData instead of the $event object. This is so, because in our previous example we trigger the Model.Order.afterPlace event with some data: $event = new CakeEvent(’Model.Order.afterPlace’, $this, array( ’order’ => $order )); $this->getEventManager()->dispatch($event); Note: The params can only be passed as function arguments if the event data is an array. Any other data type cannot be converted to function parameters, thus not using this option is often the most adequate choice. Stopping events Much like DOM events, you may want to stop an event to prevent additional listeners from being notified. You can see this in action during model callbacks (e.g. beforeSave) in which it is possible to stop the saving operation if the code detects it cannot proceed any further. In order to stop events you can either return false in your callbacks or call the stopPropagation method on the event object: public function doSomething($event) { // ... return false; // stops the event } public function updateBuyStatistic($event) { // ... $event->stopPropagation(); } Stopping an event will prevent any additional callbacks from being called. Additionally the code triggering the event may behave differently based on the event being stopped or not. Generally it does not make sense to stop ‘after’ events, but stopping ‘before’ events is often used to prevent the entire operation from occurring. To check if an event was stopped, you call the isStopped() method in the event object: public function place($order) { $event = new CakeEvent( ’Model.Order.beforePlace’, $this, array(’order’ => $order) ); $this->getEventManager()->dispatch($event); if ($event->isStopped()) { return false; } if ($this->Order->save($order)) { // ... } 356 Chapter 9. Core Libraries
- 363. CakePHP Cookbook Documentation,Release 2.x // ... } In the previous example the order would not get saved if the event is stopped during the beforePlace process. Getting event results Every time a callback returns a value, it gets stored in the $result property of the event object. This is useful when you want to allow callbacks to modify the event execution. Let’s take again our beforePlace example and let callbacks modify the $order data. Event results can be altered either using the event object result property directly or returning the value in the callback itself: // A listener callback public function doSomething($event) { // ... $alteredData = $event->data[’order’] + $moreData; return $alteredData; } // Another listener callback public function doSomethingElse($event) { // ... $event->result[’order’] = $alteredData; } // Using the event result public function place($order) { $event = new CakeEvent( ’Model.Order.beforePlace’, $this, array(’order’ => $order) ); $this->getEventManager()->dispatch($event); if (!empty($event->result[’order’])) { $order = $event->result[’order’]; } if ($this->Order->save($order)) { // ... } // ... } It is possible to alter any event object property and have the new data passed to the next callback. In most of the cases, providing objects as event data or result and directly altering the object is the best solution as the reference is kept the same and modifications are shared across all callback calls. Removing callbacks and listeners If for any reason you want to remove any callback from the event manager just call the CakeEventManager::detach() method using as arguments the first two params you used for attaching it: General Purpose 357
- 364. CakePHP Cookbook Documentation,Release 2.x // Attaching a function $this->getEventManager()->attach(array($this, ’doSomething’), ’My.event’); // Detaching the function $this->getEventManager()->detach(array($this, ’doSomething’), ’My.event’); // Attaching an anonymous function (PHP 5.3+ only); $myFunction = function($event) { ... }; $this->getEventManager()->attach($myFunction, ’My.event’); // Detaching the anonymous function $this->getEventManager()->detach($myFunction, ’My.event’); // Attaching a CakeEventListener $listener = new MyEventLister(); $this->getEventManager()->attach($listener); // Detaching a single event key from a listener $this->getEventManager()->detach($listener, ’My.event’); // Detaching all callbacks implemented by a listener $this->getEventManager()->detach($listener); Conclusion Events are a great way of separating concerns in your application and make classes both cohesive and de- coupled from each other. Events can be utilized to de-couple application code and make extensible plugins. Keep in mind that with great power comes great responsibility. Using too many events can make debugging harder and require additional integration testing. Additional Reading Collections Components, Helpers, Behaviors and Tasks all share a similar structure and set of behaviors. For 2.0, they were given a unified API for interacting with collections of similar objects. The collection objects in CakePHP, give you a uniform way to interact with several different kinds of objects in your application. While the examples below, will use Components, the same behavior can be expected for Helpers, Behaviors, and Tasks in addition to Components. Loading and unloading objects Loading objects on every kind of collection can be done using the load() method: $this->Prg = $this->Components->load(’Prg’); $this->Prg->process(); When loading a component, if the component is not currently loaded into the collection, a new instance will be created. If the component is already loaded, another instance will not be created. When loading 358 Chapter 9. Core Libraries
- 365. CakePHP Cookbook Documentation,Release 2.x components, you can also provide additional configuration for them: $this->Cookie = $this->Components->load(’Cookie’, array(’name’ => ’sweet’)); Any keys & values provided will be passed to the Component’s constructor. The one exception to this rule is className. ClassName is a special key that is used to alias objects in a collection. This allows you to have component names that do not reflect the classnames, which can be helpful when extending core components: $this->Auth = $this->Components->load( ’Auth’, array(’className’ => ’MyCustomAuth’) ); $this->Auth->user(); // Actually using MyCustomAuth::user(); The inverse of loading an object, is unloading it. Unloaded objects are removed from memory, and will not have additional callbacks triggered on them: $this->Components->unload(’Cookie’); $this->Cookie->read(); // Fatal error. Triggering callbacks Callbacks are supported by collection objects. When a collection has a callback triggered, that method will be called on all enabled objects in the collection. You can pass parameters to the callback loop as well: $this->Behaviors->trigger(’afterFind’, array($this, $results, $primary)); In the above $this would be passed as the first argument to every behavior’s afterFind method. There are several options that can be used to control how callbacks are fired: • breakOn Set to the value or values you want the callback propagation to stop on. Can either be a scalar value, or an array of values to break on. Defaults to false. • break Set to true to enabled breaking. When a trigger is broken, the last returned value will be re- turned. If used in combination with collectReturn the collected results will be returned. Defaults to false. • collectReturn Set to true to collect the return of each object into an array. This array of return values will be returned from the trigger() call. Defaults to false. • triggerDisabled Will trigger the callback on all objects in the collection even the non-enabled objects. Defaults to false. • modParams Allows each object the callback gets called on to modify the parameters to the next object. Setting modParams to an integer value will allow you to modify the parameter with that index. Any non-null value will modify the parameter index indicated. Defaults to false. Canceling a callback loop Using the break and breakOn options you can cancel a callback loop midway similar to stopping event propagation in JavaScript: General Purpose 359
- 366. CakePHP Cookbook Documentation,Release 2.x $this->Behaviors->trigger( ’beforeFind’, array($this, $query), array(’break’ => true, ’breakOn’ => false) ); In the above example, if any behavior returns false from its beforeFind method, no further callbacks will be called. In addition, the return of trigger() will be false. Enabling and disabling objects Once an object is loaded into a collection you may need to disable it. Disabling an object in a collection prevents future callbacks from being fired on that object unless the triggerDisabled option is used: // Disable the HtmlHelper $this->Helpers->disable(’Html’); // Re-enable the helper later on $this->Helpers->enable(’Html’); Disabled objects can still have their normal methods and properties used. The primary difference between an enabled and disabled object is with regards to callbacks. You can interrogate a collection about the enabled objects, or check if a specific object is still enabled using enabled(): // Check whether or not a specific helper is enabled. $this->Helpers->enabled(’Html’); // $enabled will contain an array of helper currently enabled. $enabled = $this->Helpers->enabled(); Object callback priorities You can prioritize the triggering object callbacks similar to event callbacks. The handling of priority values and order of triggering is the same as explained here. Here’s how you can specify priority at declaration time: class SomeController { public $components = array( ’Foo’, //Foo gets default priority 10 // Bar’s callbacks are triggered before Foo’s ’Bar’ => array(’priority’ => 9) ); public $helpers = array( // Cache’s callbacks will be triggered last ’Cache’ => array(’priority’ => 12), ’Asset’, ’Utility’ //Utility has priority 10 same as Asset and its callbacks //are triggered after Asset’s ); } class Post { 360 Chapter 9. Core Libraries
- 367. CakePHP Cookbook Documentation,Release 2.x public $actsAs = array( ’DoFirst’ => array(’priority’ => 1), ’Media’ ); } When dynamically loading objects to a collection you can specify the priority like this: $this->MyComponent = $this->Components->load( ’MyComponent’, array(’priority’ => 9) ); You can also change priorities at run time using the ObjectCollection::setPriority() function: //For a single object $this->Components->setPriority(’Foo’, 2); //For multiple objects $this->Behaviors->setPriority(array(’Object1’ => 8, ’Object2’ => 9)); Behaviors Model behaviors are a way to organize some of the functionality defined in CakePHP models. They allow us to separate and reuse logic that creates a type of behavior, and they do this without requiring inheritance. For example creating tree structures. By providing a simple yet powerful way to enhance models, behaviors allow us to attach functionality to models by defining a simple class variable. That’s how behaviors allow models to get rid of all the extra weight that might not be part of the business contract they are modeling, or that is also needed in different models and can then be extrapolated. As an example, consider a model that gives us access to a database table which stores structural information about a tree. Removing, adding, and migrating nodes in the tree is not as simple as deleting, inserting, and editing rows in the table. Many records may need to be updated as things move around. Rather than creating those tree-manipulation methods on a per model basis (for every model that needs that functionality), we could simply tell our model to use the TreeBehavior, or in more formal terms, we tell our model to behave as a Tree. This is known as attaching a behavior to a model. With just one line of code, our CakePHP model takes on a whole new set of methods that allow it to interact with the underlying structure. CakePHP already includes behaviors for tree structures, translated content, access control list interac- tion, not to mention the community-contributed behaviors already available in the CakePHP Bakery (http://bakery.cakephp.org). In this section, we’ll cover the basic usage pattern for adding behaviors to models, how to use CakePHP’s built-in behaviors, and how to create our own. In essence, Behaviors are Mixins1 with callbacks. There are a number of Behaviors included in CakePHP. To find out more about each one, reference the chapters below: ACL class AclBehavior 1 http://en.wikipedia.org/wiki/Mixin General Purpose 361
- 368. CakePHP Cookbook Documentation,Release 2.x The Acl behavior provides a way to seamlessly integrate a model with your ACL system. It can create both AROs or ACOs transparently. To use the new behavior, you can add it to the $actsAs property of your model. When adding it to the actsAs array you choose to make the related Acl entry an ARO or an ACO. The default is to create ACOs: class User extends AppModel { public $actsAs = array(’Acl’ => array(’type’ => ’requester’)); } This would attach the Acl behavior in ARO mode. To join the ACL behavior in ACO mode use: class Post extends AppModel { public $actsAs = array(’Acl’ => array(’type’ => ’controlled’)); } For User and Group models it is common to have both ACO and ARO nodes, to achieve this use: class User extends AppModel { public $actsAs = array(’Acl’ => array(’type’ => ’both’)); } You can also attach the behavior on the fly like so: $this->Post->Behaviors->load(’Acl’, array(’type’ => ’controlled’)); Changed in version 2.1: You can now safely attach AclBehavior to AppModel. Aco, Aro and AclNode now extend Model instead of AppModel, which would cause an infinite loop. If your application depends on having those models to extend AppModel for some reason, then copy AclNode to your application and have it extend AppModel again. Using the AclBehavior Most of the AclBehavior works transparently on your Model’s afterSave(). How- ever, using it requires that your Model has a parentNode() method defined. This is used by the AclBehavior to determine parent->child relationships. A model’s parentNode() method must return null or return a parent Model reference: public function parentNode() { return null; } If you want to set an ACO or ARO node as the parent for your Model, parentNode() must return the alias of the ACO or ARO node: public function parentNode() { return ’root_node’; } A more complete example. Using an example User Model, where User belongsTo Group: public function parentNode() { if (!$this->id && empty($this->data)) { return null; } 362 Chapter 9. Core Libraries
- 369. CakePHP Cookbook Documentation,Release 2.x $data = $this->data; if (empty($this->data)) { $data = $this->read(); } if (!$data[’User’][’group_id’]) { return null; } else { return array(’Group’ => array(’id’ => $data[’User’][’group_id’])); } } In the above example the return is an array that looks similar to the results of a model find. It is important to have the id value set or the parentNode relation will fail. The AclBehavior uses this data to construct its tree structure. node() The AclBehavior also allows you to retrieve the Acl node associated with a model record. After setting $model->id. You can use $model->node() to retrieve the associated Acl node. You can also retrieve the Acl Node for any row, by passing in a data array: $this->User->id = 1; $node = $this->User->node(); $user = array(’User’ => array( ’id’ => 1 )); $node = $this->User->node($user); Will both return the same Acl Node information. If you had setup AclBehavior to create both ACO and ARO nodes, you need to specify which node type you want: $this->User->id = 1; $node = $this->User->node(null, ’Aro’); $user = array(’User’ => array( ’id’ => 1 )); $node = $this->User->node($user, ’Aro’); Containable class ContainableBehavior A new addition to the CakePHP 1.2 core is the ContainableBehavior. This model behavior allows you to filter and limit model find operations. Using Containable will help you cut down on needless wear and tear on your database, increasing the speed and overall performance of your application. The class will also help you search and filter your data for your users in a clean and consistent way. Containable allows you to streamline and simplify operations on your model bindings. It works by temporar- ily or permanently altering the associations of your models. It does this by using supplied the containments to generate a series of bindModel and unbindModel calls. Since Containable only modifies existing General Purpose 363
- 370. CakePHP Cookbook Documentation,Release 2.x relationships it will not allow you to restrict results by distant associations. Instead you should refer to Joining tables. To use the new behavior, you can add it to the $actsAs property of your model: class Post extends AppModel { public $actsAs = array(’Containable’); } You can also attach the behavior on the fly: $this->Post->Behaviors->load(’Containable’); Using Containable To see how Containable works, let’s look at a few examples. First, we’ll start off with a find() call on a model named ‘Post’. Let’s say that ‘Post’ hasMany ‘Comment’, and ‘Post’ hasAndBe- longsToMany ‘Tag’. The amount of data fetched in a normal find() call is rather extensive: debug($this->Post->find(’all’)); [0] => Array ( [Post] => Array ( [id] => 1 [title] => First article [content] => aaa [created] => 2008-05-18 00:00:00 ) [Comment] => Array ( [0] => Array ( [id] => 1 [post_id] => 1 [author] => Daniel [email] => [email protected] [website] => http://example.com [comment] => First comment [created] => 2008-05-18 00:00:00 ) [1] => Array ( [id] => 2 [post_id] => 1 [author] => Sam [email] => [email protected] [website] => http://example.net [comment] => Second comment [created] => 2008-05-18 00:00:00 ) ) [Tag] => Array ( 364 Chapter 9. Core Libraries
- 371. CakePHP Cookbook Documentation,Release 2.x [0] => Array ( [id] => 1 [name] => Awesome ) [1] => Array ( [id] => 2 [name] => Baking ) ) ) [1] => Array ( [Post] => Array (... For some interfaces in your application, you may not need that much information from the Post model. One thing the ContainableBehavior does is help you cut down on what find() returns. For example, to get only the post-related information, you can do the following: $this->Post->contain(); $this->Post->find(’all’); You can also invoke Containable’s magic from inside the find() call: $this->Post->find(’all’, array(’contain’ => false)); Having done that, you end up with something a lot more concise: [0] => Array ( [Post] => Array ( [id] => 1 [title] => First article [content] => aaa [created] => 2008-05-18 00:00:00 ) ) [1] => Array ( [Post] => Array ( [id] => 2 [title] => Second article [content] => bbb [created] => 2008-05-19 00:00:00 ) ) This sort of help isn’t new: in fact, you can do that without the ContainableBehavior doing something like this: General Purpose 365
- 372. CakePHP Cookbook Documentation,Release 2.x $this->Post->recursive = -1; $this->Post->find(’all’); Containable really shines when you have complex associations, and you want to pare down things that sit at the same level. The model’s $recursive property is helpful if you want to hack off an entire level of recursion, but not when you want to pick and choose what to keep at each level. Let’s see how it works by using the contain() method. The contain method’s first argument accepts the name, or an array of names, of the models to keep in the find operation. If we wanted to fetch all posts and their related tags (without any comment information), we’d try something like this: $this->Post->contain(’Tag’); $this->Post->find(’all’); Again, we can use the contain key inside a find() call: $this->Post->find(’all’, array(’contain’ => ’Tag’)); Without Containable, you’d end up needing to use the unbindModel() method of the model, multiple times if you’re paring off multiple models. Containable creates a cleaner way to accomplish this same task. Containing deeper associations Containable also goes a step deeper: you can filter the data of the asso- ciated models. If you look at the results of the original find() call, notice the author field in the Comment model. If you are interested in the posts and the names of the comment authors — and nothing else — you could do something like the following: $this->Post->contain(’Comment.author’); $this->Post->find(’all’); // or.. $this->Post->find(’all’, array(’contain’ => ’Comment.author’)); Here, we’ve told Containable to give us our post information, and just the author field of the associated Comment model. The output of the find call might look something like this: [0] => Array ( [Post] => Array ( [id] => 1 [title] => First article [content] => aaa [created] => 2008-05-18 00:00:00 ) [Comment] => Array ( [0] => Array ( [author] => Daniel [post_id] => 1 366 Chapter 9. Core Libraries
- 373. CakePHP Cookbook Documentation,Release 2.x ) [1] => Array ( [author] => Sam [post_id] => 1 ) ) ) [1] => Array (... As you can see, the Comment arrays only contain the author field (plus the post_id which is needed by CakePHP to map the results). You can also filter the associated Comment data by specifying a condition: $this->Post->contain(’Comment.author = "Daniel"’); $this->Post->find(’all’); //or... $this->Post->find(’all’, array(’contain’ => ’Comment.author = "Daniel"’)); This gives us a result that gives us posts with comments authored by Daniel: [0] => Array ( [Post] => Array ( [id] => 1 [title] => First article [content] => aaa [created] => 2008-05-18 00:00:00 ) [Comment] => Array ( [0] => Array ( [id] => 1 [post_id] => 1 [author] => Daniel [email] => [email protected] [website] => http://example.com [comment] => First comment [created] => 2008-05-18 00:00:00 ) ) ) There is an important caveat to using Containable when filtering on a deeper association. In the previous example, assume you had 3 posts in your database and Daniel had commented on 2 of those posts. The operation $this->Post->find(‘all’, array(‘contain’ => ‘Comment.author = “Daniel”’)); would return ALL 3 posts, not just the 2 posts that Daniel had commented on. It won’t return all comments however, just comments by Daniel.: General Purpose 367
- 374. CakePHP Cookbook Documentation,Release 2.x [0] => Array ( [Post] => Array ( [id] => 1 [title] => First article [content] => aaa [created] => 2008-05-18 00:00:00 ) [Comment] => Array ( [0] => Array ( [id] => 1 [post_id] => 1 [author] => Daniel [email] => [email protected] [website] => http://example.com [comment] => First comment [created] => 2008-05-18 00:00:00 ) ) ) [1] => Array ( [Post] => Array ( [id] => 2 [title] => Second article [content] => bbb [created] => 2008-05-18 00:00:00 ) [Comment] => Array ( ) ) [2] => Array ( [Post] => Array ( [id] => 3 [title] => Third article [content] => ccc [created] => 2008-05-18 00:00:00 ) [Comment] => Array ( [0] => Array ( [id] => 22 [post_id] => 3 [author] => Daniel [email] => [email protected] 368 Chapter 9. Core Libraries
- 375. CakePHP Cookbook Documentation,Release 2.x [website] => http://example.com [comment] => Another comment [created] => 2008-05-18 00:00:00 ) ) ) If you want to filter the posts by the comments, so that posts without a comment by Daniel won’t be returned, the easiest way is to find all the comments by Daniel and contain the Posts.: $this->Comment->find(’all’, array( ’conditions’ => ’Comment.author = "Daniel"’, ’contain’ => ’Post’ )); Additional filtering can be performed by supplying the standard find options: $this->Post->find(’all’, array(’contain’ => array( ’Comment’ => array( ’conditions’ => array(’Comment.author =’ => "Daniel"), ’order’ => ’Comment.created DESC’ ) ))); Here’s an example of using the ContainableBehavior when you’ve got deep and complex model relationships. Let’s consider the following model associations: User->Profile User->Account->AccountSummary User->Post->PostAttachment->PostAttachmentHistory->HistoryNotes User->Post->Tag This is how we retrieve the above associations with Containable: $this->User->find(’all’, array( ’contain’ => array( ’Profile’, ’Account’ => array( ’AccountSummary’ ), ’Post’ => array( ’PostAttachment’ => array( ’fields’ => array(’id’, ’name’), ’PostAttachmentHistory’ => array( ’HistoryNotes’ => array( ’fields’ => array(’id’, ’note’) ) ) ), ’Tag’ => array( ’conditions’ => array(’Tag.name LIKE’ => ’%happy%’) ) General Purpose 369
- 376. CakePHP Cookbook Documentation,Release 2.x ) ) )); Keep in mind that contain key is only used once in the main model, you don’t need to use ‘contain’ again for related models. Note: When using ‘fields’ and ‘contain’ options - be careful to include all foreign keys that your query directly or indirectly requires. Please also note that because Containable must to be attached to all models used in containment, you may consider attaching it to your AppModel. ContainableBehavior options The ContainableBehavior has a number of options that can be set when the Behavior is attached to a model. The settings allow you to fine tune the behavior of Containable and work with other behaviors more easily. • recursive (boolean, optional) set to true to allow containable to automatically determine the recur- siveness level needed to fetch specified models, and set the model recursiveness to this level. setting it to false disables this feature. The default value is true. • notices (boolean, optional) issues E_NOTICES for bindings referenced in a containable call that are not valid. The default value is true. • autoFields: (boolean, optional) auto-add needed fields to fetch requested bindings. The default value is true. • order: (string, optional) the order of how the contained elements are sorted. From the previous example, this is an example of how to force the posts to be ordered by the date when they were last updated: $this->User->find(’all’, array( ’contain’ => array( ’Profile’, ’Post’ => array( ’order’ => ’Post.updated DESC’ ) ) )); You can change ContainableBehavior settings at run time by reattaching the behavior as seen in Behaviors (Using Behaviors). ContainableBehavior can sometimes cause issues with other behaviors or queries that use aggregate func- tions and/or GROUP BY statements. If you get invalid SQL errors due to mixing of aggregate and non- aggregate fields, try disabling the autoFields setting.: $this->Post->Behaviors->load(’Containable’, array(’autoFields’ => false)); Using Containable with pagination By including the ‘contain’ parameter in the $paginate property it will apply to both the find(‘count’) and the find(‘all’) done on the model. 370 Chapter 9. Core Libraries
- 377. CakePHP Cookbook Documentation,Release 2.x See the section Using Containable for further details. Here’s an example of how to contain associations when paginating: $this->paginate[’User’] = array( ’contain’ => array(’Profile’, ’Account’), ’order’ => ’User.username’ ); $users = $this->paginate(’User’); Note: If you contained the associations through the model instead, it will not honor Containable’s recursive option. So if you set recursive to -1 for example for the model, it won’t work: $this->User->recursive = -1; $this->User->contain(array(’Profile’, ’Account’)); $users = $this->paginate(’User’); Translate class TranslateBehavior TranslateBehavior is actually quite easy to setup and works out of the box with very little configuration. In this section, you will learn how to add and setup the behavior to use in any model. If you are using TranslateBehavior in alongside containable issue, be sure to set the ‘fields’ key for your queries. Otherwise you could end up with invalid SQL generated. Initializing the i18n Database Tables You can either use the CakePHP console or you can manually create it. It is advised to use the console for this, because it might happen that the layout changes in future versions of CakePHP. Sticking to the console will make sure that you have the correct layout.: ./cake i18n Select [I] which will run the i18n database initialization script. You will be asked if you want to drop any existing and if you want to create it. Answer with yes if you are sure there is no i18n table already, and answer with yes again to create the table. Attaching the Translate Behavior to your Models Add it to your model by using the $actsAs property like in the following example.: class Post extends AppModel { public $actsAs = array( ’Translate’ ); } This will do nothing yet, because it expects a couple of options before it begins to work. You need to define which fields of the current model should be tracked in the translation table we’ve created in the first step. General Purpose 371
- 378. CakePHP Cookbook Documentation,Release 2.x Defining the Fields You can set the fields by simply extending the ’Translate’ value with another array, like so: class Post extends AppModel { public $actsAs = array( ’Translate’ => array( ’fieldOne’, ’fieldTwo’, ’and_so_on’ ) ); } After you have done that (for example putting “title” as one of the fields) you already finished the basic setup. Great! According to our current example the model should now look something like this: class Post extends AppModel { public $actsAs = array( ’Translate’ => array( ’title’ ) ); } When defining fields for TranslateBehavior to translate, be sure to omit those fields from the translated model’s schema. If you leave the fields in, there can be issues when retrieving data with fallback locales. Note: If all the fields in your model are translated be sure to add created and modified columns to your table. CakePHP requires at least one non primary key field before it will save a record. Conclusion From now on each record update/creation will cause TranslateBehavior to copy the value of “title” to the translation table (default: i18n) along with the current locale. A locale is the identifier of the language, so to speak. Reading translated content By default the TranslateBehavior will automatically fetch and add in data based on the current locale. The current locale is read from Configure::read(’Config.language’) which is assigned by the L10n class. You can override this default on the fly using $Model->locale. Retrieve translated fields in a specific locale By setting $Model->locale you can read translations for a specific locale: // Read the spanish locale data. $this->Post->locale = ’es’; $results = $this->Post->find(’first’, array( ’conditions’ => array(’Post.id’ => $id) )); // $results will contain the spanish translation. 372 Chapter 9. Core Libraries
- 379. CakePHP Cookbook Documentation,Release 2.x Retrieve all translation records for a field If you want to have all translation records attached to the current model record you simply extend the field array in your behavior setup as shown below. The naming is completely up to you.: class Post extends AppModel { public $actsAs = array( ’Translate’ => array( ’title’ => ’titleTranslation’ ) ); } With this setup the result of $this->Post->find() should look something like this: Array ( [Post] => Array ( [id] => 1 [title] => Beispiel Eintrag [body] => lorem ipsum... [locale] => de_de ) [titleTranslation] => Array ( [0] => Array ( [id] => 1 [locale] => en_us [model] => Post [foreign_key] => 1 [field] => title [content] => Example entry ) [1] => Array ( [id] => 2 [locale] => de_de [model] => Post [foreign_key] => 1 [field] => title [content] => Beispiel Eintrag ) ) ) Note: The model record contains a virtual field called “locale”. It indicates which locale is used in this result. Note that only fields of the model you are directly doing ‘find‘ on will be translated. Models attached via as- General Purpose 373
- 380. CakePHP Cookbook Documentation,Release 2.x sociations won’t be translated because triggering callbacks on associated models is currently not supported. Using the bindTranslation method You can also retrieve all translations, only when you need them, using the bindTranslation method TranslateBehavior::bindTranslation($fields, $reset) $fields is a named-key array of field and association name, where the key is the translatable field and the value is the fake association name.: $this->Post->bindTranslation(array(’title’ => ’titleTranslation’)); // need at least recursive 1 for this to work. $this->Post->find(’all’, array(’recursive’ => 1)); With this setup the result of your find() should look something like this: Array ( [Post] => Array ( [id] => 1 [title] => Beispiel Eintrag [body] => lorem ipsum... [locale] => de_de ) [titleTranslation] => Array ( [0] => Array ( [id] => 1 [locale] => en_us [model] => Post [foreign_key] => 1 [field] => title [content] => Example entry ) [1] => Array ( [id] => 2 [locale] => de_de [model] => Post [foreign_key] => 1 [field] => title [content] => Beispiel Eintrag ) ) ) Saving in another language You can force the model which is using the TranslateBehavior to save in a language other than the one detected. 374 Chapter 9. Core Libraries
- 381. CakePHP Cookbook Documentation,Release 2.x To tell a model in what language the content is going to be you simply change the value of the $locale property on the model before you save the data to the database. You can do that either in your controller or you can define it directly in the model. Example A: In your controller: class PostsController extends AppController { public function add() { if (!empty($this->request->data)) { // we are going to save the german version $this->Post->locale = ’de_de’; $this->Post->create(); if ($this->Post->save($this->request->data)) { return $this->redirect(array(’action’ => ’index’)); } } } } Example B: In your model: class Post extends AppModel { public $actsAs = array( ’Translate’ => array( ’title’ ) ); // Option 1) just define the property directly public $locale = ’en_us’; // Option 2) create a simple method public function setLanguage($locale) { $this->locale = $locale; } } Multiple Translation Tables If you expect a lot entries you probably wonder how to deal with a rapidly growing database table. There are two properties introduced by TranslateBehavior that allow to specify which “Model” to bind as the model containing the translations. These are $translateModel and $translateTable. Lets say we want to save our translations for all posts in the table “post_i18ns” instead of the default “i18n” table. To do so you need to setup your model like this: class Post extends AppModel { public $actsAs = array( ’Translate’ => array( ’title’ ) ); General Purpose 375
- 382. CakePHP Cookbook Documentation,Release 2.x // Use a different model (and table) public $translateModel = ’PostI18n’; } Note: It is important that you to pluralize the table. It is now a usual model and can be treated as such and thus comes with the conventions involved. The table schema itself must be identical with the one generated by the CakePHP console script. To make sure it fits one could just initialize a empty i18n table using the console and rename the table afterwards. Create the TranslateModel For this to work you need to create the actual model file in your models folder. Reason is that there is no property to set the displayField directly in the model using this behavior yet. Make sure that you change the $displayField to ’field’.: class PostI18n extends AppModel { public $displayField = ’field’; // important } // filename: PostI18n.php That’s all it takes. You can also add all other model stuff here like $useTable. But for better consis- tency we could do that in the model which actually uses this translation model. This is where the optional $translateTable comes into play. Changing the Table If you want to change the name of the table you simply define $translateTable in your model, like so: class Post extends AppModel { public $actsAs = array( ’Translate’ => array( ’title’ ) ); // Use a different model public $translateModel = ’PostI18n’; // Use a different table for translateModel public $translateTable = ’post_translations’; } Please note that you can’t use $translateTable alone. If you don’t intend to use a custom $translateModel then leave this property untouched. Reason is that it would break your setup and show you a “Missing Table” message for the default I18n model which is created in runtime. Tree class TreeBehavior 376 Chapter 9. Core Libraries
- 383. CakePHP Cookbook Documentation,Release 2.x It’s fairly common to want to store hierarchical data in a database table. Examples of such data might be categories with unlimited subcategories, data related to a multilevel menu system or a literal representation of hierarchy such as is used to store access control objects with ACL logic. For small trees of data, or where the data is only a few levels deep it is simple to add a parent_id field to your database table and use this to keep track of which item is the parent of what. Bundled with cake however, is a powerful behavior which allows you to use the benefits of MPTT logic2 without worrying about any of the intricacies of the technique - unless you want to ;). Requirements To use the tree behavior, your database table needs 3 fields as listed below (all are ints): • parent - default fieldname is parent_id, to store the id of the parent object • left - default fieldname is lft, to store the lft value of the current row. • right - default fieldname is rght, to store the rght value of the current row. If you are familiar with MPTT logic you may wonder why a parent field exists - quite simply it’s easier to do certain tasks if a direct parent link is stored on the database - such as finding direct children. Note: The parent field must be able to have a NULL value! It might seem to work if you just give the top elements a parent value of zero, but reordering the tree (and possible other operations) will fail. Basic Usage The tree behavior has a lot packed into it, but let’s start with a simple example - create the following database table and put some data in it: CREATE TABLE categories ( id INTEGER(10) UNSIGNED NOT NULL AUTO_INCREMENT, parent_id INTEGER(10) DEFAULT NULL, lft INTEGER(10) DEFAULT NULL, rght INTEGER(10) DEFAULT NULL, name VARCHAR(255) DEFAULT ’’, PRIMARY KEY (id) ); INSERT INTO ‘categories‘ (‘id‘, ‘name‘, ‘parent_id‘, ‘lft‘, ‘rght‘) VALUES (1, ’My Categories’, NULL, 1, 30); INSERT INTO ‘categories‘ (‘id‘, ‘name‘, ‘parent_id‘, ‘lft‘, ‘rght‘) VALUES (2, ’Fun’, 1, 2, 15); INSERT INTO ‘categories‘ (‘id‘, ‘name‘, ‘parent_id‘, ‘lft‘, ‘rght‘) VALUES (3, ’Sport’, 2, 3, 8); INSERT INTO ‘categories‘ (‘id‘, ‘name‘, ‘parent_id‘, ‘lft‘, ‘rght‘) VALUES 2 http://www.sitepoint.com/hierarchical-data-database-2/ General Purpose 377
- 384. CakePHP Cookbook Documentation,Release 2.x (4, ’Surfing’, 3, 4, 5); INSERT INTO ‘categories‘ (‘id‘, ‘name‘, ‘parent_id‘, ‘lft‘, ‘rght‘) VALUES (5, ’Extreme knitting’, 3, 6, 7); INSERT INTO ‘categories‘ (‘id‘, ‘name‘, ‘parent_id‘, ‘lft‘, ‘rght‘) VALUES (6, ’Friends’, 2, 9, 14); INSERT INTO ‘categories‘ (‘id‘, ‘name‘, ‘parent_id‘, ‘lft‘, ‘rght‘) VALUES (7, ’Gerald’, 6, 10, 11); INSERT INTO ‘categories‘ (‘id‘, ‘name‘, ‘parent_id‘, ‘lft‘, ‘rght‘) VALUES (8, ’Gwendolyn’, 6, 12, 13); INSERT INTO ‘categories‘ (‘id‘, ‘name‘, ‘parent_id‘, ‘lft‘, ‘rght‘) VALUES (9, ’Work’, 1, 16, 29); INSERT INTO ‘categories‘ (‘id‘, ‘name‘, ‘parent_id‘, ‘lft‘, ‘rght‘) VALUES (10, ’Reports’, 9, 17, 22); INSERT INTO ‘categories‘ (‘id‘, ‘name‘, ‘parent_id‘, ‘lft‘, ‘rght‘) VALUES (11, ’Annual’, 10, 18, 19); INSERT INTO ‘categories‘ (‘id‘, ‘name‘, ‘parent_id‘, ‘lft‘, ‘rght‘) VALUES (12, ’Status’, 10, 20, 21); INSERT INTO ‘categories‘ (‘id‘, ‘name‘, ‘parent_id‘, ‘lft‘, ‘rght‘) VALUES (13, ’Trips’, 9, 23, 28); INSERT INTO ‘categories‘ (‘id‘, ‘name‘, ‘parent_id‘, ‘lft‘, ‘rght‘) VALUES (14, ’National’, 13, 24, 25); INSERT INTO ‘categories‘ (‘id‘, ‘name‘, ‘parent_id‘, ‘lft‘, ‘rght‘) VALUES (15, ’International’, 13, 26, 27); For the purpose of checking that everything is setup correctly, we can create a test method and output the contents of our category tree to see what it looks like. With a simple controller: class CategoriesController extends AppController { public function index() { $data = $this->Category->generateTreeList( 378 Chapter 9. Core Libraries
- 385. CakePHP Cookbook Documentation,Release 2.x null, null, null, ’ ’ ); debug($data); die; } } and an even simpler model definition: // app/Model/Category.php class Category extends AppModel { public $actsAs = array(’Tree’); } We can check what our category tree data looks like by visiting /categories You should see something like this: • My Categories – Fun * Sport · Surfing · Extreme knitting * Friends · Gerald · Gwendolyn – Work * Reports · Annual · Status * Trips · National · International Adding data In the previous section, we used existing data and checked that it looked hierarchal via the method generateTreeList. However, usually you would add your data in exactly the same way as you would for any model. For example: // pseudo controller code $data[’Category’][’parent_id’] = 3; $data[’Category’][’name’] = ’Skating’; $this->Category->save($data); General Purpose 379
- 386. CakePHP Cookbook Documentation,Release 2.x When using the tree behavior it’s not necessary to do any more than set the parent_id, and the tree behavior will take care of the rest. If you don’t set the parent_id, the tree behavior will add to the tree making your new addition a new top level entry: // pseudo controller code $data = array(); $data[’Category’][’name’] = ’Other People’s Categories’; $this->Category->save($data); Running the above two code snippets would alter your tree as follows: • My Categories – Fun * Sport · Surfing · Extreme knitting · Skating New * Friends · Gerald · Gwendolyn – Work * Reports · Annual · Status * Trips · National · International • Other People’s Categories New Modifying data Modifying data is as transparent as adding new data. If you modify something, but do not change the parent_id field - the structure of your data will remain unchanged. For example: // pseudo controller code $this->Category->id = 5; // id of Extreme knitting $this->Category->save(array(’name’ => ’Extreme fishing’)); The above code did not affect the parent_id field - even if the parent_id is included in the data that is passed to save if the value doesn’t change, neither does the data structure. Therefore the tree of data would now look like: • My Categories 380 Chapter 9. Core Libraries
- 387. CakePHP Cookbook Documentation,Release 2.x • Fun • Sport – Surfing – Extreme fishing Updated – Skating • Friends – Gerald – Gwendolyn • Work • Reports – Annual – Status • Trips – National – International • Other People’s Categories Moving data around in your tree is also a simple affair. Let’s say that Extreme fishing does not belong under Sport, but instead should be located under Other People’s Categories. With the following code: // pseudo controller code $this->Category->id = 5; // id of Extreme fishing $newParentId = $this->Category->field( ’id’, array(’name’ => ’Other People’s Categories’) ); $this->Category->save(array(’parent_id’ => $newParentId)); As would be expected the structure would be modified to: • My Categories • Fun – Sport * Surfing * Skating – Friends * Gerald * Gwendolyn General Purpose 381
- 388. CakePHP Cookbook Documentation,Release 2.x • Work – Reports * Annual * Status – Trips * National * International • Other People’s Categories • Extreme fishing Moved Deleting data The tree behavior provides a number of ways to manage deleting data. To start with the simplest example; let’s say that the reports category is no longer useful. To remove it and any children it may have just call delete as you would for any model. For example with the following code: // pseudo controller code $this->Category->id = 10; $this->Category->delete(); The category tree would be modified as follows: • My Categories • Fun – Sport * Surfing * Skating – Friends * Gerald * Gwendolyn • Work – Trips * National * International • Other People’s Categories • Extreme fishing 382 Chapter 9. Core Libraries
- 389. CakePHP Cookbook Documentation,Release 2.x Querying and using your data Using and manipulating hierarchical data can be a tricky business. In addition to the core find methods, with the tree behavior there are a few more tree-orientated permutations at your disposal. Note: Most tree behavior methods return and rely on data being sorted by the lft field. If you call find() and do not order by lft, or call a tree behavior method and pass a sort order, you may get undesirable results. class TreeBehavior children($id = null, $direct = false, $fields = null, $order = null, $limit = null, $page = 1, $recursive = null) Parameters • $id – The ID of the record to look up • $direct – Set to true to return only the direct descendants • $fields – Single string field name or array of fields to include in the return • $order – SQL string of ORDER BY conditions • $limit – SQL LIMIT statement • $page – for accessing paged results • $recursive – Number of levels deep for recursive associated Models The children method takes the primary key value (the id) of a row and returns the children, by default in the order they appear in the tree. The second optional parameter defines whether or not only direct children should be returned. Using the example data from the previous section: $allChildren = $this->Category->children(1); // a flat array with 11 items // -- or -- $this->Category->id = 1; $allChildren = $this->Category->children(); // a flat array with 11 items // Only return direct children $directChildren = $this->Category->children(1, true); // a flat array with // 2 items Note: If you want a recursive array use find(’threaded’) childCount($id = null, $direct = false) As with the method children, childCount takes the primary key value (the id) of a row and returns how many children it has. The second optional parameter defines whether or not only direct children are counted. Using the example data from the previous section: $totalChildren = $this->Category->childCount(1); // will output 11 // -- or -- $this->Category->id = 1; General Purpose 383
- 390. CakePHP Cookbook Documentation,Release 2.x $directChildren = $this->Category->childCount(); // will output 11 // Only counts the direct descendants of this category $numChildren = $this->Category->childCount(1, true); // will output 2 generateTreeList($conditions=null, $keyPath=null, $valuePath=null, $spacer= ‘_’, $recursive=null) Parameters • $conditions – Uses the same conditional options as find(). • $keyPath – Path to the field to use for the key. • $valuePath – Path to the field to use for the label. • $spacer – The string to use in front of each item to indicate depth. • $recursive – The number of levels deep to fetch associated records This method will return data similar to find(‘list’) but with a nested prefix that is specified in the spacer option to show the structure of your data. Below is an example of what you can expect this method to return: $treelist = $this->Category->generateTreeList(); Output: array( [1] => "My Categories", [2] => "_Fun", [3] => "__Sport", [4] => "___Surfing", [16] => "___Skating", [6] => "__Friends", [7] => "___Gerald", [8] => "___Gwendolyn", [9] => "_Work", [13] => "__Trips", [14] => "___National", [15] => "___International", [17] => "Other People’s Categories", [5] => "_Extreme fishing" ) getParentNode() This convenience function will, as the name suggests, return the parent node for any node, or false if the node has no parent (it’s the root node). For example: $parent = $this->Category->getParentNode(2); //<- id for fun // $parent contains All categories getPath($id = null, $fields = null, $recursive = null) 384 Chapter 9. Core Libraries
- 391. CakePHP Cookbook Documentation,Release 2.x The ‘path’ when referring to hierarchal data is how you get from where you are to the top. So for example the path from the category “International” is: •My Categories •... •Work –Trips *... *International Using the id of “International” getPath will return each of the parents in turn (starting from the top).: $parents = $this->Category->getPath(15); // contents of $parents array( [0] => array( ’Category’ => array(’id’ => 1, ’name’ => ’My Categories’, ..) ), [1] => array( ’Category’ => array(’id’ => 9, ’name’ => ’Work’, ..) ), [2] => array( ’Category’ => array(’id’ => 13, ’name’ => ’Trips’, ..) ), [3] => array( ’Category’ => array(’id’ => 15, ’name’ => ’International’, ..) ), ) Advanced Usage The tree behavior doesn’t only work in the background, there are a number of specific meth- ods defined in the behavior to cater for all your hierarchical data needs, and any unexpected problems that might arise in the process. TreeBehavior::moveDown() Used to move a single node down the tree. You need to provide the ID of the element to be moved and a positive number of how many positions the node should be moved down. All child nodes for the specified node will also be moved. Here is an example of a controller action (in a controller named Categories) that moves a spec- ified node down the tree: public function movedown($id = null, $delta = null) { $this->Category->id = $id; if (!$this->Category->exists()) { throw new NotFoundException(__(’Invalid category’)); General Purpose 385
- 392. CakePHP Cookbook Documentation,Release 2.x } if ($delta > 0) { $this->Category->moveDown($this->Category->id, abs($delta)); } else { $this->Session->setFlash( ’Please provide the number of positions the field should be’ . ’moved down.’ ); } return $this->redirect(array(’action’ => ’index’)); } For example, if you’d like to move the “Sport” ( id of 3 ) category one position down, you would request: /categories/movedown/3/1. TreeBehavior::moveUp() Used to move a single node up the tree. You need to provide the ID of the element to be moved and a positive number of how many positions the node should be moved up. All child nodes will also be moved. Here’s an example of a controller action (in a controller named Categories) that moves a node up the tree: public function moveup($id = null, $delta = null) { $this->Category->id = $id; if (!$this->Category->exists()) { throw new NotFoundException(__(’Invalid category’)); } if ($delta > 0) { $this->Category->moveUp($this->Category->id, abs($delta)); } else { $this->Session->setFlash( ’Please provide a number of positions the category should’ . ’be moved up.’ ); } return $this->redirect(array(’action’ => ’index’)); } For example, if you would like to move the category “Gwendolyn” ( id of 8 ) up one position you would request /categories/moveup/8/1. Now the order of Friends will be Gwendolyn, Gerald. TreeBehavior::removeFromTree($id = null, $delete = false) Using this method will either delete or move a node but retain its sub-tree, which will be re- parented one level higher. It offers more control than delete, which for a model using the tree behavior will remove the specified node and all of its children. Taking the following tree as a starting point: 386 Chapter 9. Core Libraries
- 393. CakePHP Cookbook Documentation,Release 2.x • My Categories – Fun * Sport · Surfing · Extreme knitting · Skating Running the following code with the id for ‘Sport’: $this->Node->removeFromTree($id); The Sport node will be become a top level node: • My Categories – Fun * Surfing * Extreme knitting * Skating • Sport Moved This demonstrates the default behavior of removeFromTree of moving the node to have no parent, and re-parenting all children. If however the following code snippet was used with the id for ‘Sport’: $this->Node->removeFromTree($id, true); The tree would become • My Categories – Fun * Surfing * Extreme knitting * Skating This demonstrates the alternate use for removeFromTree, the children have been reparented and ‘Sport’ has been deleted. TreeBehavior::reorder(array(‘id’ => null, ‘field’ => $Model->displayField, ‘order’ => ‘ASC’, ‘verify’ => true)) Reorders the nodes (and child nodes) of the tree according to the field and direction specified in the parameters. This method does not change the parent of any node.: General Purpose 387
- 394. CakePHP Cookbook Documentation,Release 2.x $model->reorder(array( //id of record to use as top node for reordering, default: $Model->id ’id’ => , //which field to use in reordering, default: $Model->displayField ’field’ => , //direction to order, default: ’ASC’ ’order’ => , //whether or not to verify the tree before reorder, default: true ’verify’ => )); Note: If you have saved your data or made other operations on the model, you might want to set $model->id = null before calling reorder. Otherwise only the current node and it’s children will be reordered. Data Integrity Due to the nature of complex self referential data structures such as trees and linked lists, they can occasionally become broken by a careless call. Take heart, for all is not lost! The Tree Behavior contains several previously undocumented features designed to recover from such situations. TreeBehavior::recover($mode = ‘parent’, $missingParentAction = null) The mode parameter is used to specify the source of info that is valid/correct. The opposite source of data will be populated based upon that source of info. E.g. if the MPTT fields are corrupt or empty, with the $mode ’parent’ the values of the parent_id field will be used to populate the left and right fields. The missingParentAction parameter only applies to “parent” mode and determines what to do if the parent field contains an id that is not present. Available $mode options: • ’parent’ - use the existing parent_id‘s to update the lft and rght fields • ’tree’ - use the existing lft and rght fields to update parent_id Available missingParentActions options when using mode=’parent’: • null - do nothing and carry on • ’return’ - do nothing and return • ’delete’ - delete the node • int - set the parent_id to this id Example: // Rebuild all the left and right fields based on the parent_id $this->Category->recover(); // or $this->Category->recover(’parent’); 388 Chapter 9. Core Libraries
- 395. CakePHP Cookbook Documentation,Release 2.x // Rebuild all the parent_id’s based on the lft and rght fields $this->Category->recover(’tree’); TreeBehavior::reorder($options = array()) Reorders the nodes (and child nodes) of the tree according to the field and direction specified in the parameters. This method does not change the parent of any node. Reordering affects all nodes in the tree by default, however the following options can affect the process: • ’id’ - only reorder nodes below this node. • ’field‘ - field to use for sorting, default is the displayField for the model. • ’order’ - ’ASC’ for ascending, ’DESC’ for descending sort. • ’verify’ - whether or not to verify the tree prior to resorting. $options is used to pass all extra parameters, and has the following possible keys by default, all of which are optional: array( ’id’ => null, ’field’ => $model->displayField, ’order’ => ’ASC’, ’verify’ => true ) TreeBehavior::verify() Returns true if the tree is valid otherwise an array of errors, with fields for type, incorrect index and message. Each record in the output array is an array of the form (type, id, message) • type is either ’index’ or ’node’ • ’id’ is the id of the erroneous node. • ’message’ depends on the error Example Use: $this->Category->verify(); Example output: Array ( [0] => Array ( [0] => node [1] => 3 [2] => left and right values identical ) [1] => Array General Purpose 389
- 396. CakePHP Cookbook Documentation,Release 2.x ( [0] => node [1] => 2 [2] => The parent node 999 doesn ’ t exist ) [10] => Array ( [0] => index [1] => 123 [2] => missing ) [99] => Array ( [0] => node [1] => 163 [2] => left greater than right ) ) Using Behaviors Behaviors are attached to models through the $actsAs model class variable: class Category extends AppModel { public $actsAs = array(’Tree’); } This example shows how a Category model could be managed in a tree structure using the TreeBehavior. Once a behavior has been specified, use the methods added by the behavior as if they always existed as part of the original model: // Set ID $this->Category->id = 42; // Use behavior method, children(): $kids = $this->Category->children(); Some behaviors may require or allow settings to be defined when the behavior is attached to the model. Here, we tell our TreeBehavior the names of the “left” and “right” fields in the underlying database table: class Category extends AppModel { public $actsAs = array(’Tree’ => array( ’left’ => ’left_node’, ’right’ => ’right_node’ )); } We can also attach several behaviors to a model. There’s no reason why, for example, our Category model should only behave as a tree, it may also need internationalization support: class Category extends AppModel { public $actsAs = array( ’Tree’ => array( 390 Chapter 9. Core Libraries
- 397. CakePHP Cookbook Documentation,Release 2.x ’left’ => ’left_node’, ’right’ => ’right_node’ ), ’Translate’ ); } So far we have been adding behaviors to models using a model class variable. That means that our behaviors will be attached to our models throughout the model’s lifetime. However, we may need to “detach” behaviors from our models at runtime. Let’s say that on our previous Category model, which is acting as a Tree and a Translate model, we need for some reason to force it to stop acting as a Translate model: // Detach a behavior from our model: $this->Category->Behaviors->unload(’Translate’); That will make our Category model stop behaving as a Translate model from thereon. We may need, instead, to just disable the Translate behavior from acting upon our normal model operations: our finds, our saves, etc. In fact, we are looking to disable the behavior from acting upon our CakePHP model callbacks. Instead of detaching the behavior, we then tell our model to stop informing of these callbacks to the Translate behavior: // Stop letting the behavior handle our model callbacks $this->Category->Behaviors->disable(’Translate’); We may also need to find out if our behavior is handling those model callbacks, and if not we then restore its ability to react to them: // If our behavior is not handling model callbacks if (!$this->Category->Behaviors->enabled(’Translate’)) { // Tell it to start doing so $this->Category->Behaviors->enable(’Translate’); } Just as we could completely detach a behavior from a model at runtime, we can also attach new behaviors. Say that our familiar Category model needs to start behaving as a Christmas model, but only on Christmas day: // If today is Dec 25 if (date(’m/d’) === ’12/25’) { // Our model needs to behave as a Christmas model $this->Category->Behaviors->load(’Christmas’); } We can also use the load method to override behavior settings: // We will change one setting from our already attached behavior $this->Category->Behaviors->load(’Tree’, array(’left’ => ’new_left_node’)); There’s also a method to obtain the list of behaviors a model has attached. If we pass the name of a behavior to the method, it will tell us if that behavior is attached to the model, otherwise it will give us the list of attached behaviors: General Purpose 391
- 398. CakePHP Cookbook Documentation,Release 2.x // If the Translate behavior is not attached if (!$this->Category->Behaviors->loaded(’Translate’)) { // Get the list of all behaviors the model has attached $behaviors = $this->Category->Behaviors->loaded(); } Creating Behaviors Behaviors that are attached to Models get their callbacks called automatically. The callbacks are similar to those found in Models: beforeFind, afterFind, beforeValidate, afterValidate, beforeSave, afterSave, beforeDelete, afterDelete and onError - see Callback Methods. Your behaviors should be placed in app/Model/Behavior. They are named in CamelCase and postfixed by Behavior, ex. NameBehavior.php. It’s often helpful to use a core behavior as a template when creating your own. Find them in lib/Cake/Model/Behavior/. Every callback and behavior method takes a reference to the model it is being called from as the first parameter. Besides implementing the callbacks, you can add settings per behavior and/or model behavior attachment. Information about specifying settings can be found in the chapters about core behaviors and their configu- ration. A quick example that illustrates how behavior settings can be passed from the model to the behavior: class Post extends AppModel { public $actsAs = array( ’YourBehavior’ => array( ’option1_key’ => ’option1_value’ ) ); } Since behaviors are shared across all the model instances that use them, it’s a good practice to store the settings per alias/model name that is using the behavior. When created behaviors will have their setup() method called: public function setup(Model $Model, $settings = array()) { if (!isset($this->settings[$Model->alias])) { $this->settings[$Model->alias] = array( ’option1_key’ => ’option1_default_value’, ’option2_key’ => ’option2_default_value’, ’option3_key’ => ’option3_default_value’, ); } $this->settings[$Model->alias] = array_merge( $this->settings[$Model->alias], (array)$settings); } Creating behavior methods Behavior methods are automatically available on any model acting as the behavior. For example if you had: 392 Chapter 9. Core Libraries
- 399. CakePHP Cookbook Documentation,Release 2.x class Duck extends AppModel { public $actsAs = array(’Flying’); } You would be able to call FlyingBehavior methods as if they were methods on your Duck model. When creating behavior methods you automatically get passed a reference of the calling model as the first parameter. All other supplied parameters are shifted one place to the right. For example: $this->Duck->fly(’toronto’, ’montreal’); Although this method takes two parameters, the method signature should look like: public function fly(Model $Model, $from, $to) { // Do some flying. } Keep in mind that methods called in a $this->doIt() fashion from inside a behavior method will not get the $model parameter automatically appended. Mapped methods In addition to providing ‘mixin’ methods, behaviors can also provide pattern matching methods. Behaviors can also define mapped methods. Mapped methods use pattern matching for method invocation. This allows you to create methods similar to Model::findAllByXXX methods on your behaviors. Mapped methods need to be declared in your behaviors $mapMethods array. The method signature for a mapped method is slightly different than a normal behavior mixin method: class MyBehavior extends ModelBehavior { public $mapMethods = array(’/do(w+)/’ => ’doSomething’); public function doSomething(Model $model, $method, $arg1, $arg2) { debug(func_get_args()); //do something } } The above will map every doXXX() method call to the behavior. As you can see, the model is still the first parameter, but the called method name will be the 2nd parameter. This allows you to munge the method name for additional information, much like Model::findAllByXX. If the above behavior was attached to a model the following would happen: $model->doReleaseTheHounds(’homer’, ’lenny’); // would output ’ReleaseTheHounds’, ’homer’, ’lenny’ Behavior callbacks Model Behaviors can define a number of callbacks that are triggered before the model callbacks of the same name. Behavior callbacks allow your behaviors to capture events in attached models and augment the parameters or splice in additional behavior. All behavior callbacks are fired before the model callbacks are: • beforeFind General Purpose 393
- 400. CakePHP Cookbook Documentation,Release 2.x • afterFind • beforeValidate • afterValidate • beforeSave • afterSave • beforeDelete • afterDelete Creating a behavior callback class ModelBehavior Model behavior callbacks are defined as simple methods in your behavior class. Much like regular behavior methods, they receive a $Model parameter as the first argument. This parameter is the model that the behavior method was invoked on. ModelBehavior::setup(Model $Model, array $settings = array()) Called when a behavior is attached to a model. The settings come from the attached model’s $actsAs property. ModelBehavior::cleanup(Model $Model) Called when a behavior is detached from a model. The base method removes model settings based on $model->alias. You can override this method and provide custom cleanup functionality. ModelBehavior::beforeFind(Model $Model, array $query) If a behavior’s beforeFind return’s false it will abort the find(). Returning an array will augment the query parameters used for the find operation. ModelBehavior::afterFind(Model $Model, mixed $results, boolean $primary = false) You can use the afterFind to augment the results of a find. The return value will be passed on as the results to either the next behavior in the chain or the model’s afterFind. ModelBehavior::beforeValidate(Model $Model, array $options = array()) You can use beforeValidate to modify a model’s validate array or handle any other pre-validation logic. Returning false from a beforeValidate callback will abort the validation and cause it to fail. ModelBehavior::afterValidate(Model $Model) You can use afterValidate to perform any data cleanup or preparation if needed. ModelBehavior::beforeSave(Model $Model, array $options = array()) You can return false from a behavior’s beforeSave to abort the save. Return true to allow it continue. ModelBehavior::afterSave(Model $Model, boolean $created, array $options = array()) You can use afterSave to perform clean up operations related to your behavior. $created will be true when a record is created, and false when a record is updated. ModelBehavior::beforeDelete(Model $Model, boolean $cascade = true) You can return false from a behavior’s beforeDelete to abort the delete. Return true to allow it con- tinue. 394 Chapter 9. Core Libraries
- 401. CakePHP Cookbook Documentation,Release 2.x ModelBehavior::afterDelete(Model $Model) You can use afterDelete to perform clean up operations related to your behavior. Components Components are packages of logic that are shared between controllers. CakePHP comes with a fantastic set of core components you can use to aid in various common tasks. You can also create your own components. If you find yourself wanting to copy and paste things between controllers, you should consider creating your own component to contain the functionality. Creating components keeps controller code clean and allows you to reuse code between projects. Each of the core components is detailed in its own chapter. See Components. This section describes how to configure and use components, and how to create your own components. Configuring Components Many of the core components require configuration. Some examples of components requiring configuration are Authentication and Cookie. Configuration for these compo- nents, and for components in general, is usually done in the $components array or your controller’s beforeFilter() method: class PostsController extends AppController { public $components = array( ’Auth’ => array( ’authorize’ => array(’controller’), ’loginAction’ => array( ’controller’ => ’users’, ’action’ => ’login’ ) ), ’Cookie’ => array(’name’ => ’CookieMonster’) ); The previous fragment of code would be an example of configuring a component with the $components array. All core components allow their configuration settings to be set in this way. In addition, you can configure components in your controller’s 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’; } It’s possible, however, that a component requires certain configuration options to be set before the con- troller’s beforeFilter() is run. To this end, some components allow configuration options be set in the $components array: public $components = array( ’DebugKit.Toolbar’ => array(’panels’ => array(’history’, ’session’)) ); General Purpose 395
- 402. CakePHP Cookbook Documentation,Release 2.x Consult the relevant documentation to determine what configuration 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 you’ve 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: 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 fly 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 controller’s method you can do the following: $this->OneTimer = $this->Components->load(’OneTimer’); $this->OneTimer->getTime(); 396 Chapter 9. Core Libraries
- 403. CakePHP Cookbook Documentation,Release 2.x Note: Keep in mind that loading a component on the fly 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 aug- ment 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 opera- tion in many different parts of the application. We could create a component to house this shared logic for use in many different controllers. The first step is to create a new component file and class. Create the file 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; } } Note: All components must extend Component. Failing to do this will trigger an exception. Including your component in your controllers Once our component is finished, we can use it in the ap- plication’s controllers by placing the component’s name (without the “Component” part) in the controller’s $components array. The controller will automatically be given a new attribute named after the compo- nent, 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 Component’s constructor. These parameters can then be handled by the Component: public $components = array( ’Math’ => array( ’precision’ => 2, ’randomGenerator’ => ’srand’ ), ’Session’, ’Auth’ ); General Purpose 397
- 404. CakePHP Cookbook Documentation,Release 2.x The above would pass the array containing precision and randomGenerator to MathComponent::__construct() as the second parameter. By convention, if array keys match component’s public properties, the properties will be set to the values of these keys. 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) { $this->Existing->foo(); } public function bar() { // ... } } // app/Controller/Component/ExistingComponent.php App::uses(’Component’, ’Controller’); class ExistingComponent extends Component { public function foo() { // ... } } Note: In contrast to a component included in a controller no callbacks will be triggered on a component’s 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) Is called before the controller’s beforeFilter method. 398 Chapter 9. Core Libraries
- 405. CakePHP Cookbook Documentation,Release 2.x Component::startup(Controller $controller) Is called after the controller’s beforeFilter method but before the controller executes the current action handler. Component::beforeRender(Controller $controller) Is called after the controller executes the requested action’s logic, but before the controller’s renders views and layout. Component::shutdown(Controller $controller) Is called before output is sent to the browser. Component::beforeRedirect(Controller $controller, $url, $status=null, $exit=true) Is invoked when the controller’s redirect method is called but before any further action. If this method returns false the controller will not continue on to redirect the request. The $url, $status and $exit variables have same meaning as for the controller’s method. You can also return a string which will be interpreted as the URL to redirect to or return an associative array with the key ‘url’ and optionally ‘status’ and ‘exit’. Helpers Helpers are the component-like classes for the presentation layer of your application. They con- tain 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 CakePHP’s core helpers can help you accomplish. 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 CakePHP temporarily stores parsed layouts and views as simple PHP + HTML files. 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 file and output to generate the cache file. 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 CakePHP doesn’t find 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 Configure write call for Cache.check. This will tell CakePHP to check for, and generate view cache files when handling requests. Once you’ve uncommented the Cache.check line you will need to add the helper to your controller’s $helpers array: General Purpose 399
- 406. CakePHP Cookbook Documentation,Release 2.x class PostsController extends AppController { public $helpers = array(’Cache’); } You will also need to add the CacheDispatcher to your dispatcher filters 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 Config- ure::write(‘Cache.viewPrefix’, ‘YOURPREFIX’); to store the view cache files prefixed. Additional configuration options CacheHelper has a few additional configuration 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 traffic that needs to be cached: 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 files to create the components and models for the controller. Additionally, fire 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 don’t 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. 400 Chapter 9. Core Libraries
- 407. CakePHP Cookbook Documentation,Release 2.x To indicate blocks of content that are not to be cached, wrap them in <!--nocache--> <!--/nocache--> like so: <!--nocache--> <?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; ?> <!--/nocache--> 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 file is created, the request object, and view variables are serialized with PHP’s serialize(). 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 modified. 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 you’ve 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 files. If you need to clear the cached view files, 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 flexible - it will do almost everything for you using conventions, or you can use specific methods to get only what you need. Creating Forms The first method you’ll 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 General Purpose 401
- 408. CakePHP Cookbook Documentation,Release 2.x create() inside a UsersController view, I’d 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. 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 form’s context. All fields are assumed to belong to this model (unless otherwise specified), 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 prop- erty to automatically detect whether to create an add or edit form. If $this->request->data contains an array element named after the form’s model, and that array contains a non-empty value of the model’s 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 field is generated to override the default HTTP method. 402 Chapter 9. Core Libraries
- 409. CakePHP Cookbook Documentation,Release 2.x 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 configuration 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(). 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’, ‘file’, ‘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 ‘file’ 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 file elements inside the form. The absence of the proper enctype attribute will cause the file 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 specific action in your current controller. For example, if you’d 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 isn’t 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: General Purpose 403
- 410. CakePHP Cookbook Documentation,Release 2.x 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’ )); 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 form’s 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 form’s 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 // has a label element echo $this->Form->input( ’username’, array(’label’ => ’Username’) ); Closing the Form FormHelper::end($options = null, $secureAttributes = array()) 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: 404 Chapter 9. Core Libraries
- 411. CakePHP Cookbook Documentation,Release 2.x <?php echo $this->Form->create(); ?> <!-- Form elements go here --> <?php echo $this->Form->end(); ?> If a string is supplied as the first 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(): $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 Form Helper API3 for further details. Note: If you are using SecurityComponent in your application you should always end your forms with end(). Changed in version 2.5: The $secureAttributes parameter was added in 2.5. Creating form elements There are a few ways to create form inputs with the FormHelper. We’ll start by looking at input(). This method will automatically inspect the model field it has been supplied in order to create an appropriate input for that field. Internally input() delegates to other methods in FormHelper. FormHelper::input(string $fieldName, array $options = array()) Creates the following elements given a particular Model.field: •Wrapping div. •Label element 3 http://api.cakephp.org/2.4/class-FormHelper.html General Purpose 405
- 412. CakePHP Cookbook Documentation,Release 2.x •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 binary file The $options parameter allows you to customize how input() works, and finely control what is generated. The wrapping div will have a required class name appended if the validation rules for the Model’s field do not specify allowEmpty => true. One limitation of this behavior is the field’s model must have been loaded during this request. Or be directly associated to the model supplied to create(). New in version 2.5: The binary type now maps to a file input. 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 field. 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, let’s assume that your User model includes fields 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 fields: echo $this->Form->create(); echo $this->Form->input(’username’); //text echo $this->Form->input(’password’); //password echo $this->Form->input(’approved’); //day, month, year, hour, minute, //meridian echo $this->Form->input(’quote’); //textarea echo $this->Form->end(’Add’); 406 Chapter 9. Core Libraries
- 413. CakePHP Cookbook Documentation,Release 2.x A more extensive example showing some options for a date field: echo $this->Form->input(’birth_dt’, array( ’label’ => ’Date of birth’, ’dateFormat’ => ’DMY’, ’minYear’ => date(’Y’) - 70, ’maxYear’ => date(’Y’) - 18, )); Besides the specific options for input() found below, you can specify any option for the in- put 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 vari- able (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 field while using a belongsTo - or hasOne - Relation, you can add the following to your Users-controller (assuming your User belongsTo Group): $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(’list’) ); Note: Try to avoid using FormHelper::input() to generate submit buttons. Use FormHelper::submit() instead. FormHelper::inputs(mixed $fields = null, array $blacklist = null, $options = array()) Generate a set of inputs for $fields. If $fields is null all fields, except of those defined in $blacklist, of the current model will be used. In addition to controller fields output, $fields can be used to control legend and fieldset render- ing 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.: General Purpose 407
- 414. CakePHP Cookbook Documentation,Release 2.x echo $this->Form->inputs(array( ’name’ => array(’label’ => ’custom label’) )); In addition to fields control, inputs() allows you to use a few additional options. •fieldset Set to false to disable the fieldset. If a string is supplied it will be used as the class name for the fieldset 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 field name with the form helper methods, it’ll 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.fieldname as the first parameter: echo $this->Form->input(’Modelname.fieldname’); If you need to specify multiple fields using the same field name, thus creating an array that can be saved in one shot with saveAll(), use the following convention: 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 field-suffixes internally for datetime input creation. If you are using fields 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 specific to FormHelper::input(). 408 Chapter 9. Core Libraries
- 415. CakePHP Cookbook Documentation,Release 2.x • $options[’type’] You can force the type of an input, overriding model introspection, by spec- ifying a type. In addition to the field types found in the Creating form elements, you can also create ‘file’, ‘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 input’s containing div. Using a string value will set the div’s class name. An array will set the div’s attributes to those specified by the array’s 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: <div class="class_name"> <label for="UserName">Name</label> <input name="data[User][name]" type="text" value="" id="UserName" /> </div> 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: General Purpose 409
- 416. CakePHP Cookbook Documentation,Release 2.x 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> 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 & field classes set the error key to false: 410 Chapter 9. Core Libraries
- 417. CakePHP Cookbook Documentation,Release 2.x $this->Form->input(’Model.field’, array(’error’ => false)); To disable only the error message, but retain the field 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 • $options[’before’], $options[’between’], $options[’separator’], and $options[’after’] 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> General Purpose 411
- 418. CakePHP Cookbook Documentation,Release 2.x 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 by 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 find yourself repeating the same options in multiple in- put() calls, you can use inputDefaults‘ to keep your code dry: 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 specific types of inputs In addition to the generic input() method, FormHelper has specific methods for generating a number of different types of inputs. These can be used to generate just 412 Chapter 9. Core Libraries
- 419. CakePHP Cookbook Documentation,Release 2.x 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 class name 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 field. The value is used if the data passed to the form does not contain a value for the field (or if no data is passed at all). Example usage: echo $this->Form->input(’ingredient’, array(’default’ => ’Sugar’)); Example with select field (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 fields’ default values can be set by using the ‘selected’ key. Beware of using false to assign a default value. A false value is used to disable/exclude options of an input field, 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’ )); General Purpose 413
- 420. CakePHP Cookbook Documentation,Release 2.x 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 field to blank, use ‘value’ => ‘’ instead. Options can also supplied as key-value pairs. • $options[’hiddenField’] For certain input types (checkboxes, radios) a hidden input is cre- ated so that the key in $this->request->data will exist even without a value specified: <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 first. If the hidden input is on the page in multiple places, only the last group of input’s values will be saved In this example, only the tertiary colors would be passed, and the primary colors would be overridden: 414 Chapter 9. Core Libraries
- 421. CakePHP Cookbook Documentation,Release 2.x <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 field 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 in the order defined by the dateFormat option. • $options[’minYear’], $options[’maxYear’] Used in combination with a date/datetime input. Defines the lower and/or upper end of values shown in the years select field. • $options[’orderYear’] Used in combination with a date/datetime input. Defines the order in which the year values will be set. Valid values include ‘asc’, ‘desc’. The default value is ‘desc’. • $options[’interval’] This option specifies the number of minutes between each option in the minutes select box: General Purpose 415
- 422. CakePHP Cookbook Documentation,Release 2.x 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-Specific Methods All elements are created under a form for the User model as in the examples above. For this reason, the HTML code generated will contain attributes that reference to the User model. Ex: name=data[User][username], id=UserUsername FormHelper::label(string $fieldName, string $text, array $options) Create a label element. $fieldName is used for generating the DOM id. If $text is undefined, $fieldName will be used to inflect the label’s 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 class name: 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 specific 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’)); Will output: <input name="data[User][username]" type="text" class="users" id="UserUsername" /> FormHelper::password(string $fieldName, array $options) Creates a password field.: 416 Chapter 9. Core Libraries
- 423. CakePHP Cookbook Documentation,Release 2.x echo $this->Form->password(’password’); Will output: <input name="data[User][password]" value="" id="UserPassword" type="password" /> FormHelper::hidden(string $fieldName, array $options) Creates a hidden form input. Example: echo $this->Form->hidden(’id’); Will output: <input name="data[User][id]" id="UserId" type="hidden" /> If the form is edited (that is, the array $this->request->data will contain the information saved for the User model), the value corresponding to id field will automatically be added to the HTML generated. Example for data[User][id] = 10: <input name="data[User][id]" id="UserId" type="hidden" /> Changed in version 2.0: Hidden fields no longer remove the class attribute. This means that if there are validation errors on hidden fields, the error-field class name will be applied. FormHelper::textarea(string $fieldName, array $options) Creates a textarea input field.: echo $this->Form->textarea(’notes’); Will output: <textarea name="data[User][notes]" id="UserNotes"></textarea> If the form is edited (that is, the array $this->request->data will contain the information saved for the User model), the value corresponding to notes field will automatically be added to the HTML generated. Example: <textarea name="data[User][notes]" id="UserNotes"> This text is to be edited. </textarea> Note: The textarea input type allows for the $options attribute of ’escape’ which deter- mines 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 General Purpose 417
- 424. CakePHP Cookbook Documentation,Release 2.x In addition to the Common options, textarea() supports a few specific 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: <textarea name="data[Form][textarea]" cols="5" rows="5" id="FormTextarea"> </textarea> FormHelper::checkbox(string $fieldName, array $options) Creates a checkbox form element. This method also generates an associated hidden form input to force the submission of data for the specified field.: 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 don’t 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 $fieldName, 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 first element. •$attributes[’disabled’] Setting this to true or ’disabled’ will disable all of the generated radio buttons. 418 Chapter 9. Core Libraries
- 425. CakePHP Cookbook Documentation,Release 2.x •$attributes[’legend’] Radio elements are wrapped with a legend and fieldset by de- fault. 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: <input name="data[User][gender]" id="UserGender_" value="" type="hidden" /> <input name="data[User][gender]" id="UserGenderM" value="M" type="radio" /> <label for="UserGenderM">Male</label> <input name="data[User][gender]" id="UserGenderF" value="F" type="radio" /> <label for="UserGenderF">Female</label> If for some reason you don’t 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 $fieldName, array $options, array $attributes) Creates a select element, populated with the items in $options, with the option specified by $attributes[’value’] shown as selected by default. Set the ‘empty’ key in the $attributes variable to false 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 specified 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: General Purpose 419
- 426. CakePHP Cookbook Documentation,Release 2.x <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’, ’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 fieldsets: $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: 420 Chapter 9. Core Libraries
- 427. CakePHP Cookbook Documentation,Release 2.x 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’ )); 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="checkbox"> <label for="ModelField1">Label 1</label> </div> <div class="checkbox"> <input name="data[Model][field][]" value="Value 2" id="ModelField2" type="checkbox"> <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" General Purpose 421
- 428. CakePHP Cookbook Documentation,Release 2.x value="Value 1" id="ModelField1" type="checkbox"> <label for="ModelField1">Label 1</label> </div> <div class="checkbox"> <input name="data[Model][field][]" value="Value 2" id="ModelField2" type="checkbox"> <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 $fieldName, array $options) To add a file upload field to a form, you must first 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 file: 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 fields of type ‘file’. Each time the form is displayed, the value inside will be empty. Upon submission, file fields 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 file fields read the PHP manual section on file uploads4. 4 http://php.net/features.file-upload 422 Chapter 9. Core Libraries
- 429. CakePHP Cookbook Documentation,Release 2.x Validating Uploads Below is an example validation method you could define in your model to validate whether a file 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 file 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"> Note: When using $this->Form->file(), remember to set the form encoding-type, by setting the type option to ‘file’ 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 specified title and a default type of “button”. Setting $options[’type’] will output one of the three possible button types: General Purpose 423
- 430. CakePHP Cookbook Documentation,Release 2.x 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 $this->Form->button(’A Button’); echo $this->Form->button(’Another Button’, array(’type’ => ’button’)); echo $this->Form->button(’Reset the Form’, array(’type’ => ’reset’)); echo $this->Form->button(’Submit Form’, array(’type’ => ’submit’)); Will output: <button type="submit">A Button</button> <button type="button">Another Button</button> <button type="reset">Reset the Form</button> <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: 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 $con- firmMessage = 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. Changed in version 2.5: The inline and block options were added. They allow buffering the generated form tag, instead of returning with the link. This helps avoiding nested form tags. Setting ’inline’ => true will add the form tag to postLink content block or you can use option block to specify a custom block. Creating date and time inputs FormHelper::dateTime($fieldName, $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. 424 Chapter 9. Core Libraries
- 431. CakePHP Cookbook Documentation,Release 2.x You can specify not to display empty values by setting “array(‘empty’ => false)” in the attributes parameter. It will also pre-select the fields with the current datetime. FormHelper::year(string $fieldName, 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> FormHelper::month(string $fieldName, 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.): General Purpose 425
- 432. CakePHP Cookbook Documentation,Release 2.x echo $this->Form->month(’mob’, array(’monthNames’ => false)); FormHelper::day(string $fieldName, 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 first option is ‘Day’), you can supply the text as the final 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 $fieldName, boolean $format24Hours, array $attributes) Creates a select element populated with the hours of the day. FormHelper::minute(string $fieldName, array $attributes) Creates a select element populated with the minutes of the hour. FormHelper::meridian(string $fieldName, array $attributes) Creates a select element populated with ‘am’ and ‘pm’. Displaying and checking errors FormHelper::error(string $fieldName, mixed $text, array $options) Shows a validation error message, specified by $text, for the given field, 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 class name for the error message FormHelper::isFieldError(string $fieldName) Returns true if the supplied $fieldName 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. 426 Chapter 9. Core Libraries
- 433. CakePHP Cookbook Documentation,Release 2.x FormHelper::tagIsInvalid() Returns false if given form field described by the current entity has no errors. Otherwise it returns the validation message. Setting Defaults for all fields 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’ // has a label element same defaults echo $this->Form->input( ’username’, array(’label’ => ’Username’) ); Working with SecurityComponent SecurityComponent offers several features that make your forms safer and more secure. By simply including the SecurityComponent in your controller, you’ll automatically benefit 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 field making it exempt from the SecurityComponent field hashing. This also allows the fields to be manipulated by JavaScript. The $name parameter should be the entity name for the input: $this->Form->unlockField(’User.id’); FormHelper::secure(array $fields = array()) Generates a hidden field with a security hash based on the fields 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 simplifies the FormHelper methods, reducing the number of arguments, and reduces the duplication that $selected created. The effected methods are: • FormHelper::select() General Purpose 427
- 434. CakePHP Cookbook Documentation,Release 2.x • 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 pa- rameters. You can override this default by supplying $options[’url’] in the second parameter of $this->Form->create() FormHelper::hidden() Hidden fields no longer remove the class attribute. This means that if there are validation errors on hidden fields, the error-field class name will be applied. 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 flexible 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 you’re getting an error informing you that it isn’t there, it’s usually due to its name being missing from a manually configured $helpers controller variable. Inserting Well-Formatted elements The most important task the HtmlHelper accomplishes is creating well formed markup. Don’t 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 428 Chapter 9. Core Libraries
- 435. CakePHP Cookbook Documentation,Release 2.x • $charset (string) – Desired character set. If null, the value of App.encoding will be used. Used to create a meta tag specifying the document’s 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: <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 file to link, or an array with multiple files • $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 file specified resides inside the /app/webroot/css directory if path doesn’t start with a ‘/’.: echo $this->Html->css(’forms’); Will output: <link rel="stylesheet" type="text/css" href="/css/forms.css" /> The first parameter can be an array to include multiple files.: 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" /> General Purpose 429
- 436. CakePHP Cookbook Documentation,Release 2.x You can include CSS files 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 file 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: .. versionchanged:: 2.4 echo $this->Html->css(‘Blog.common.css’, 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. • $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 you’d 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 translated value html text/html rss application/rss+xml atom application/atom+xml icon 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’) 430 Chapter 9. Core Libraries
- 437. CakePHP Cookbook Documentation,Release 2.x ); ?> // 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" /> <?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 first 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 translated value html4-strict HTML4 Strict html4-trans HTML4 Transitional html4-frame HTML4 Frameset html5 HTML5 xhtml-strict XHTML1 Strict xhtml-trans XHTML1 Transitional xhtml-frame XHTML1 Frameset xhtml11 XHTML1.1 General Purpose 431
- 438. CakePHP Cookbook Documentation,Release 2.x echo $this->Html->docType(); // Outputs: // <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" // "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> 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.w3.org/TR/html4/loose.dtd"> 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 definitions based on the keys and values of the array passed to the method. Especially handy if your CSS file is dynamic.: 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", 432 Chapter 9. Core Libraries
- 439. CakePHP Cookbook Documentation,Release 2.x ’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 files 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 file 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: 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 $confir- mMessage = 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’ => ’_blank’) ); Will output: <a href="/pages/home" class="button" target="_blank">Enter</a> Use ’full_base’=>true option for absolute URLs: General Purpose 433
- 440. CakePHP Cookbook Documentation,Release 2.x 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 delete this recipe?’ );"> Delete </a> 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: <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’, 434 Chapter 9. Core Libraries
- 441. CakePHP Cookbook Documentation,Release 2.x ’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. HtmlHelper::media(string|array $path, array $options) Parameters • $path (string|array) – Path to the video file, relative to the web- root/{$options[’pathPrefix’]} directory. Or an array where each item itself can be a path string or an associate array containing keys src and type. General Purpose 435
- 442. CakePHP Cookbook Documentation,Release 2.x • $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 file’s mime type. – text Text to include inside the video tag – pathPrefix Path prefix to use for relative URLs, defaults to ‘files/’ – 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=’theora, vorbis’" ) ), 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. 436 Chapter 9. Core Libraries
- 443. CakePHP Cookbook Documentation,Release 2.x • $options (array) – An array of html attributes. Returns text wrapped in a specified tag. If no text is specified 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 class name 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 first parameter specifies 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 specified, 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 class name for the paragraph. • $text (string) – The content inside the paragraph. • $options (array) – An array of html attributes. General Purpose 437
- 444. 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 file, or an array of strings for multiple files. • $options (array) – An array of html attributes. Include a script file(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 file inclusion assumes that the JavaScript file specified 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 files with absolute paths as well to link files 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 first parameter can be an array to include multiple files.: 438 Chapter 9. Core Libraries
- 445. 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 specific 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 files 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 file 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 defined 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: General Purpose 439
- 446. 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 = ar- ray(), 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) 440 Chapter 9. Core Libraries
- 447. 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 General Purpose 441
- 448. CakePHP Cookbook Documentation,Release 2.x • $data (array) – A two dimensional array with data for the rows. • $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 specific <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’) ), ’Yes’), 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> 442 Chapter 9. Core Libraries
- 449. CakePHP Cookbook Documentation,Release 2.x <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. • $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 a 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" )); General Purpose 443
- 450. CakePHP Cookbook Documentation,Release 2.x // 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" )); // Output /posts/search?foo=bar#first For further information check Router::url5 in the API. HtmlHelper::useTag(string $tag) Returns a formatted existent block of $tag: 5 http://api.cakephp.org/2.4/class-Router.html#_url 444 Chapter 9. Core Libraries
- 451. CakePHP Cookbook Documentation,Release 2.x $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 $configFile, 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 config file containing the tags you’d 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|array|bool $startText = false) CakePHP has the built-in ability to automatically create a breadcrumb trail in your app. To set this up, first 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 first link: 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 you’ll want to add the following to start the breadcrumb trails on each of the pages: General Purpose 445
- 452. CakePHP Cookbook Documentation,Release 2.x $this->Html->addCrumb(’Users’, ’/users’); $this->Html->addCrumb(’Add User’, array(’controller’ => ’users’, ’action’ => ’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’, ‘firstClass’, ‘lastClass’ and ‘escape’ 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 first breadcrumb link/text. This is useful when you al- ways 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’, ‘firstClass’ and ‘lastClass’ options were added. Changed in version 2.5: The ‘escape’ option was added. JsHelper class JsHelper(View $view, array $settings = array()) Warning: The JsHelper is currently deprecated and completely removed in 3.x. We recommend using regular JavaScript and directly interacting with JavaScript libraries where possible. Since the beginning CakePHP’s support for JavaScript has been with Prototype/Scriptaculous. While we still think these are excellent JavaScript libraries, 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. 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 flexibility they need to address their specific application needs. JavaScript Engines form the backbone of the new JsHelper. A JavaScript engine translates an abstract JavaScript element into concrete JavaScript code specific to the JavaScript library being used. In addition they create an extensible system for others to use. Using a specific 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: 446 Chapter 9. Core Libraries
- 453. CakePHP Cookbook Documentation,Release 2.x echo $this->Html->script(’jquery’); // Include jQuery library Replace jquery with the name of your library file (.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 specific 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 shouldn’t 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 cus- tomHelper: public $helpers = array(’Js’); Note: It is not possible to declare a JavaScript engine inside a custom helper. Doing that will have no effect. 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’ ); General Purpose 447
- 454. CakePHP Cookbook Documentation,Release 2.x Warning: Be sure to declare the JsHelper and its engine on top of the $helpers array in your controller. 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 fit your JavaScript library. Creating a JavaScript Engine JavaScript engine helpers follow normal helper conventions, with a few additional restrictions. They must have the Engine suffix. 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 through- out 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 JavaScript libraries can change, a common set of options is supported by JsHelper, these common options will be mapped out to the library specific options 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 448 Chapter 9. Core Libraries
- 455. CakePHP Cookbook Documentation,Release 2.x place $this->Js->writeBuffer() at the bottom of your layout file 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 files. JsHelper::writeBuffer($options = array()) Writes all JavaScript generated so far to a code block or caches them to a file 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 file 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 file 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 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. General Purpose 449
- 456. CakePHP Cookbook Documentation,Release 2.x 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 specific options. This is done to provide end developers with as unified 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 final position. •opacity - Opacity of the placeholder •distance - Distance a sortable must be dragged before sorting starts. Event Options •start - Event fired when sorting starts •sort - Event fired during sorting •complete - Event fired 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’, 450 Chapter 9. Core Libraries
- 457. CakePHP Cookbook Documentation,Release 2.x ’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, stop:onStop }); JsHelper::request($url, $options = array()) Generate a JavaScript snippet to create an XmlHttpRequest or ‘AJAX’ request. Event Options •complete - Callback to fire on complete. •success - Callback to fire on success. •before - Callback to fire on request initialization. •error - Callback to fire 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 eval’ed. •dataExpression - Should the data key be treated as a callback. Useful for supplying $options[’data’] as another JavaScript expression. Example use: $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 General Purpose 451
- 458. CakePHP Cookbook Documentation,Release 2.x 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 fired when the drag starts •drag - Event fired on every step of the drag •stop - Event fired 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 $("#element").draggable({ containment:"#content", drag:onDrag, grid:[10,10], start:onStart, stop:onStop }); JsHelper::drop($options = array()) Make an element accept draggable elements and act as a dropzone for dragged elements. Options 452 Chapter 9. Core Libraries
- 459. CakePHP Cookbook Documentation,Release 2.x •accept - Selector for elements this droppable will accept. •hoverclass - Class to add to droppable when a draggable is over. Event Options •drop - Event fired when an element is dropped into the drop zone. •hover - Event fired when a drag enters a drop zone. •leave - Event fired 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 imple- mentation 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. Events General Purpose 453
- 460. CakePHP Cookbook Documentation,Release 2.x •change - Fired when the slider’s 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:onComplete, value:2 }); 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’); 454 Chapter 9. Core Libraries
- 461. CakePHP Cookbook Documentation,Release 2.x // $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 event type if your library supports them. $content should contain the function body for the call- back. 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: General Purpose 455
- 462. CakePHP Cookbook Documentation,Release 2.x $(’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.: $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 files. 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 - Confirm message displayed before sending the request. Using confirm, 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 both FormHelper::submit() and JsHelper::request() when using submit. 456 Chapter 9. Core Libraries
- 463. CakePHP Cookbook Documentation,Release 2.x 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. Options •confirm - Generate a confirm() 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: <a href="/posts/index/page:2" other="value">Page 2</a> 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. General Purpose 457
- 464. CakePHP Cookbook Documentation,Release 2.x 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. 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 we’ll 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, call the options() at the top of your view: $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 file. 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 don’t 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’); ?> 458 Chapter 9. Core Libraries
- 465. CakePHP Cookbook Documentation,Release 2.x //more stuff here. </head> <body> <div id="content"> <?php echo $this->fetch(’content’); ?> </div> <?php echo $this->Html->image( ’indicator.gif’, array(’id’ => ’busy-indicator’) ); ?> </body> </html> Remember to place the indicator.gif file 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 file. With the above layout, we’ve included an indicator image file, 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’ => false) ), )); 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 convenient methods that enable display numbers in common formats in your views. These methods include ways to format currency, percentages, data sizes, format numbers to specific precisions and also to give you more flexibility 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. General Purpose 459
- 466. CakePHP Cookbook Documentation,Release 2.x NumberHelper::currency(mixed $number, string $currency = ‘USD’, array $options = ar- ray()) Parameters • $number (float) – 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 first parameter, $number, should be a floating point number that represents the amount of money you are expressing. The second parameter is used to choose a predefined currency formatting scheme: $currency 1234.56, formatted by currency type EUR C1.234,56 GBP £1,234.56 USD $1,234.56 The third parameter is an array of options for further defining the output. The following options are available: Option Description before The currency symbol to place before whole numbers ie. ‘$’ after The currency symbol to place after decimal numbers ie. ‘c’. Set to boolean false to use no decimal symbol. eg. 0.35 => $0.35. zero The text to use for zero values, can be a string or a number. ie. 0, ‘Free!’ places Number of decimal places to use. ie. 2 thousands Thousands separator ie. ‘,’ decimals Decimal separator symbol ie. ‘.’ negative Symbol for negative numbers. If equal to ‘()’, the number will be wrapped with ( and ) escape Should the output be htmlentity escaped? Defaults to true wholeSym- bol String to use for whole numbers ie. ‘ dollars’ wholePosi- tion Either ‘before’ or ‘after’ to place the whole symbol fraction- Symbol String to use for fraction numbers ie. ‘ cents’ fractionPo- sition Either ‘before’ or ‘after’ to place the fraction symbol fractionEx- ponent Fraction exponent of this specific currency. Defaults to 2. 460 Chapter 9. Core Libraries
- 467. CakePHP Cookbook Documentation,Release 2.x 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 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. Uses the same $options keys as CakeNumber::currency(). Add a currency format to the Number helper. Makes reusing currency formats easier: // called as NumberHelper $this->Number->addFormat(’BRL’, array(’before’ => ’R$’, ’thousands’ => ’.’, ’decimals’ // called as CakeNumber App::uses(’CakeNumber’, ’Utility’); CakeNumber::addFormat(’BRL’, array(’before’ => ’R$’, ’thousands’ => ’.’, ’decimals’ => You can now use BRL as a short form when formatting currency amounts: // called as NumberHelper echo $this->Number->currency($value, ’BRL’); // called as CakeNumber App::uses(’CakeNumber’, ’Utility’); echo CakeNumber::currency($value, ’BRL’); Added formats are merged with the following defaults: array( ’wholeSymbol’ => ’’, General Purpose 461
- 468. CakePHP Cookbook Documentation,Release 2.x ’wholePosition’ => ’before’, ’fractionSymbol’ => false, ’fractionPosition’ => ’after’, ’zero’ => 0, ’places’ => 2, ’thousands’ => ’,’, ’decimals’ => ’.’, ’negative’ => ’()’, ’escape’ => true, ’fractionExponent’ => 2 ) NumberHelper::precision(mixed $number, int $precision = 3) Parameters • $number (float) – The value to covert • $precision (integer) – The number of decimal places to display This method displays a number with the specified amount of precision (decimal places). It will round in order to maintain the level of precision defined.: // called as NumberHelper echo $this->Number->precision(456.91873645, 2); // 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 = ar- ray()) Parameters • $number (float) – The value to covert. • $precision (integer) – The number of decimal places to display. • $options (array) – Options, see below. Option Description multi- ply 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% 462 Chapter 9. Core Libraries
- 469. CakePHP Cookbook Documentation,Release 2.x 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. 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 $op- tions supplied, the number 1236.334 would output as 1,236. Note that the default precision is zero General Purpose 463
- 470. CakePHP Cookbook Documentation,Release 2.x 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’ => ’.’, ’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 $op- tions 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 464 Chapter 9. Core Libraries
- 471. CakePHP Cookbook Documentation,Release 2.x •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’ => ’.’, ’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 inflection. • $options (array) – Options for sorting link. General Purpose 465
- 472. CakePHP Cookbook Documentation,Release 2.x Generates a sorting link. Sets named or querystring parameters for the sort and direction. Links will default to sorting by asc. After the first click, links generated with sort() will handle direction switching auto- matically. Link sorting default by ‘asc’. If the resultset is sorted ‘asc’ by the specified 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(). • direction The default direction to use when this link isn’t active. • lock Lock direction. Will only use the default direction then, defaults to false. New in version 2.5: You can now set the lock option to true in order to lock the sorting direction into the specified direction. 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: 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 automat- ically switch directions like normal: echo $this->Paginator->sort(’user_id’, null, array(’direction’ => ’desc’)); Output: 466 Chapter 9. Core Libraries
- 473. CakePHP Cookbook Documentation,Release 2.x <a href="/posts/index/page:1/sort:user_id/direction:desc/">User Id</a> The lock option can be used to lock sorting into the specified direction: echo $this->Paginator->sort(’user_id’, null, array(’direction’ => ’asc’, ’lock’ => true)); 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 first links generated, set to an integer to define the number of ‘first’ links to generate. Defaults to false. If a string is set a link to the first page will be generated with the value as the title: echo $this->Paginator->numbers(array(’first’ => ’First page’)); • last Whether you want last links generated, set to an integer to define 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 class name used on the wrapping tag. • currentClass The class name 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.: General Purpose 467
- 474. CakePHP Cookbook Documentation,Release 2.x echo $this->Paginator->numbers(); Using the first 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 first 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 specific page numbers, you’ll often want links that go to the previous and next links, first 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 you’re already on the first 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. •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’ => ’prev disabled’) ); 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"> << previous </a> </span> 468 Chapter 9. Core Libraries
- 475. CakePHP Cookbook Documentation,Release 2.x If there were no previous pages you would get: <span class="prev disabled"><< previous</span> 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"> previous </a> </li> 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 </a> 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, $dis- abledOptions = 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($first = ‘<< first’, $options = array()) Returns a first or set of numbers for the first pages. If a string is given, then only a link to the first page with the provided text will be created: echo $this->Paginator->first(’< first’); The above creates a single link for the first page. Will output nothing if you are on the first page. You can also use an integer to indicate how many first paging links you want generated: echo $this->Paginator->first(3); The above will create links for the first 3 pages, once you get to the third or greater page. Prior to that nothing will be output. The options parameter accepts the following: •tag The tag wrapping tag you want to use, defaults to ‘span’ General Purpose 469
- 476. CakePHP Cookbook Documentation,Release 2.x •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 first 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 specific 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 first record being displayed. – {:end} - number of the last record being displayed. – {: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: 470 Chapter 9. Core Libraries
- 477. CakePHP Cookbook Documentation,Release 2.x 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’ ) )); The above adds the en route parameter to all links the helper will generate. It will also create links with specific sort, direction and page values. By default PaginatorHelper will merge in all of the current pass and named parameters. So you don’t have to do that in each view file. • escape Defines if the title field for links should be HTML escaped. Defaults to true. General Purpose 471
- 478. CakePHP Cookbook Documentation,Release 2.x • update The CSS selector of the element to update with the results of AJAX pagination calls. If not specified, 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 being paginated, defaults to PaginatorHelper::defaultModel(). 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 configuration 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’) )); Configuring the PaginatorHelper to use a JavaScript helper By default the PaginatorHelper uses JsHelper to do AJAX features. However, if you don’t 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 It’s 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 doesn’t always need to be restricted as such. See the details on PaginatorHelper6 in the API. As mentioned, the PaginatorHelper also offers sorting fea- tures which can be easily integrated into your table column headers: // app/View/Posts/index.ctp <table> <tr> <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> 6 http://api.cakephp.org/2.4/class-PaginatorHelper.html 472 Chapter 9. Core Libraries
- 479. CakePHP Cookbook Documentation,Release 2.x <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 field. 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 final 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}’ )); General Purpose 473
- 480. CakePHP Cookbook Documentation,Release 2.x Other Methods PaginatorHelper::link($title, $url = array(), $options = array()) 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 Would create a link pointing at ‘/posts/index/page:5/sort:title/direction:desc’ 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 474 Chapter 9. Core Libraries
- 481. CakePHP Cookbook Documentation,Release 2.x [order] => [limit] => 20 [options] => Array ( [page] => 2 [conditions] => Array ( ) ) [paramType] => named ) */ PaginatorHelper::param(string $key, string $model = null) Gets the specific 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 we’ve 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, first we need to edit the controller to add in the rss-specific code. Controller Code It is a good idea to add RequestHandler to your PostsController’s $components array. This will allow a lot of automagic to occur: public $components = array(’RequestHandler’); Our view will also use the TextHelper for formatting, so that should be added to the controller as well: General Purpose 475
- 482. CakePHP Cookbook Documentation,Release 2.x 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 DESC’) ); return $this->set(compact(’posts’)); } // this is not an Rss request, so deliver // data used by website’s 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, put the following contents in app/View/Layouts/rss/default.ctp: if (!isset($documentData)) { $documentData = array(); } if (!isset($channelData)) { $channelData = array(); } if (!isset($channelData[’title’])) { $channelData[’title’] = $this->fetch(’title’); } $channel = $this->Rss->channel(array(), $channelData, $this->fetch(’content’)); echo $this->Rss->document($documentData, $channel); It doesn’t look like much but thanks to the power in the RssHelper it’s doing a lot of lifting for us. We haven’t set $documentData or $channelData in the controller, however in CakePHP your views can 476 Chapter 9. Core Libraries
- 483. CakePHP Cookbook Documentation,Release 2.x pass variables back to the layout. Which is where our $channelData array will come from setting all of the meta data for our feed. Next up is view file for my posts/index. Much like the layout file we created, we need to create a View/Posts/rss/ directory and create a new index.ctp inside that folder. The contents of the file 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 Con- troller::set() method. Here though we are passing the channel’s 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 ar- ray 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, )); General Purpose 477
- 484. CakePHP Cookbook Documentation,Release 2.x echo $this->Rss->item(array(), array( ’title’ => $post[’Post’][’title’], ’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 filter 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 configuration 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 field 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. 478 Chapter 9. Core Libraries
- 485. 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 $end- Tag = 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 component’s 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 in- dicating the nested array. This notation is used for all Session helper methods wherever a $key is used. SessionHelper::read(string $key) Return type mixed General Purpose 479
- 486. CakePHP Cookbook Documentation,Release 2.x 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 whether a key is in the Session. Returns a boolean representing the key’s existence. SessionHelper::error() Return type string Returns last error encountered in a session. SessionHelper::valid() Return type boolean Used to check whether a session is valid in a view. Displaying notifications or flash messages SessionHelper::flash(string $key = ‘flash’, array $params = array()) Return type string As explained in Creating notification messages, you can create one-time notifications 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 the 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. The failure element would contain something like this: <div class="flash flash-failure"> <?php echo h($message); ?> </div> 480 Chapter 9. Core Libraries
- 487. CakePHP Cookbook Documentation,Release 2.x You can also pass additional parameters into the flash() method, which allows 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 escape the HTML in flash messages. If you are using any request or user data in your flash messages, you should escape it with h when formatting your mes- sages. 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 gracefully truncating long stretches of text. Changed in version 2.1: Several TextHelper methods have been moved into the String class to allow easier use outside of the View layer. Within a view, these methods are accessible via the TextHelper class. You can call one 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 defined in $htmlOptions (see HtmlHelper::link()).: $myText = ’For more information regarding our world-famous ’ . ’pastries and desserts, contact [email protected]’; $linkedText = $this->Text->autoLinkEmails($myText); Output: 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. General Purpose 481
- 488. CakePHP Cookbook Documentation,Release 2.x 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 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: As of 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 are found, 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. • $needle (string) – The string to find. • $options (array) – An array of options, see below. 482 Chapter 9. Core Libraries
- 489. CakePHP Cookbook Documentation,Release 2.x Highlights $needle in $haystack using the $options[’format’] string specified or a de- fault 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="highlight">1</span>’) ); // called as String App::uses(’String’, ’Utility’); echo String::highlight( $lastSentence, ’using’, array(’format’ => ’<span class="highlight">1</span>’) ); 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, in characters, beyond which the text should be trun- cated. • $options (array) – An array of options to use. If $text is longer than $length characters, this method truncates it at $length and adds a prefix consisting of ’ellipsis’, if defined. If ’exact’ is passed as false, the truncation will occur at the first whitespace after the point at which $length is exceeded. 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, General Purpose 483
- 490. CakePHP Cookbook Documentation,Release 2.x ’html’ => false ) Example: // called as TextHelper echo $this->Text->truncate( ’The killer crept forward and tripped on the rug.’, 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, in characters, beyond which the text should be trun- cated. • $options (array) – An array of options to use. If $text is longer than $length characters, this method removes an initial substring with length consisting of the difference and prepends a suffix consisting of ’ellipsis’, if defined. If ’exact’ is passed as false, the truncation will occur at the first whitespace prior to the point at which truncation would otherwise take place. $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 ) 484 Chapter 9. Core Libraries
- 491. CakePHP Cookbook Documentation,Release 2.x New in version 2.3. Example: $sampleText = ’I packed my bag and in it I put a PSP, a PS3, a TV, ’ . ’a C# program that can divide by zero, death metal t-shirts’ // called as TextHelper echo $this->Text->tail( $sampleText, 70, array( ’ellipsis’ => ’...’, ’exact’ => false ) ); // called as String App::uses(’String’, ’Utility’); echo String::tail( $sampleText, 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 $ellip- sis=”...”) 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 prefix/suffix 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, ’...’); General Purpose 485
- 492. CakePHP Cookbook Documentation,Release 2.x 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’.: // 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 user’s 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. Un- comment the line date_default_timezone_set(’UTC’); in app/Config/core.php to en- sure your application’s time zone is set to GMT+0. Next add a time zone field to your users table and make the necessary modifications 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 h:i A’, $post[’Post’][’created’], null, 486 Chapter 9. Core Libraries
- 493. CakePHP Cookbook Documentation,Release 2.x $user[’User’][’time_zone’] ); // Will display August 22nd, 2011 11:53 PM for a user in GMT+0 // August 22nd, 2011 03:53 PM for a user in GMT-8 // and August 23rd, 2011 09:53 AM GMT+10 Most of the Time Helper methods have a $timezone parameter. The $timezone parameter accepts a valid timezone identifier string or an instance of DateTimeZone class. Formatting TimeHelper::convert($serverTime, $timezone = NULL) Return type integer Converts given time (in server’s time zone) to user’s 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, $field_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, $fieldName, $timezone = NULL) General Purpose 487
- 494. CakePHP Cookbook Documentation,Release 2.x Return type string Returns a string in the format “($field_name >= ‘2008-01-21 00:00:00’) AND ($field_name <= ‘2008- 01-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. TimeHelper::format($date, $format = NULL, $default = false, $timezone = NULL) Return type string Will return a string formatted to the given format using the PHP strftime() formatting options7: // called via TimeHelper echo $this->Time->format(’2011-08-22 11:53:00’, ’%B %e, %Y %H:%M %p’); // August 22, 2011 11:53 AM echo $this->Time->format(’+2 days’, ’%c’); // 2 days from now formatted as Sun, 13 Nov 2011 03:36:10 AM EET // called as CakeTime App::uses(’CakeTime’, ’Utility’); echo CakeTime::format(’2011-08-22 11:53:00’, ’%B %e, %Y %H:%M %p’); echo CakeTime::format(’+2 days’, ’%c’); You can also provide the date/time as the first 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 be- low. $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. 7 http://www.php.net/manual/en/function.strftime.php 488 Chapter 9. Core Libraries
- 495. CakePHP Cookbook Documentation,Release 2.x TimeHelper::fromString($dateString, $timezone = NULL) Return type string Takes a string and uses strtotime8 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’); 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 file is used. For more info about LC_TIME file 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: 8 http://us.php.net/manual/en/function.date.php General Purpose 489
- 496. CakePHP Cookbook Documentation,Release 2.x // 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’); 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 server’s offset from GMT in seconds. TimeHelper::timeAgoInWords($dateString, $options = array()) Return type string Will take a datetime string (anything that is parsable by PHP’s strtotime() function or MySQL’s date- time 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 // on August 22nd, 2011 echo $this->Time->timeAgoInWords( ’Aug 22, 2011’, array(’format’ => ’F jS, Y’) ); // called as CakeTime App::uses(’CakeTime’, ’Utility’); echo CakeTime::timeAgoInWords(’Aug 22, 2011’); echo CakeTime::timeAgoInWords( ’Aug 22, 2011’, 490 Chapter 9. Core Libraries
- 497. CakePHP Cookbook Documentation,Release 2.x 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’ => ’+1 year’) ); // 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’ => ’+1 year’) ); 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: $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); General Purpose 491
- 498. CakePHP Cookbook Documentation,Release 2.x /* 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 server’s timezone. TimeHelper::timezone($timezone = NULL) Return type DateTimeZone New in version 2.2: Returns a timezone object from a string or the user’s timezone object. If the function is called without a parameter it tries to get timezone from ‘Config.timezone’ configuration variable. TimeHelper::listTimezones($filter = null, $country = null, $group = true) Return type array 492 Chapter 9. Core Libraries
- 499. CakePHP Cookbook Documentation,Release 2.x New in version 2.2: Returns a list of timezone identifiers. 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 Configuring 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 controller’s $helpers array: 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’); } General Purpose 493
- 500. CakePHP Cookbook Documentation,Release 2.x You can also add helpers from within an action, so they will only be available to that action and not to the other actions in the controller. This saves processing power for the other actions that do not use the helper and helps 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 it 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( ’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 494 Chapter 9. Core Libraries
- 501. CakePHP Cookbook Documentation,Release 2.x } 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 configure your helpers and keep configuration logic out of your controller actions. If you have configuration options that cannot be included as part of a class declaration, you can set those in your controller’s beforeRender callback: class PostsController extends AppController { public function beforeRender() { parent::beforeRender(); $this->helpers[’CustomStuff’] = $this->_getCustomStuffSettings(); } } Using Helpers Once you’ve configured 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 view’s 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 pro- cess. See the Helper API and the Collections documentation for more information. Creating Helpers If a core helper (or one showcased on GitHub or in the Bakery) doesn’t fit your needs, helpers are easy to create. Let’s say we wanted to create a helper that could be used to output a specifically crafted CSS-styled link you needed many different places in your application. In order to fit your logic into CakePHP’s existing helper structure, you’ll need to create a new class in /app/View/Helper. Let’s call our helper LinkHelper. The actual PHP class file 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... General Purpose 495
- 502. CakePHP Cookbook Documentation,Release 2.x } } 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 you’ve created your helper and placed it in /app/View/Helper/, you’ll be able to include it in your controllers using the special variable $helpers: 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: <!-- make a link using the new 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() { } } 496 Chapter 9. Core Libraries
- 503. CakePHP Cookbook Documentation,Release 2.x Helper API class Helper The base class for Helpers. It provides a number of utility methods and features for loading other helpers. Helper::webroot($file) Resolve a file name to the webroot of the application. If a theme is active and the file exists in the current theme’s webroot, the path to the themed file will be returned. Helper::url($url, $full = false) Generates an HTML escaped URL, delegates to Router::url(). Helper::value($options = array(), $field = 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 field. 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 file is rendered. This includes elements, views, parent views and layouts. Helper::afterRenderFile($viewFile, $content) Is called after each view file 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 controller’s beforeRender method but before the con- troller renders view and layout. Receives the file 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 filename as an argument. Helper::afterLayout($layoutFile) Is called after layout rendering is complete. Receives the layout filename as an argument. Collections Components, Helpers, Behaviors and Tasks all share a similar structure and set of behaviors. For 2.0, they were given a unified API for interacting with collections of similar objects. The collection objects in CakePHP, give you a uniform way to interact with several different kinds of objects in your application. While the examples below, will use Components, the same behavior can be expected for Helpers, Behaviors, and Tasks in addition to Components. General Purpose 497
- 504. CakePHP Cookbook Documentation,Release 2.x Loading and unloading objects Loading objects on every kind of collection can be done using the load() method: $this->Prg = $this->Components->load(’Prg’); $this->Prg->process(); When loading a component, if the component is not currently loaded into the collection, a new instance will be created. If the component is already loaded, another instance will not be created. When loading components, you can also provide additional configuration for them: $this->Cookie = $this->Components->load(’Cookie’, array(’name’ => ’sweet’)); Any keys & values provided will be passed to the Component’s constructor. The one exception to this rule is className. ClassName is a special key that is used to alias objects in a collection. This allows you to have component names that do not reflect the classnames, which can be helpful when extending core components: $this->Auth = $this->Components->load( ’Auth’, array(’className’ => ’MyCustomAuth’) ); $this->Auth->user(); // Actually using MyCustomAuth::user(); The inverse of loading an object, is unloading it. Unloaded objects are removed from memory, and will not have additional callbacks triggered on them: $this->Components->unload(’Cookie’); $this->Cookie->read(); // Fatal error. Triggering callbacks Callbacks are supported by collection objects. When a collection has a callback triggered, that method will be called on all enabled objects in the collection. You can pass parameters to the callback loop as well: $this->Behaviors->trigger(’afterFind’, array($this, $results, $primary)); In the above $this would be passed as the first argument to every behavior’s afterFind method. There are several options that can be used to control how callbacks are fired: • breakOn Set to the value or values you want the callback propagation to stop on. Can either be a scalar value, or an array of values to break on. Defaults to false. • break Set to true to enabled breaking. When a trigger is broken, the last returned value will be re- turned. If used in combination with collectReturn the collected results will be returned. Defaults to false. • collectReturn Set to true to collect the return of each object into an array. This array of return values will be returned from the trigger() call. Defaults to false. • triggerDisabled Will trigger the callback on all objects in the collection even the non-enabled objects. Defaults to false. 498 Chapter 9. Core Libraries
- 505. CakePHP Cookbook Documentation,Release 2.x • modParams Allows each object the callback gets called on to modify the parameters to the next object. Setting modParams to an integer value will allow you to modify the parameter with that index. Any non-null value will modify the parameter index indicated. Defaults to false. Canceling a callback loop Using the break and breakOn options you can cancel a callback loop midway similar to stopping event propagation in JavaScript: $this->Behaviors->trigger( ’beforeFind’, array($this, $query), array(’break’ => true, ’breakOn’ => false) ); In the above example, if any behavior returns false from its beforeFind method, no further callbacks will be called. In addition, the return of trigger() will be false. Enabling and disabling objects Once an object is loaded into a collection you may need to disable it. Disabling an object in a collection prevents future callbacks from being fired on that object unless the triggerDisabled option is used: // Disable the HtmlHelper $this->Helpers->disable(’Html’); // Re-enable the helper later on $this->Helpers->enable(’Html’); Disabled objects can still have their normal methods and properties used. The primary difference between an enabled and disabled object is with regards to callbacks. You can interrogate a collection about the enabled objects, or check if a specific object is still enabled using enabled(): // Check whether or not a specific helper is enabled. $this->Helpers->enabled(’Html’); // $enabled will contain an array of helper currently enabled. $enabled = $this->Helpers->enabled(); Object callback priorities You can prioritize the triggering object callbacks similar to event callbacks. The handling of priority values and order of triggering is the same as explained here. Here’s how you can specify priority at declaration time: class SomeController { public $components = array( ’Foo’, //Foo gets default priority 10 // Bar’s callbacks are triggered before Foo’s ’Bar’ => array(’priority’ => 9) ); General Purpose 499
- 506. CakePHP Cookbook Documentation,Release 2.x public $helpers = array( // Cache’s callbacks will be triggered last ’Cache’ => array(’priority’ => 12), ’Asset’, ’Utility’ //Utility has priority 10 same as Asset and its callbacks //are triggered after Asset’s ); } class Post { public $actsAs = array( ’DoFirst’ => array(’priority’ => 1), ’Media’ ); } When dynamically loading objects to a collection you can specify the priority like this: $this->MyComponent = $this->Components->load( ’MyComponent’, array(’priority’ => 9) ); You can also change priorities at run time using the ObjectCollection::setPriority() function: //For a single object $this->Components->setPriority(’Foo’, 2); //For multiple objects $this->Behaviors->setPriority(array(’Object1’ => 8, ’Object2’ => 9)); Behaviors Behaviors add extra functionality to your models. CakePHP comes with a number of built-in behaviors such as TreeBehavior and ContainableBehavior. To learn about creating and using behaviors, read the section on Behaviors. Behaviors Behaviors add extra functionality to your models. CakePHP comes with a number of built-in behaviors such as TreeBehavior and ContainableBehavior. To learn about creating and using behaviors, read the section on Behaviors. ACL class AclBehavior 500 Chapter 9. Core Libraries
- 507. CakePHP Cookbook Documentation,Release 2.x The Acl behavior provides a way to seamlessly integrate a model with your ACL system. It can create both AROs or ACOs transparently. To use the new behavior, you can add it to the $actsAs property of your model. When adding it to the actsAs array you choose to make the related Acl entry an ARO or an ACO. The default is to create ACOs: class User extends AppModel { public $actsAs = array(’Acl’ => array(’type’ => ’requester’)); } This would attach the Acl behavior in ARO mode. To join the ACL behavior in ACO mode use: class Post extends AppModel { public $actsAs = array(’Acl’ => array(’type’ => ’controlled’)); } For User and Group models it is common to have both ACO and ARO nodes, to achieve this use: class User extends AppModel { public $actsAs = array(’Acl’ => array(’type’ => ’both’)); } You can also attach the behavior on the fly like so: $this->Post->Behaviors->load(’Acl’, array(’type’ => ’controlled’)); Changed in version 2.1: You can now safely attach AclBehavior to AppModel. Aco, Aro and AclNode now extend Model instead of AppModel, which would cause an infinite loop. If your application depends on having those models to extend AppModel for some reason, then copy AclNode to your application and have it extend AppModel again. Using the AclBehavior Most of the AclBehavior works transparently on your Model’s afterSave(). However, using it requires that your Model has a parentNode() method defined. This is used by the AclBehavior to determine parent->child relationships. A model’s parentNode() method must return null or return a parent Model reference: public function parentNode() { return null; } If you want to set an ACO or ARO node as the parent for your Model, parentNode() must return the alias of the ACO or ARO node: public function parentNode() { return ’root_node’; } A more complete example. Using an example User Model, where User belongsTo Group: public function parentNode() { if (!$this->id && empty($this->data)) { return null; Behaviors 501
- 508. CakePHP Cookbook Documentation,Release 2.x } $data = $this->data; if (empty($this->data)) { $data = $this->read(); } if (!$data[’User’][’group_id’]) { return null; } else { return array(’Group’ => array(’id’ => $data[’User’][’group_id’])); } } In the above example the return is an array that looks similar to the results of a model find. It is important to have the id value set or the parentNode relation will fail. The AclBehavior uses this data to construct its tree structure. node() The AclBehavior also allows you to retrieve the Acl node associated with a model record. After setting $model->id. You can use $model->node() to retrieve the associated Acl node. You can also retrieve the Acl Node for any row, by passing in a data array: $this->User->id = 1; $node = $this->User->node(); $user = array(’User’ => array( ’id’ => 1 )); $node = $this->User->node($user); Will both return the same Acl Node information. If you had setup AclBehavior to create both ACO and ARO nodes, you need to specify which node type you want: $this->User->id = 1; $node = $this->User->node(null, ’Aro’); $user = array(’User’ => array( ’id’ => 1 )); $node = $this->User->node($user, ’Aro’); Containable class ContainableBehavior A new addition to the CakePHP 1.2 core is the ContainableBehavior. This model behavior allows you to filter and limit model find operations. Using Containable will help you cut down on needless wear 502 Chapter 9. Core Libraries
- 509. CakePHP Cookbook Documentation,Release 2.x and tear on your database, increasing the speed and overall performance of your application. The class will also help you search and filter your data for your users in a clean and consistent way. Containable allows you to streamline and simplify operations on your model bindings. It works by temporar- ily or permanently altering the associations of your models. It does this by using supplied the containments to generate a series of bindModel and unbindModel calls. Since Containable only modifies existing relationships it will not allow you to restrict results by distant associations. Instead you should refer to Joining tables. To use the new behavior, you can add it to the $actsAs property of your model: class Post extends AppModel { public $actsAs = array(’Containable’); } You can also attach the behavior on the fly: $this->Post->Behaviors->load(’Containable’); Using Containable To see how Containable works, let’s look at a few examples. First, we’ll start off with a find() call on a model named ‘Post’. Let’s say that ‘Post’ hasMany ‘Comment’, and ‘Post’ hasAndBelongsToMany ‘Tag’. The amount of data fetched in a normal find() call is rather extensive: debug($this->Post->find(’all’)); [0] => Array ( [Post] => Array ( [id] => 1 [title] => First article [content] => aaa [created] => 2008-05-18 00:00:00 ) [Comment] => Array ( [0] => Array ( [id] => 1 [post_id] => 1 [author] => Daniel [email] => [email protected] [website] => http://example.com [comment] => First comment [created] => 2008-05-18 00:00:00 ) [1] => Array ( [id] => 2 [post_id] => 1 Behaviors 503
- 510. CakePHP Cookbook Documentation,Release 2.x [author] => Sam [email] => [email protected] [website] => http://example.net [comment] => Second comment [created] => 2008-05-18 00:00:00 ) ) [Tag] => Array ( [0] => Array ( [id] => 1 [name] => Awesome ) [1] => Array ( [id] => 2 [name] => Baking ) ) ) [1] => Array ( [Post] => Array (... For some interfaces in your application, you may not need that much information from the Post model. One thing the ContainableBehavior does is help you cut down on what find() returns. For example, to get only the post-related information, you can do the following: $this->Post->contain(); $this->Post->find(’all’); You can also invoke Containable’s magic from inside the find() call: $this->Post->find(’all’, array(’contain’ => false)); Having done that, you end up with something a lot more concise: [0] => Array ( [Post] => Array ( [id] => 1 [title] => First article [content] => aaa [created] => 2008-05-18 00:00:00 ) ) [1] => Array ( [Post] => Array ( 504 Chapter 9. Core Libraries
- 511. CakePHP Cookbook Documentation,Release 2.x [id] => 2 [title] => Second article [content] => bbb [created] => 2008-05-19 00:00:00 ) ) This sort of help isn’t new: in fact, you can do that without the ContainableBehavior doing something like this: $this->Post->recursive = -1; $this->Post->find(’all’); Containable really shines when you have complex associations, and you want to pare down things that sit at the same level. The model’s $recursive property is helpful if you want to hack off an entire level of recursion, but not when you want to pick and choose what to keep at each level. Let’s see how it works by using the contain() method. The contain method’s first argument accepts the name, or an array of names, of the models to keep in the find operation. If we wanted to fetch all posts and their related tags (without any comment information), we’d try something like this: $this->Post->contain(’Tag’); $this->Post->find(’all’); Again, we can use the contain key inside a find() call: $this->Post->find(’all’, array(’contain’ => ’Tag’)); Without Containable, you’d end up needing to use the unbindModel() method of the model, multiple times if you’re paring off multiple models. Containable creates a cleaner way to accomplish this same task. Containing deeper associations Containable also goes a step deeper: you can filter the data of the associated models. If you look at the results of the original find() call, notice the author field in the Comment model. If you are interested in the posts and the names of the comment authors — and nothing else — you could do something like the following: $this->Post->contain(’Comment.author’); $this->Post->find(’all’); // or.. $this->Post->find(’all’, array(’contain’ => ’Comment.author’)); Here, we’ve told Containable to give us our post information, and just the author field of the associated Comment model. The output of the find call might look something like this: [0] => Array ( [Post] => Array Behaviors 505
- 512. CakePHP Cookbook Documentation,Release 2.x ( [id] => 1 [title] => First article [content] => aaa [created] => 2008-05-18 00:00:00 ) [Comment] => Array ( [0] => Array ( [author] => Daniel [post_id] => 1 ) [1] => Array ( [author] => Sam [post_id] => 1 ) ) ) [1] => Array (... As you can see, the Comment arrays only contain the author field (plus the post_id which is needed by CakePHP to map the results). You can also filter the associated Comment data by specifying a condition: $this->Post->contain(’Comment.author = "Daniel"’); $this->Post->find(’all’); //or... $this->Post->find(’all’, array(’contain’ => ’Comment.author = "Daniel"’)); This gives us a result that gives us posts with comments authored by Daniel: [0] => Array ( [Post] => Array ( [id] => 1 [title] => First article [content] => aaa [created] => 2008-05-18 00:00:00 ) [Comment] => Array ( [0] => Array ( [id] => 1 [post_id] => 1 [author] => Daniel [email] => [email protected] 506 Chapter 9. Core Libraries
- 513. CakePHP Cookbook Documentation,Release 2.x [website] => http://example.com [comment] => First comment [created] => 2008-05-18 00:00:00 ) ) ) There is an important caveat to using Containable when filtering on a deeper association. In the previous example, assume you had 3 posts in your database and Daniel had commented on 2 of those posts. The operation $this->Post->find(‘all’, array(‘contain’ => ‘Comment.author = “Daniel”’)); would return ALL 3 posts, not just the 2 posts that Daniel had commented on. It won’t return all comments however, just comments by Daniel.: [0] => Array ( [Post] => Array ( [id] => 1 [title] => First article [content] => aaa [created] => 2008-05-18 00:00:00 ) [Comment] => Array ( [0] => Array ( [id] => 1 [post_id] => 1 [author] => Daniel [email] => [email protected] [website] => http://example.com [comment] => First comment [created] => 2008-05-18 00:00:00 ) ) ) [1] => Array ( [Post] => Array ( [id] => 2 [title] => Second article [content] => bbb [created] => 2008-05-18 00:00:00 ) [Comment] => Array ( ) ) [2] => Array ( [Post] => Array ( Behaviors 507
- 514. CakePHP Cookbook Documentation,Release 2.x [id] => 3 [title] => Third article [content] => ccc [created] => 2008-05-18 00:00:00 ) [Comment] => Array ( [0] => Array ( [id] => 22 [post_id] => 3 [author] => Daniel [email] => [email protected] [website] => http://example.com [comment] => Another comment [created] => 2008-05-18 00:00:00 ) ) ) If you want to filter the posts by the comments, so that posts without a comment by Daniel won’t be returned, the easiest way is to find all the comments by Daniel and contain the Posts.: $this->Comment->find(’all’, array( ’conditions’ => ’Comment.author = "Daniel"’, ’contain’ => ’Post’ )); Additional filtering can be performed by supplying the standard find options: $this->Post->find(’all’, array(’contain’ => array( ’Comment’ => array( ’conditions’ => array(’Comment.author =’ => "Daniel"), ’order’ => ’Comment.created DESC’ ) ))); Here’s an example of using the ContainableBehavior when you’ve got deep and complex model relationships. Let’s consider the following model associations: User->Profile User->Account->AccountSummary User->Post->PostAttachment->PostAttachmentHistory->HistoryNotes User->Post->Tag This is how we retrieve the above associations with Containable: $this->User->find(’all’, array( ’contain’ => array( ’Profile’, ’Account’ => array( ’AccountSummary’ 508 Chapter 9. Core Libraries
- 515. CakePHP Cookbook Documentation,Release 2.x ), ’Post’ => array( ’PostAttachment’ => array( ’fields’ => array(’id’, ’name’), ’PostAttachmentHistory’ => array( ’HistoryNotes’ => array( ’fields’ => array(’id’, ’note’) ) ) ), ’Tag’ => array( ’conditions’ => array(’Tag.name LIKE’ => ’%happy%’) ) ) ) )); Keep in mind that contain key is only used once in the main model, you don’t need to use ‘contain’ again for related models. Note: When using ‘fields’ and ‘contain’ options - be careful to include all foreign keys that your query directly or indirectly requires. Please also note that because Containable must to be attached to all models used in containment, you may consider attaching it to your AppModel. ContainableBehavior options The ContainableBehavior has a number of options that can be set when the Behavior is attached to a model. The settings allow you to fine tune the behavior of Containable and work with other behaviors more easily. • recursive (boolean, optional) set to true to allow containable to automatically determine the recur- siveness level needed to fetch specified models, and set the model recursiveness to this level. setting it to false disables this feature. The default value is true. • notices (boolean, optional) issues E_NOTICES for bindings referenced in a containable call that are not valid. The default value is true. • autoFields: (boolean, optional) auto-add needed fields to fetch requested bindings. The default value is true. • order: (string, optional) the order of how the contained elements are sorted. From the previous example, this is an example of how to force the posts to be ordered by the date when they were last updated: $this->User->find(’all’, array( ’contain’ => array( ’Profile’, ’Post’ => array( ’order’ => ’Post.updated DESC’ ) Behaviors 509
- 516. CakePHP Cookbook Documentation,Release 2.x ) )); You can change ContainableBehavior settings at run time by reattaching the behavior as seen in Behaviors (Using Behaviors). ContainableBehavior can sometimes cause issues with other behaviors or queries that use aggregate func- tions and/or GROUP BY statements. If you get invalid SQL errors due to mixing of aggregate and non- aggregate fields, try disabling the autoFields setting.: $this->Post->Behaviors->load(’Containable’, array(’autoFields’ => false)); Using Containable with pagination By including the ‘contain’ parameter in the $paginate property it will apply to both the find(‘count’) and the find(‘all’) done on the model. See the section Using Containable for further details. Here’s an example of how to contain associations when paginating: $this->paginate[’User’] = array( ’contain’ => array(’Profile’, ’Account’), ’order’ => ’User.username’ ); $users = $this->paginate(’User’); Note: If you contained the associations through the model instead, it will not honor Containable’s recursive option. So if you set recursive to -1 for example for the model, it won’t work: $this->User->recursive = -1; $this->User->contain(array(’Profile’, ’Account’)); $users = $this->paginate(’User’); Translate class TranslateBehavior TranslateBehavior is actually quite easy to setup and works out of the box with very little configuration. In this section, you will learn how to add and setup the behavior to use in any model. If you are using TranslateBehavior in alongside containable issue, be sure to set the ‘fields’ key for your queries. Otherwise you could end up with invalid SQL generated. Initializing the i18n Database Tables You can either use the CakePHP console or you can manually create it. It is advised to use the console for this, because it might happen that the layout changes in future versions of CakePHP. Sticking to the console will make sure that you have the correct layout.: 510 Chapter 9. Core Libraries
- 517. CakePHP Cookbook Documentation,Release 2.x ./cake i18n Select [I] which will run the i18n database initialization script. You will be asked if you want to drop any existing and if you want to create it. Answer with yes if you are sure there is no i18n table already, and answer with yes again to create the table. Attaching the Translate Behavior to your Models Add it to your model by using the $actsAs property like in the following example.: class Post extends AppModel { public $actsAs = array( ’Translate’ ); } This will do nothing yet, because it expects a couple of options before it begins to work. You need to define which fields of the current model should be tracked in the translation table we’ve created in the first step. Defining the Fields You can set the fields by simply extending the ’Translate’ value with another array, like so: class Post extends AppModel { public $actsAs = array( ’Translate’ => array( ’fieldOne’, ’fieldTwo’, ’and_so_on’ ) ); } After you have done that (for example putting “title” as one of the fields) you already finished the basic setup. Great! According to our current example the model should now look something like this: class Post extends AppModel { public $actsAs = array( ’Translate’ => array( ’title’ ) ); } When defining fields for TranslateBehavior to translate, be sure to omit those fields from the translated model’s schema. If you leave the fields in, there can be issues when retrieving data with fallback locales. Note: If all the fields in your model are translated be sure to add created and modified columns to your table. CakePHP requires at least one non primary key field before it will save a record. Behaviors 511
- 518. CakePHP Cookbook Documentation,Release 2.x Conclusion From now on each record update/creation will cause TranslateBehavior to copy the value of “title” to the translation table (default: i18n) along with the current locale. A locale is the identifier of the language, so to speak. Reading translated content By default the TranslateBehavior will automatically fetch and add in data based on the current locale. The current locale is read from Configure::read(’Config.language’) which is assigned by the L10n class. You can override this default on the fly using $Model->locale. Retrieve translated fields in a specific locale By setting $Model->locale you can read translations for a specific locale: // Read the spanish locale data. $this->Post->locale = ’es’; $results = $this->Post->find(’first’, array( ’conditions’ => array(’Post.id’ => $id) )); // $results will contain the spanish translation. Retrieve all translation records for a field If you want to have all translation records attached to the current model record you simply extend the field array in your behavior setup as shown below. The naming is completely up to you.: class Post extends AppModel { public $actsAs = array( ’Translate’ => array( ’title’ => ’titleTranslation’ ) ); } With this setup the result of $this->Post->find() should look something like this: Array ( [Post] => Array ( [id] => 1 [title] => Beispiel Eintrag [body] => lorem ipsum... [locale] => de_de ) [titleTranslation] => Array ( [0] => Array 512 Chapter 9. Core Libraries
- 519. CakePHP Cookbook Documentation,Release 2.x ( [id] => 1 [locale] => en_us [model] => Post [foreign_key] => 1 [field] => title [content] => Example entry ) [1] => Array ( [id] => 2 [locale] => de_de [model] => Post [foreign_key] => 1 [field] => title [content] => Beispiel Eintrag ) ) ) Note: The model record contains a virtual field called “locale”. It indicates which locale is used in this result. Note that only fields of the model you are directly doing ‘find‘ on will be translated. Models attached via as- sociations won’t be translated because triggering callbacks on associated models is currently not supported. Using the bindTranslation method You can also retrieve all translations, only when you need them, using the bindTranslation method TranslateBehavior::bindTranslation($fields, $reset) $fields is a named-key array of field and association name, where the key is the translatable field and the value is the fake association name.: $this->Post->bindTranslation(array(’title’ => ’titleTranslation’)); // need at least recursive 1 for this to work. $this->Post->find(’all’, array(’recursive’ => 1)); With this setup the result of your find() should look something like this: Array ( [Post] => Array ( [id] => 1 [title] => Beispiel Eintrag [body] => lorem ipsum... [locale] => de_de ) Behaviors 513
- 520. CakePHP Cookbook Documentation,Release 2.x [titleTranslation] => Array ( [0] => Array ( [id] => 1 [locale] => en_us [model] => Post [foreign_key] => 1 [field] => title [content] => Example entry ) [1] => Array ( [id] => 2 [locale] => de_de [model] => Post [foreign_key] => 1 [field] => title [content] => Beispiel Eintrag ) ) ) Saving in another language You can force the model which is using the TranslateBehavior to save in a language other than the one detected. To tell a model in what language the content is going to be you simply change the value of the $locale property on the model before you save the data to the database. You can do that either in your controller or you can define it directly in the model. Example A: In your controller: class PostsController extends AppController { public function add() { if (!empty($this->request->data)) { // we are going to save the german version $this->Post->locale = ’de_de’; $this->Post->create(); if ($this->Post->save($this->request->data)) { return $this->redirect(array(’action’ => ’index’)); } } } } Example B: In your model: 514 Chapter 9. Core Libraries
- 521. CakePHP Cookbook Documentation,Release 2.x class Post extends AppModel { public $actsAs = array( ’Translate’ => array( ’title’ ) ); // Option 1) just define the property directly public $locale = ’en_us’; // Option 2) create a simple method public function setLanguage($locale) { $this->locale = $locale; } } Multiple Translation Tables If you expect a lot entries you probably wonder how to deal with a rapidly growing database table. There are two properties introduced by TranslateBehavior that allow to specify which “Model” to bind as the model containing the translations. These are $translateModel and $translateTable. Lets say we want to save our translations for all posts in the table “post_i18ns” instead of the default “i18n” table. To do so you need to setup your model like this: class Post extends AppModel { public $actsAs = array( ’Translate’ => array( ’title’ ) ); // Use a different model (and table) public $translateModel = ’PostI18n’; } Note: It is important that you to pluralize the table. It is now a usual model and can be treated as such and thus comes with the conventions involved. The table schema itself must be identical with the one generated by the CakePHP console script. To make sure it fits one could just initialize a empty i18n table using the console and rename the table afterwards. Create the TranslateModel For this to work you need to create the actual model file in your models folder. Reason is that there is no property to set the displayField directly in the model using this behavior yet. Make sure that you change the $displayField to ’field’.: Behaviors 515
- 522. CakePHP Cookbook Documentation,Release 2.x class PostI18n extends AppModel { public $displayField = ’field’; // important } // filename: PostI18n.php That’s all it takes. You can also add all other model stuff here like $useTable. But for better consis- tency we could do that in the model which actually uses this translation model. This is where the optional $translateTable comes into play. Changing the Table If you want to change the name of the table you simply define $translateTable in your model, like so: class Post extends AppModel { public $actsAs = array( ’Translate’ => array( ’title’ ) ); // Use a different model public $translateModel = ’PostI18n’; // Use a different table for translateModel public $translateTable = ’post_translations’; } Please note that you can’t use $translateTable alone. If you don’t intend to use a custom $translateModel then leave this property untouched. Reason is that it would break your setup and show you a “Missing Table” message for the default I18n model which is created in runtime. Tree class TreeBehavior It’s fairly common to want to store hierarchical data in a database table. Examples of such data might be categories with unlimited subcategories, data related to a multilevel menu system or a literal representation of hierarchy such as is used to store access control objects with ACL logic. For small trees of data, or where the data is only a few levels deep it is simple to add a parent_id field to your database table and use this to keep track of which item is the parent of what. Bundled with cake however, is a powerful behavior which allows you to use the benefits of MPTT logic9 without worrying about any of the intricacies of the technique - unless you want to ;). Requirements To use the tree behavior, your database table needs 3 fields as listed below (all are ints): • parent - default fieldname is parent_id, to store the id of the parent object 9 http://www.sitepoint.com/hierarchical-data-database-2/ 516 Chapter 9. Core Libraries
- 523. CakePHP Cookbook Documentation,Release 2.x • left - default fieldname is lft, to store the lft value of the current row. • right - default fieldname is rght, to store the rght value of the current row. If you are familiar with MPTT logic you may wonder why a parent field exists - quite simply it’s easier to do certain tasks if a direct parent link is stored on the database - such as finding direct children. Note: The parent field must be able to have a NULL value! It might seem to work if you just give the top elements a parent value of zero, but reordering the tree (and possible other operations) will fail. Basic Usage The tree behavior has a lot packed into it, but let’s start with a simple example - create the following database table and put some data in it: CREATE TABLE categories ( id INTEGER(10) UNSIGNED NOT NULL AUTO_INCREMENT, parent_id INTEGER(10) DEFAULT NULL, lft INTEGER(10) DEFAULT NULL, rght INTEGER(10) DEFAULT NULL, name VARCHAR(255) DEFAULT ’’, PRIMARY KEY (id) ); INSERT INTO ‘categories‘ (‘id‘, ‘name‘, ‘parent_id‘, ‘lft‘, ‘rght‘) VALUES (1, ’My Categories’, NULL, 1, 30); INSERT INTO ‘categories‘ (‘id‘, ‘name‘, ‘parent_id‘, ‘lft‘, ‘rght‘) VALUES (2, ’Fun’, 1, 2, 15); INSERT INTO ‘categories‘ (‘id‘, ‘name‘, ‘parent_id‘, ‘lft‘, ‘rght‘) VALUES (3, ’Sport’, 2, 3, 8); INSERT INTO ‘categories‘ (‘id‘, ‘name‘, ‘parent_id‘, ‘lft‘, ‘rght‘) VALUES (4, ’Surfing’, 3, 4, 5); INSERT INTO ‘categories‘ (‘id‘, ‘name‘, ‘parent_id‘, ‘lft‘, ‘rght‘) VALUES (5, ’Extreme knitting’, 3, 6, 7); INSERT INTO ‘categories‘ (‘id‘, ‘name‘, ‘parent_id‘, ‘lft‘, ‘rght‘) VALUES (6, ’Friends’, 2, 9, 14); INSERT INTO ‘categories‘ (‘id‘, ‘name‘, ‘parent_id‘, ‘lft‘, ‘rght‘) VALUES (7, ’Gerald’, 6, 10, 11); Behaviors 517
- 524. CakePHP Cookbook Documentation,Release 2.x INSERT INTO ‘categories‘ (‘id‘, ‘name‘, ‘parent_id‘, ‘lft‘, ‘rght‘) VALUES (8, ’Gwendolyn’, 6, 12, 13); INSERT INTO ‘categories‘ (‘id‘, ‘name‘, ‘parent_id‘, ‘lft‘, ‘rght‘) VALUES (9, ’Work’, 1, 16, 29); INSERT INTO ‘categories‘ (‘id‘, ‘name‘, ‘parent_id‘, ‘lft‘, ‘rght‘) VALUES (10, ’Reports’, 9, 17, 22); INSERT INTO ‘categories‘ (‘id‘, ‘name‘, ‘parent_id‘, ‘lft‘, ‘rght‘) VALUES (11, ’Annual’, 10, 18, 19); INSERT INTO ‘categories‘ (‘id‘, ‘name‘, ‘parent_id‘, ‘lft‘, ‘rght‘) VALUES (12, ’Status’, 10, 20, 21); INSERT INTO ‘categories‘ (‘id‘, ‘name‘, ‘parent_id‘, ‘lft‘, ‘rght‘) VALUES (13, ’Trips’, 9, 23, 28); INSERT INTO ‘categories‘ (‘id‘, ‘name‘, ‘parent_id‘, ‘lft‘, ‘rght‘) VALUES (14, ’National’, 13, 24, 25); INSERT INTO ‘categories‘ (‘id‘, ‘name‘, ‘parent_id‘, ‘lft‘, ‘rght‘) VALUES (15, ’International’, 13, 26, 27); For the purpose of checking that everything is setup correctly, we can create a test method and output the contents of our category tree to see what it looks like. With a simple controller: class CategoriesController extends AppController { public function index() { $data = $this->Category->generateTreeList( null, null, null, ’ ’ ); debug($data); die; } } and an even simpler model definition: // app/Model/Category.php class Category extends AppModel { public $actsAs = array(’Tree’); 518 Chapter 9. Core Libraries
- 525. CakePHP Cookbook Documentation,Release 2.x } We can check what our category tree data looks like by visiting /categories You should see something like this: • My Categories – Fun * Sport · Surfing · Extreme knitting * Friends · Gerald · Gwendolyn – Work * Reports · Annual · Status * Trips · National · International Adding data In the previous section, we used existing data and checked that it looked hierarchal via the method generateTreeList. However, usually you would add your data in exactly the same way as you would for any model. For example: // pseudo controller code $data[’Category’][’parent_id’] = 3; $data[’Category’][’name’] = ’Skating’; $this->Category->save($data); When using the tree behavior it’s not necessary to do any more than set the parent_id, and the tree behavior will take care of the rest. If you don’t set the parent_id, the tree behavior will add to the tree making your new addition a new top level entry: // pseudo controller code $data = array(); $data[’Category’][’name’] = ’Other People’s Categories’; $this->Category->save($data); Running the above two code snippets would alter your tree as follows: • My Categories Behaviors 519
- 526. CakePHP Cookbook Documentation,Release 2.x – Fun * Sport · Surfing · Extreme knitting · Skating New * Friends · Gerald · Gwendolyn – Work * Reports · Annual · Status * Trips · National · International • Other People’s Categories New Modifying data Modifying data is as transparent as adding new data. If you modify something, but do not change the parent_id field - the structure of your data will remain unchanged. For example: // pseudo controller code $this->Category->id = 5; // id of Extreme knitting $this->Category->save(array(’name’ => ’Extreme fishing’)); The above code did not affect the parent_id field - even if the parent_id is included in the data that is passed to save if the value doesn’t change, neither does the data structure. Therefore the tree of data would now look like: • My Categories • Fun • Sport – Surfing – Extreme fishing Updated – Skating • Friends – Gerald – Gwendolyn 520 Chapter 9. Core Libraries
- 527. CakePHP Cookbook Documentation,Release 2.x • Work • Reports – Annual – Status • Trips – National – International • Other People’s Categories Moving data around in your tree is also a simple affair. Let’s say that Extreme fishing does not belong under Sport, but instead should be located under Other People’s Categories. With the following code: // pseudo controller code $this->Category->id = 5; // id of Extreme fishing $newParentId = $this->Category->field( ’id’, array(’name’ => ’Other People’s Categories’) ); $this->Category->save(array(’parent_id’ => $newParentId)); As would be expected the structure would be modified to: • My Categories • Fun – Sport * Surfing * Skating – Friends * Gerald * Gwendolyn • Work – Reports * Annual * Status – Trips * National * International • Other People’s Categories Behaviors 521
- 528. CakePHP Cookbook Documentation,Release 2.x • Extreme fishing Moved Deleting data The tree behavior provides a number of ways to manage deleting data. To start with the simplest example; let’s say that the reports category is no longer useful. To remove it and any children it may have just call delete as you would for any model. For example with the following code: // pseudo controller code $this->Category->id = 10; $this->Category->delete(); The category tree would be modified as follows: • My Categories • Fun – Sport * Surfing * Skating – Friends * Gerald * Gwendolyn • Work – Trips * National * International • Other People’s Categories • Extreme fishing Querying and using your data Using and manipulating hierarchical data can be a tricky business. In addition to the core find methods, with the tree behavior there are a few more tree-orientated permutations at your disposal. Note: Most tree behavior methods return and rely on data being sorted by the lft field. If you call find() and do not order by lft, or call a tree behavior method and pass a sort order, you may get undesirable results. class TreeBehavior children($id = null, $direct = false, $fields = null, $order = null, $limit = null, $page = 1, $recursive = null) Parameters 522 Chapter 9. Core Libraries
- 529. CakePHP Cookbook Documentation,Release 2.x • $id – The ID of the record to look up • $direct – Set to true to return only the direct descendants • $fields – Single string field name or array of fields to include in the return • $order – SQL string of ORDER BY conditions • $limit – SQL LIMIT statement • $page – for accessing paged results • $recursive – Number of levels deep for recursive associated Models The children method takes the primary key value (the id) of a row and returns the children, by default in the order they appear in the tree. The second optional parameter defines whether or not only direct children should be returned. Using the example data from the previous section: $allChildren = $this->Category->children(1); // a flat array with 11 items // -- or -- $this->Category->id = 1; $allChildren = $this->Category->children(); // a flat array with 11 items // Only return direct children $directChildren = $this->Category->children(1, true); // a flat array with // 2 items Note: If you want a recursive array use find(’threaded’) childCount($id = null, $direct = false) As with the method children, childCount takes the primary key value (the id) of a row and returns how many children it has. The second optional parameter defines whether or not only direct children are counted. Using the example data from the previous section: $totalChildren = $this->Category->childCount(1); // will output 11 // -- or -- $this->Category->id = 1; $directChildren = $this->Category->childCount(); // will output 11 // Only counts the direct descendants of this category $numChildren = $this->Category->childCount(1, true); // will output 2 generateTreeList($conditions=null, $keyPath=null, $valuePath=null, $spacer= ‘_’, $recursive=null) Parameters • $conditions – Uses the same conditional options as find(). • $keyPath – Path to the field to use for the key. • $valuePath – Path to the field to use for the label. • $spacer – The string to use in front of each item to indicate depth. Behaviors 523
- 530. CakePHP Cookbook Documentation,Release 2.x • $recursive – The number of levels deep to fetch associated records This method will return data similar to find(‘list’) but with a nested prefix that is specified in the spacer option to show the structure of your data. Below is an example of what you can expect this method to return: $treelist = $this->Category->generateTreeList(); Output: array( [1] => "My Categories", [2] => "_Fun", [3] => "__Sport", [4] => "___Surfing", [16] => "___Skating", [6] => "__Friends", [7] => "___Gerald", [8] => "___Gwendolyn", [9] => "_Work", [13] => "__Trips", [14] => "___National", [15] => "___International", [17] => "Other People’s Categories", [5] => "_Extreme fishing" ) getParentNode() This convenience function will, as the name suggests, return the parent node for any node, or false if the node has no parent (it’s the root node). For example: $parent = $this->Category->getParentNode(2); //<- id for fun // $parent contains All categories getPath($id = null, $fields = null, $recursive = null) The ‘path’ when referring to hierarchal data is how you get from where you are to the top. So for example the path from the category “International” is: •My Categories •... •Work –Trips *... *International Using the id of “International” getPath will return each of the parents in turn (starting from the top).: 524 Chapter 9. Core Libraries
- 531. CakePHP Cookbook Documentation,Release 2.x $parents = $this->Category->getPath(15); // contents of $parents array( [0] => array( ’Category’ => array(’id’ => 1, ’name’ => ’My Categories’, ..) ), [1] => array( ’Category’ => array(’id’ => 9, ’name’ => ’Work’, ..) ), [2] => array( ’Category’ => array(’id’ => 13, ’name’ => ’Trips’, ..) ), [3] => array( ’Category’ => array(’id’ => 15, ’name’ => ’International’, ..) ), ) Advanced Usage The tree behavior doesn’t only work in the background, there are a number of specific meth- ods defined in the behavior to cater for all your hierarchical data needs, and any unexpected problems that might arise in the process. TreeBehavior::moveDown() Used to move a single node down the tree. You need to provide the ID of the element to be moved and a positive number of how many positions the node should be moved down. All child nodes for the specified node will also be moved. Here is an example of a controller action (in a controller named Categories) that moves a spec- ified node down the tree: public function movedown($id = null, $delta = null) { $this->Category->id = $id; if (!$this->Category->exists()) { throw new NotFoundException(__(’Invalid category’)); } if ($delta > 0) { $this->Category->moveDown($this->Category->id, abs($delta)); } else { $this->Session->setFlash( ’Please provide the number of positions the field should be’ . ’moved down.’ ); } return $this->redirect(array(’action’ => ’index’)); } Behaviors 525
- 532. CakePHP Cookbook Documentation,Release 2.x For example, if you’d like to move the “Sport” ( id of 3 ) category one position down, you would request: /categories/movedown/3/1. TreeBehavior::moveUp() Used to move a single node up the tree. You need to provide the ID of the element to be moved and a positive number of how many positions the node should be moved up. All child nodes will also be moved. Here’s an example of a controller action (in a controller named Categories) that moves a node up the tree: public function moveup($id = null, $delta = null) { $this->Category->id = $id; if (!$this->Category->exists()) { throw new NotFoundException(__(’Invalid category’)); } if ($delta > 0) { $this->Category->moveUp($this->Category->id, abs($delta)); } else { $this->Session->setFlash( ’Please provide a number of positions the category should’ . ’be moved up.’ ); } return $this->redirect(array(’action’ => ’index’)); } For example, if you would like to move the category “Gwendolyn” ( id of 8 ) up one position you would request /categories/moveup/8/1. Now the order of Friends will be Gwendolyn, Gerald. TreeBehavior::removeFromTree($id = null, $delete = false) Using this method will either delete or move a node but retain its sub-tree, which will be re- parented one level higher. It offers more control than delete, which for a model using the tree behavior will remove the specified node and all of its children. Taking the following tree as a starting point: • My Categories – Fun * Sport · Surfing · Extreme knitting · Skating Running the following code with the id for ‘Sport’: $this->Node->removeFromTree($id); 526 Chapter 9. Core Libraries
- 533. CakePHP Cookbook Documentation,Release 2.x The Sport node will be become a top level node: • My Categories – Fun * Surfing * Extreme knitting * Skating • Sport Moved This demonstrates the default behavior of removeFromTree of moving the node to have no parent, and re-parenting all children. If however the following code snippet was used with the id for ‘Sport’: $this->Node->removeFromTree($id, true); The tree would become • My Categories – Fun * Surfing * Extreme knitting * Skating This demonstrates the alternate use for removeFromTree, the children have been reparented and ‘Sport’ has been deleted. TreeBehavior::reorder(array(‘id’ => null, ‘field’ => $Model->displayField, ‘order’ => ‘ASC’, ‘verify’ => true)) Reorders the nodes (and child nodes) of the tree according to the field and direction specified in the parameters. This method does not change the parent of any node.: $model->reorder(array( //id of record to use as top node for reordering, default: $Model->id ’id’ => , //which field to use in reordering, default: $Model->displayField ’field’ => , //direction to order, default: ’ASC’ ’order’ => , //whether or not to verify the tree before reorder, default: true ’verify’ => )); Note: If you have saved your data or made other operations on the model, you might want to set $model->id = null before calling reorder. Otherwise only the current node and it’s children will be reordered. Behaviors 527
- 534. CakePHP Cookbook Documentation,Release 2.x Data Integrity Due to the nature of complex self referential data structures such as trees and linked lists, they can occasionally become broken by a careless call. Take heart, for all is not lost! The Tree Behavior contains several previously undocumented features designed to recover from such situations. TreeBehavior::recover($mode = ‘parent’, $missingParentAction = null) The mode parameter is used to specify the source of info that is valid/correct. The opposite source of data will be populated based upon that source of info. E.g. if the MPTT fields are corrupt or empty, with the $mode ’parent’ the values of the parent_id field will be used to populate the left and right fields. The missingParentAction parameter only applies to “parent” mode and determines what to do if the parent field contains an id that is not present. Available $mode options: • ’parent’ - use the existing parent_id‘s to update the lft and rght fields • ’tree’ - use the existing lft and rght fields to update parent_id Available missingParentActions options when using mode=’parent’: • null - do nothing and carry on • ’return’ - do nothing and return • ’delete’ - delete the node • int - set the parent_id to this id Example: // Rebuild all the left and right fields based on the parent_id $this->Category->recover(); // or $this->Category->recover(’parent’); // Rebuild all the parent_id’s based on the lft and rght fields $this->Category->recover(’tree’); TreeBehavior::reorder($options = array()) Reorders the nodes (and child nodes) of the tree according to the field and direction specified in the parameters. This method does not change the parent of any node. Reordering affects all nodes in the tree by default, however the following options can affect the process: • ’id’ - only reorder nodes below this node. • ’field‘ - field to use for sorting, default is the displayField for the model. • ’order’ - ’ASC’ for ascending, ’DESC’ for descending sort. • ’verify’ - whether or not to verify the tree prior to resorting. 528 Chapter 9. Core Libraries
- 535. CakePHP Cookbook Documentation,Release 2.x $options is used to pass all extra parameters, and has the following possible keys by default, all of which are optional: array( ’id’ => null, ’field’ => $model->displayField, ’order’ => ’ASC’, ’verify’ => true ) TreeBehavior::verify() Returns true if the tree is valid otherwise an array of errors, with fields for type, incorrect index and message. Each record in the output array is an array of the form (type, id, message) • type is either ’index’ or ’node’ • ’id’ is the id of the erroneous node. • ’message’ depends on the error Example Use: $this->Category->verify(); Example output: Array ( [0] => Array ( [0] => node [1] => 3 [2] => left and right values identical ) [1] => Array ( [0] => node [1] => 2 [2] => The parent node 999 doesn ’ t exist ) [10] => Array ( [0] => index [1] => 123 [2] => missing ) [99] => Array ( [0] => node [1] => 163 [2] => left greater than right ) Behaviors 529
- 536. CakePHP Cookbook Documentation,Release 2.x ) Components CakePHP has a selection of components to help take care of basic tasks in your controllers. See the section on Components for how to configure and use components. Components CakePHP has a selection of components to help take care of basic tasks in your controllers. See the section on Components for how to configure and use components. Pagination class PaginatorComponent(ComponentCollection $collection, array $settings = array()) One of the main obstacles of creating flexible and user-friendly web applications is designing an intuitive user interface. Many applications tend to grow in size and complexity quickly, and designers and program- mers alike find 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 defining 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 defined in an array structure like below: class PostsController extends AppController { public $components = array(’Paginator’); public $paginate = array( ’limit’ => 25, ’order’ => array( ’Post.title’ => ’asc’ ) 530 Chapter 9. Core Libraries
- 537. CakePHP Cookbook Documentation,Release 2.x ); } 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’), ’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 find 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 defining general pagination values, you can define more than one set of pagination defaults in the controller, you just name the keys of the array after the model you wish to configure: 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 defined, we can use the PaginatorComponent‘s 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 infor- mation is set to $this->request->params[’paging’], and is used by PaginatorHelper for creating links. PaginatorComponent::paginate() also adds PaginatorHelper to the list of Components 531
- 538. CakePHP Cookbook Documentation,Release 2.x 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 filter the records by passing conditions as second parameter to the paginate() function: $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 you’re not able to use the standard find options to create the query you need to display your data, there are a few options. You can use a custom find 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 defined below with the normal additional first parameter of $model: // paginate and paginateCount implemented on a behavior. public function paginate(Model $model, $conditions, $fields, $order, $limit, $page = 1, $recursive = null, $extra = array()) { // method content } public function paginateCount(Model $model, $conditions = null, $recursive = 0, $extra = array()) { // method body } It’s seldom you’ll need to implement paginate() and paginateCount(). You should make sure you can’t achieve your goal with the core model methods, or a custom finder. To paginate with a custom find type, you should set the 0‘th element, or the findType key as of 2.3: 532 Chapter 9. Core Libraries
- 539. CakePHP Cookbook Documentation,Release 2.x public $paginate = array( ’popular’ ); Since the 0th index is difficult to manage, in 2.3 the findType option was added: public $paginate = array( ’findType’ => ’popular’ ); The paginate() method should implement the following method signature. To use your own method/logic override it in the model you wish to get the data from: /** * Overridden paginate method - group by week, away_team_id and home_team_id */ public function paginate($conditions, $fields, $order, $limit, $page = 1, $recursive = null, $extra = array()) { $recursive = -1; $group = $fields = array(’week’, ’away_team_id’, ’home_team_id’); return $this->find( ’all’, compact(’conditions’, ’fields’, ’order’, ’limit’, ’page’, ’recursive’, ’group’) ); } 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_team_id FROM games"; $this->recursive = $recursive; $results = $this->query($sql); return count($results); } The observant reader will have noticed that the paginate method we’ve defined wasn’t actually necessary - All you have to do is add the keyword in controller’s $paginate class variable: /** * Add GROUP BY clause */ Components 533
- 540. CakePHP Cookbook Documentation,Release 2.x 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 fields 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 fields that can be expensive to calculate. You can use the 3rd parameter of PaginatorComponent::paginate() to restrict the columns that sorting will be done on: $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 request’s limit param is greater than this value, it will be reduced to the maxLimit value. 534 Chapter 9. Core Libraries
- 541. CakePHP Cookbook Documentation,Release 2.x 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 querys- tring 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. You can also modify the $settings property on the PaginatorComponent: $this->Paginator->settings[’paramType’] = ’querystring’; 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 modification of overloaded property $paginate has no effect.” Assign- ing an initial value to the property solves the issue: $this->paginate = array(); $this->paginate[’limit’] = 10; //or $this->paginate = array(’limit’ => 10); 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: Components 535
- 542. CakePHP Cookbook Documentation,Release 2.x 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 It’s 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. Sessions can be configured in a number of ways in CakePHP. For more information, you should see the Session configuration 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. So 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: 536 Chapter 9. Core Libraries
- 543. CakePHP Cookbook Documentation,Release 2.x $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 file system. It will then destroy the PHP session and then create a fresh session: $this->Session->destroy(); Creating notification messages SessionComponent::setFlash(string $message, string $element = ‘default’, array $params = array(), string $key = ‘flash’) Return type void Often in web applications, you will need to display a one-time notification message to the user after processing a form or acknowledging data. In CakePHP, these are referred to as “flash messages”. You can set flash 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"> Components 537
- 544. CakePHP Cookbook Documentation,Release 2.x Your stuff has been saved. </div> You can use the additional parameters of setFlash() to create different kinds of flash mes- sages. For example, you may want error and positive notifications to look different from each other. 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 the element (located in /app/View/Elements) in which the message should be rendered. Within the element, the message is available as $message. First we set the flash in our controller: $this->Session->setFlash(’Something custom!’, ’flash_custom’); Then we create the file app/View/Elements/flash_custom.ctp and build our custom flash 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 to the div output using $this->Session->flash() in your layout or view: $this->Session->setFlash( ’Example message text’, ’default’, array(’class’ => ’example_class’) ); 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’) ); 538 Chapter 9. Core Libraries
- 545. CakePHP Cookbook Documentation,Release 2.x Note: By default CakePHP does not escape the HTML in flash messages. If you are using any request or user data in your flash 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 flexible ways of identifying and checking user authorization. Suggested Reading Before Continuing Configuring authentication requires several steps including defining a users table, creating a model, con- troller & views, etc. This is all covered step by step in the Blog Tutorial. 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 you’ll 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. You can also use authentication systems like openid as well, however openid is not part of CakePHP core. Components 539
- 546. CakePHP Cookbook Documentation,Release 2.x Configuring Authentication handlers You configure authentication handlers using $this->Auth->authenticate. You can configure 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 configure authentication handlers in your controller’s beforeFilter or, in the $components array. You can pass configuration 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 you’ll 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 defined for the ‘all’ key. Any settings passed to a specific authentication object will override the matching key in the ‘all’ key. The core authenti- cation objects support the following configuration keys. • fields The fields 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, i.e. array(’User.is_active’ => 1). • contain Containable options for when the user record is loaded. If you want to use this option, you’ll need to make sure your model has the containable behavior attached. New in version 2.2. • passwordHasher Password hasher class. Defaults to Simple. New in version 2.4. To configure different fields for user in $components array: // Pass settings in $components array public $components = array( ’Auth’ => array( 540 Chapter 9. Core Libraries
- 547. CakePHP Cookbook Documentation,Release 2.x ’authenticate’ => array( ’Form’ => array( ’fields’ => array(’username’ => ’email’) ) ) ) ); Do not put other Auth configuration 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 config- uration 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 configuration, Basic authentication supports the following keys: • realm The realm being authenticated. Defaults to env(’SERVER_NAME’). In addition to the common configuration 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 be returned unchanged by clients. Defaults to md5($settings[’realm’]) 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 difficult at times. For 2.0, you’ll 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’)) { Components 541
- 548. CakePHP Cookbook Documentation,Release 2.x if ($this->Auth->login()) { return $this->redirect($this->Auth->redirectUrl()); // Prior to 2.3 use // ‘return $this->redirect($this->Auth->redirect());‘ } else { $this->Session->setFlash( __(’Username or password is incorrect’), ’default’, array(), ’auth’ ); } } } The above code (without any data passed to the login method), will attempt to log a user in us- ing 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 flash 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 iden- tify the user first and only log in when successful. Using Digest and Basic Authentication for logging in Because basic and digest authentication don’t re- quire an initial POST or a form so if using only basic / digest authenticators you don’t require a login action in your controller. Also you can set AuthComponent::$sessionKey to false to ensure AuthCompo- nent doesn’t try to read user info from session. Stateless authentication will re-verify the user’s 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 unauthen- ticated 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 } } 542 Chapter 9. Core Libraries
- 549. CakePHP Cookbook Documentation,Release 2.x Authentication objects should return false if they cannot identify the user. And an array of user infor- mation if they can. It’s 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 authen- tication object needs to support stateless or cookie-less authentication. See the sections on basic and digest authentication below for more information. Using custom authentication objects Once you’ve 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 don’t rely on cookies. A typical getUser method looks at the request/environment and uses the information there to confirm the identity of the user. HTTP Basic au- thentication for example uses $_SERVER[’PHP_AUTH_USER’] and $_SERVER[’PHP_AUTH_PW’] for the username and password fields. On each request, these values are used to re-identify the user and ensure they are valid user. As with authentication object’s 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 identifies a user based on a username and password. Handling unauthenticated requests When an unauthenticated user tries to access a protected page first 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 neces- sary. 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 it’s an AJAX request and AuthComponent::$ajaxLogin is specified 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. Components 543
- 550. CakePHP Cookbook Documentation,Release 2.x Displaying auth related flash 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 file in the body section preferable before the content_for_layout line.: echo $this->Session->flash(); echo $this->Session->flash(’auth’); You can customize the error messages, and flash settings AuthComponent uses. Using $this->Auth->flash you can configure the parameters AuthComponent uses for setting flash mes- sages. 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 flash message settings you can customize other error messages AuthComponent uses. In your controller’s 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 website that is protected."; 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 controller’s beforeFilter(), or component settings: if (!$this->Auth->loggedIn()) { $this->Auth->authError = false; } Hashing passwords AuthComponent no longer automatically hashes every password it can find. This was removed because it made a number of common tasks like validation difficult. 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 specifies 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 config. 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 specific hash type like this: public $components = array( ’Auth’ => array( ’authenticate’ => array( ’Form’ => array( ’passwordHasher’ => array( ’className’ => ’Simple’, ’hashType’ => ’sha256’ ) 544 Chapter 9. Core Libraries
- 551. CakePHP Cookbook Documentation,Release 2.x ) ) ) ); When creating new user records you can hash a password in the beforeSave callback of your model using appropriate password hasher class: App::uses(’SimplePasswordHasher’, ’Controller/Component/Auth’); class User extends AppModel { public function beforeSave($options = array()) { if (!empty($this->data[$this->alias][’password’])) { $passwordHasher = new SimplePasswordHasher(array(’hashType’ => ’sha256’)); $this->data[$this->alias][’password’] = $passwordHasher->hash( $this->data[$this->alias][’password’] ); } return true; } } You don’t 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 bcrypt10 a.k.a Blowfish 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 blowfish 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 defined 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, it’s also recommended that you store the digest password in a separate column, from the normal password hash: 10 https://en.wikipedia.org/wiki/Bcrypt Components 545
- 552. CakePHP Cookbook Documentation,Release 2.x class User extends AppModel { public function beforeSave($options = array()) { // make a password for digest auth. $this->data[$this->alias][’digest_hash’] = DigestAuthenticate::password( $this->data[$this->alias][’username’], $this->data[$this->alias][’password’], env(’SERVER_NAME’) ); return true; } } Passwords for digest authentication need a bit more information than other password hashes, based on the RFC for digest authentication. Note: The third parameter of DigestAuthenticate::password() must match the ‘realm’ config value defined when DigestAuthentication was configured 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 fol- lowing: App::uses(’AbstractPasswordHasher’, ’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’ => $id) ); $this->Auth->login($this->request->data[’User’]); 546 Chapter 9. Core Libraries
- 553. CakePHP Cookbook Documentation,Release 2.x 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 won’t 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’) // From inside a controller $this->Auth->user(’id’); Logging users out Eventually you’ll 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 difficult 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 identified/authenticated user is allowed to access the re- sources 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. Components 547
- 554. CakePHP Cookbook Documentation,Release 2.x Configuring Authorization handlers You configure authorization handlers using $this->Auth->authorize. You can configure 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 configure authorization handlers in your controller’s beforeFilter or, in the $components array. You can pass configuration 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/’), ’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 defined for the ‘all’ key. Any settings passed to a specific authorization object will override the matching key in the ‘all’ key. The core authorize objects support the following configuration keys. • actionPath Used by ActionsAuthorize to locate controller action ACO’s 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 au- thorize 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) { 548 Chapter 9. Core Libraries
- 555. CakePHP Cookbook Documentation,Release 2.x // 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 user’s access, true should be returned. It’s 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 you’ve created your custom authorize object, you can use them by including them in your AuthComponent’s authorize array: $this->Auth->authorize = array( ’Ldap’, // app authorize object. ’AuthBag.Combo’, // plugin authorize object. ); Using no authorization If you’d like to not use any of the built-in authorization objects, and want to han- dle things entirely outside of AuthComponent you can set $this->Auth->authorize = false;. By default AuthComponent starts off with authorize = false. If you don’t use an authorization scheme, make sure to check authorization yourself in your controller’s beforeFilter, or with another compo- nent. Making actions public There are often times controller actions that you wish to remain entirely public, or that don’t 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 you’re 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. Components 549
- 556. CakePHP Cookbook Documentation,Release 2.x 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 don’t want to create a custom authorize object. 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 prefix. Using ActionsAuthorize ActionsAuthorize integrates with the AclComponent, and provides a fine grained per action ACL check on each request. ActionsAuthorize is often paired with DbAcl to give dynamic and flexible 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. 550 Chapter 9. Core Libraries
- 557. CakePHP Cookbook Documentation,Release 2.x 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 specific 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 specific 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 configured authorize objects, so you can be sure the settings were applied every where: $this->Auth->mapActions(array( ’create’ => array(’register’), ’view’ => array(’show’, ’display’) )); 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 Suggested Reading Before Continuing. 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 Components 551
- 558. CakePHP Cookbook Documentation,Release 2.x property AuthComponent::$flash Settings to use when Auth needs to do a flash 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 (defined as a string or array) to the controller action that handles logins. Defaults to /users/login property AuthComponent::$loginRedirect The URL (defined 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 han- dle post-logout redirection, a redirect URL will be returned from AuthComponent::logout(). Defaults to AuthComponent::$loginAction. 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 unspecified, 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 specified actions. The special value of ’*’ will mark all the current controllers actions as public. Best used in your controller’s beforeFilter method. AuthComponent::constructAuthenticate() Loads the configured authentication objects. AuthComponent::constructAuthorize() Loads the authorization objects configured. AuthComponent::deny($action[, $action, ...]) Toggle one or more actions previously declared as public actions, as non-public methods. These methods will now require authorization. Best used inside your controller’s beforeFilter method. AuthComponent::flash($message) Set a flash message. Uses the Session component, and values from AuthComponent::$flash. 552 Chapter 9. Core Libraries
- 559. CakePHP Cookbook Documentation,Release 2.x AuthComponent::identify($request, $response) Parameters • $request (CakeRequest) – The request to use. • $response (CakeResponse) – The response to use, headers can be sent if authen- tication 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 configured 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) 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 configure 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. Components 553
- 560. CakePHP Cookbook Documentation,Release 2.x 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 specific data about the user: $id = $this->Auth->user(’id’); If the current user is not logged in or the key doesn’t exist, null will be returned. Security class SecurityComponent(ComponentCollection $collection, array $settings = array()) 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 configured through several configurable parameters. All of these properties can be set directly or through setter methods of the same name in your controller’s beforeFilter. By using the Security Component you automatically get CSRF11 and form tampering protection. Hidden token fields 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 component’s 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 fields’ “name” attributes. The Security Component looks for certain indica- tors that are created and managed by the FormHelper (especially those created in create() and end()). Dynamically altering the fields that are submitted in a POST request (e.g. disabling, deleting or creating 11 http://en.wikipedia.org/wiki/Cross-site_request_forgery 554 Chapter 9. Core Libraries
- 561. CakePHP Cookbook Documentation,Release 2.x new fields via JavaScript) is likely to trigger a black-holing of the request. See the $validatePost or $disabledFields configuration 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 configure 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’; } 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. Components 555
- 562. CakePHP Cookbook Documentation,Release 2.x 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. Restricting cross controller communication property SecurityComponent::$allowedControllers A list of controllers which can send requests to this controller. This can be used to control cross controller requests. property SecurityComponent::$allowedActions A list of actions which are allowed to send requests to this controller’s actions. This can be used to control cross controller requests. Form tampering prevention By default the SecurityComponent prevents users from tampering with forms in specific ways. The SecurityComponent will prevent the following things: • Unknown fields cannot be added to the form. • Fields cannot be removed from the form. • Values in hidden inputs cannot be modified. Preventing these types of tampering is accomplished by working with the FormHelper and tracking which fields are in a form. The values for hidden fields are tracked as well. All of this data is combined and turned into a hash. When a form is submitted, the SecurityComponent will use the POST data to build the same structure and compare the hash. Note: The SecurityComponent will not prevent select options from being added/changed. Nor will it prevent radio options from being added/changed. property SecurityComponent::$unlockedFields Set to a list of form fields to exclude from POST validation. Fields can be unlocked either in the 556 Chapter 9. Core Libraries
- 563. CakePHP Cookbook Documentation,Release 2.x Component, or with FormHelper::unlockField(). Fields that have been unlocked are not required to be part of the POST and hidden unlocked fields do not have their values checked. property SecurityComponent::$validatePost Set to false to completely skip the validation of POST requests, essentially turning off form valida- tion. CSRF configuration 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 single use. 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 controllers beforeFilter(). You would specify the security restrictions you want and the Security Component will enforce them on its startup: 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(); } } } Components 557
- 564. CakePHP Cookbook Documentation,Release 2.x 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 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 SecurityComponent 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 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 benefit 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 controller’s beforeFilter: public function beforeFilter() { $this->Security->csrfExpires = ’+1 hour’; // ... } The csrfExpires property can be any value that is compatible with strtotime()12. By default the 12 http://php.net/manual/en/function.strtotime.php 558 Chapter 9. Core Libraries
- 565. CakePHP Cookbook Documentation,Release 2.x 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 SecurityComponent blackHoleCallback will be called with a ‘csrf’ parameter. This helps you filter 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, the request 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 protec- tion 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 ar- ray. By default CSRF protection is enabled, and configured to use one-use tokens. Disabling CSRF and Post Data Validation For Specific Actions There may be cases where you want to disable all security checks for an action (ex. AJAX re- quests). You may “unlock” these actions by listing them in $this->Security->unlockedActions in your beforeFilter. The unlockedActions property will not effect other features of SecurityComponent. New in version 2.3. Request Handling class RequestHandlerComponent(ComponentCollection $collection, array $settings = ar- ray()) 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 file extensions are enabled. Components 559
- 566. CakePHP Cookbook Documentation,Release 2.x By default RequestHandler will automatically detect AJAX requests based on the HTTP-X- Requested-With header that many javascript libraries use. When used in conjunction with Router::parseExtensions() RequestHandler will automatically switch the layout and view files to those that match the requested type. Furthermore, if a helper with the same name as the requested exten- sion exists, it will be added to the Controllers Helper array. Lastly, if XML/JSON data is POST’ed 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 specified, 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’)) { // Execute XML-only code } if ($this->RequestHandler->accepts(array(’xml’, ’rss’, ’atom’))) { // Executes if the client accepts any of