Controllers¶

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 Cake\Controller\Controller class included in CakePHP. AppController is defined in src/Controller/AppController.php as follows:

namespace App\Controller;

use Cake\Controller\Controller;

class AppController extends Controller
{
}

Controller attributes and methods created in your AppController will be available in all controllers that extend it. Components (which you’ll learn about later) are best used for code that is used in many (but not necessarily all) controllers.

You can use your AppController to load components that will be used in every controller in your application. CakePHP provides a initialize() method that is invoked at the end of a Controller’s constructor for this kind of use:

namespace App\Controller;

use Cake\Controller\Controller;

class AppController extends Controller
{
    public function initialize()
    {
        // Always enable the CSRF component.
        $this->loadComponent('Csrf');
    }
}

In addition to the initialize() method, the older $components property will also allow you to declare which components should be loaded. While normal object-oriented inheritance rules apply, the components and helpers used by a controller are treated specially. In these cases, AppController property values are merged with child controller class arrays. The values in the child class will always override those in AppController.

Request Flow¶

When a request is made to a CakePHP application, CakePHP’s Cake\Routing\Router and Cake\Routing\Dispatcher classes use Connecting Routes to find and create the correct controller instance. 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 Request 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 online bakery example, our RecipesController might contain the view(), share(), and search() actions. The controller would be found in src/Controller/RecipesController.php and contain:

// src/Controller/RecipesController.php

class RecipesController extends AppController
{
    public function view($id)
    {
        // Action logic goes here.
    }

    public function share($customerId, $recipeId)
    {
        // Action logic goes here.
    }

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

The template files for these actions would be src/Template/Recipes/view.ctp, src/Template/Recipes/share.ctp, and src/Template/Recipes/search.ctp. The conventional view file name is the lowercased and underscored version of the action name.

Controller actions generally use Controller::set() to create a context that View uses to render the view layer. 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, you can return a Cake\Http\Response object from the action with the fully created response.

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.

Interacting with Views¶

Controllers interact with views in a number of ways. First, they are able to pass data to the views, using Controller::set(). You can also decide which view class to use, and which view file should be rendered from the controller.

// First you pass data from the controller:

$this->set('color', 'pink');

// Then, in the view, you can utilize the data:
?>

You have selected <?= h($color) ?> icing for the cake.

$data = [
    'color' => 'pink',
    'type' => 'sugar',
    'base_price' => 23.95
];

// Make $color, $type, and $base_price
// available to the view:

$this->set($data);

$this->viewBuilder()
    ->helpers(['MyCustom'])
    ->theme('Modern')
    ->className('Modern.Admin');

namespace App\Controller;

class RecipesController extends AppController
{
// ...
    public function search()
    {
        // Render the view in src/Template/Recipes/search.ctp
        $this->render();
    }
// ...
}

// Render the element in src/Template/Element/ajaxreturn.ctp
$this->render('/Element/ajaxreturn');

namespace App\Controller;

class PostsController extends AppController
{
    public function my_action()
    {
        $this->render('custom_file');
    }
}

namespace App\Controller;

class PostsController extends AppController
{
    public function my_action()
    {
        $this->render('Users.UserDetails/custom_file');
    }
}

Redirecting to Other Pages¶

Cake\Controller\Controller::redirect(string|array $url, integer $status)¶

The flow control method you’ll use most often is Controller::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 him to a receipt screen.

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

The method will return the response instance with appropriate headers set. You should return the response instance from your action to prevent view rendering and let the dispatcher handle actual redirection.

You can also use a relative or absolute URL as the $url argument:

return $this->redirect('/orders/thanks');
return $this->redirect('http://www.example.com');

You can also pass data to the action:

return $this->redirect(['action' => 'edit', $id]);

The second parameter of Controller::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.

If you need to redirect to the referer page you can use:

return $this->redirect($this->referer());

An example using query strings and hash would look like:

return $this->redirect([
    'controller' => 'Orders',
    'action' => 'confirm',
    '?' => [
        'product' => 'pizza',
        'quantity' => 5
    ],
    '#' => 'top'
]);

The generated URL would be:

http://www.example.com/orders/confirm?product=pizza&quantity=5#top

// From a delete action, you can render the updated
// list page.
$this->setAction('index');

Loading Additional Models¶

Cake\Controller\Controller::loadModel(string $modelClass, string $type)¶

The loadModel() function comes handy when you need to use a model table/collection that is not the controller’s default one:

// In a controller method.
$this->loadModel('Articles');
$recentArticles = $this->Articles->find('all', [
    'limit' => 5,
    'order' => 'Articles.created DESC'
]);

If you are using a table provider other than the built-in ORM you can link that table system into CakePHP’s controllers by connecting its factory method:

// In a controller method.
$this->modelFactory(
    'ElasticIndex',
    ['ElasticIndexes', 'factory']
);

After registering a table factory, you can use loadModel to load instances:

// In a controller method.
$this->loadModel('Locations', 'ElasticIndex');

Paginating a Model¶

Cake\Controller\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().

The $paginate attribute gives you an easy way to customize how paginate() behaves:

class ArticlesController extends AppController
{
    public $paginate = [
        'Articles' => [
            'conditions' => ['published' => 1]
        ]
    ];
}

Configuring Components to Load¶

Cake\Controller\Controller::loadComponent($name, $config = [])¶

In your Controller’s initialize() method you can define any components you want loaded, and any configuration data for them:

public function initialize()
{
    parent::initialize();
    $this->loadComponent('Csrf');
    $this->loadComponent('Comments', Configure::read('Comments'));
}

property Cake\Controller\Controller::$components¶

The $components property on your controllers allows you to configure components. Configured components and their dependencies will be created by CakePHP for you. Read the Configuring Components section for more information. As mentioned earlier the $components property will be merged with the property defined in each of your controller’s parent classes.

Configuring Helpers to Load¶

property Cake\Controller\Controller::$helpers¶

Let’s look at how to tell a CakePHP Controller that you plan to use additional MVC classes:

class RecipesController extends AppController
{
    public $helpers = ['Form'];
}

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

Request Life-cycle Callbacks¶

CakePHP controllers trigger several events/callbacks that you can use to insert logic around the request life-cycle:

//use Cake\Event\Event;
public function beforeFilter(Event $event)
{
    parent::beforeFilter($event);
}

More on Controllers¶