Welcome to The Cookbook

PHP4 users should start out their controller definitions using the $name attribute. 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 takes care of some PHP4 classname oddities and helps CakePHP resolve naming.

<?php

#   $name controller attribute usage example

class RecipesController extends AppController {
   var $name = 'Recipes';
}

?>	

1. <?php
2. # $name controller attribute usage example
3. class RecipesController extends AppController {
4. var $name = 'Recipes';
5. }
6. ?>

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 these MVC classes available to the controller as a class variable ($this->ModelName, for example).

Each controller has some of these classes available by default, so you may not need to configure your controller at all.

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.

The Html, Form, and Session Helpers are always available by default, as is the SessionComponent. 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.

<?php
class RecipesController extends AppController {
    var $name = 'Recipes';

    var $uses = array('Recipe', 'User');
    var $helpers = array('Ajax');
    var $components = array('Email');
}
?>   

1. <?php
2. class RecipesController extends AppController {
3. var $name = 'Recipes';
4. var $uses = array('Recipe', 'User');
5. var $helpers = array('Ajax');
6. var $components = array('Email');
7. }
8. ?>

Each of these variables are merged with their inherited values, therefore it is not necessary (for example) to redeclare the Form helper, or anything that is declared in your App controller.

A few attributes exist in CakePHP controllers that give you control over how your view is set inside of a layout.

The $layout attribute can be set to the name of a layout saved in /app/views/layouts. You specify a layout by setting $layout equal to the name of the layout file minus the .ctp extension. If this attribute has not been defined, CakePHP renders the default layout, default.ctp. If you haven’t defined one at /app/views/layouts/default.ctp, CakePHP’s core default layout will be rendered.

<?php

//   Using $layout to define an alternate layout

class RecipesController extends AppController {
    function quickSave() {
        $this->layout = 'ajax';
    }
}

?>

1. <?php
2. // Using $layout to define an alternate layout
3. class RecipesController extends AppController {
4. function quickSave() {
5. $this->layout = 'ajax';
6. }
7. }
8. ?>

You can also change the title of the page (that is located in the bar at the top of your browser) using $pageTitle. In order for this to work properly, your layout needs to include the $title_for_layout variable, at least between the <title> and </title> tags in the head of the HTML document.

<?php

//   Using $pageTitle to define the page title

class RecipesController extends AppController {
    function quickSave() {
        $this->pageTitle = 'My search engine optimized title';
    }
}

?>

1. <?php
2. // Using $pageTitle to define the page title
3. class RecipesController extends AppController {
4. function quickSave() {
5. $this->pageTitle = 'My search engine optimized title';
6. }
7. }
8. ?>

You can also set the page title from the view using $this->pageTitle (You must include the $this-> part.) This is recommended, as it better separates the logic from the layout and content. For a static page you must use $this->pageTitle in the view if you want a custom title.

If $this->pageTitle is not set, a title will be automatically generated based on the controller name, or the view file name in the case of a static page.

Controller parameters are available at $this->params in your CakePHP controller. This variable is used to provide access to information about the current request. The most common usage of $this->params is to get access to information that has been handed to the controller via POST or GET operations.

$this->params['form']

Any POST data from any form is stored here, including information also found in $_FILES.

$this->params['admin']

Is set to 1 if the current action was invoked via admin routing.

$this->params['bare']

Stores 1 if the current layout is empty, 0 if not.

$this->params['ajax']

Stores 1 if the current request is an ajax call, 0 if not. This variable is only set if the RequestHandler Component is being used in the controller.

$this->params['controller']

Stores the name of the current controller handling the request. For example, if the URL /posts/view/1 was requested, $this->params['controller'] would equal "posts".

$this->params['action']

Stores the name of the current action handling the request. For example, if the URL /posts/view/1 was requested, $this->params['action'] would equal "view".

$this->params['pass']

Stores the GET query string passed with the current request. For example, if the URL /posts/view/?var1=3&var2=4 was requested, $this->params['pass'] would equal "?var1=3&var2=4".

$this->params['url']

Stores the current URL requested, along with key-value pairs of get variables. For example, if the URL /posts/view/?var1=3&var2=4 was called, $this->params['url'] would contain:

[url] => Array
(
    [url] => posts/view
    [var1] => 3
    [var2] => 4
)

$this->data

Used to handle POST data sent from the FormHelper forms to the controller.

// The FormHelper is used to create a form element:
$form->text('User.first_name');

1. // The FormHelper is used to create a form element:
2. $form->text('User.first_name');

Which when rendered, looks something like:

 
<input name="data[User][first_name]" value="" type="text" />

When the form is submitted to the controller via POST, the data shows up in this->data

 
//The submitted first name can be found here:
$this->data['User']['first_name'];

2. //The submitted first name can be found here:
3. $this->data['User']['first_name'];

$this->params['prefix']

Set to the routing prefix. For example, this attribute would contain the string "admin" during a request to /admin/posts/someaction.

$this->params['named']

Stores any named parameters in the url query string in the form /key:value/. For example, if the URL /posts/view/var1:3/var2:4 was requested, $this->params['named'] would be an array containing:

[named] => Array
(
    [var1] => 3
    [var2] => 4
)

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

The $cacheAction attribute aids in caching views, and the $paginate attribute is used to set pagination defaults for the controller. For more information on how to use these attributes, check out their respective sections later on in this manual.