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 oft 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).

Please note that 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- and SessionHelpers 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('Html', 'Ajax');
    var $components = array('Session', 'Email');
}

?>   

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

When defining these attributes, make sure to include the default classes (like including the HtmlHelper in the $helpers array, for example) if you intend to use them.

A few attributes exist in CakePHP controllers that give you control over how your views 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. If you haven’t defined one at /app/views/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. ?>

The $pageTitle controller attribute allows you to set the title of the rendered page. In order for this to work properly, your layout needs to include the $title_for_layout variable, at least between <title> tags in the head of the HTML document.

Just set $pageTitle to a string you’d like to see in the <title> of your document.

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['bare']

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

$this->params['isAjax']

Stores 1 if the current layout is set to ‘ajax’, 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
)

1. [url] => Array
2. (
3. [url] => posts/view
4. [var1] => 3
5. [var2] => 4
6. )

$this->data

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

<?php

// The FormHelper is used to create a form element:

$form->text('User.first_name');

// When rendered, it 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'];

?>

1. <?php
2. // The FormHelper is used to create a form element:
3. $form->text('User.first_name');
4. // When rendered, it looks something like:
5. <input name="data[User][first_name]" value="" type="text" />
6. // When the form is submitted to the controller via POST,
7. // the data shows up in $this->data.
8. //The submitted first name can be found here:
9. $this->data['User']['first_name'];
10. ?>

$this->params['form']

1. $this->params['form']

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

$this->params['bare']

1. $this->params['bare']

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

$this->params['ajax']

1. $this->params['ajax']

Stores 1 if the current layout is set to ‘ajax’, 0 if not. This variable is only set if the RequestHandler Component is being used in the controller.

$this->params['controller']

1. $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']

1. $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']

1. $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']

1. $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
)

1. [url] => Array
2. (
3. [url] => posts/view
4. [var1] => 3
5. [var2] => 4
6. )

$this->data

1. $this->data

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

<?php

// The FormHelper is used to create a form element:

$form->text('User.first_name');

// When rendered, it 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'];

?>

1. <?php
2. // The FormHelper is used to create a form element:
3. $form->text('User.first_name');
4. // When rendered, it looks something like:
5. <input name="data[User][first_name]" value="" type="text" />
6. // When the form is submitted to the controller via POST,
7. // the data shows up in $this->data.
8. //The submitted first name can be found here:
9. $this->data['User']['first_name'];
10. ?>

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.