Controller

1 Controller

Controller is an instance of BaseController or of a class that extends CController. It is created by the application object when the user requests it. When a controller runs, it performs the requested action, which usually brings in the needed models and renders an appropriate view.

An action, in its simplest form, is just a controller class method whose name starts with action.

A controller has a default action. When the user request does not specify which action to execute, the default action will be executed. By default, the default action is named as index. It can be changed by setting the public instance variable, CController::defaultAction.

The following code defines a site controller, an index action (the default action), and a contact action:


class SiteController extends BaseController
{
    public function actionIndex()
    {
        // ...
    }

    public function actionContact()
    {
        // ...
    }
}

2 Route

Controllers and actions are identified by IDs.

A Controller ID is in the format path/to/xyz, which corresponds to the controller class file protected/controllers/path/to/XyzController.php, where the token xyz should be replaced by actual names; e.g. post corresponds to protected/controllers/PostController.php.

Action ID is the action method name without the action prefix. For example, if a controller class contains a method named actionEdit, the ID of the corresponding action would be edit.

Users request a particular controller and action in terms of route. A route is formed by concatenating a controller ID and an action ID, separated by a slash. For example, the route post/edit refers to PostController and its edit action. By default, the URL http://hostname/index.php/post/edit would request the post controller and the edit action.

By default, routes are case-sensitive. It is possible to make routes case-insensitive by setting CUrlManager::caseSensitive to false in the application configuration. When in case-insensitive mode, make sure you follow the convention that directories containing controller class files are in lowercase, and both controller map and action map have lowercase keys.

An application can contain modules. The route for a controller action inside a module is in the format moduleID/controllerID/actionID. For more details, see the section about modules.

3 Controller Instantiation

A controller instance is created when CWebApplication handles an incoming request.

Given the ID of the controller, the application will use the following rules to determine what the controller class is and where the class file is located.

  • If CWebApplication::catchAllRequest is specified, a controller will be created based on this property, and the user-specified controller ID will be ignored. This is mainly used to put the application in maintenance mode and display a static notice page.
  • If the ID is found in CWebApplication::controllerMap, the corresponding controller configuration will be used to create the controller instance.
  • If the ID is in the format ‘path/to/xyz’, the controller class name is assumed to be XyzController and the corresponding class file is protected/controllers/path/to/XyzController.php. For example, a controller ID admin/user would be mapped to the controller class UserController and the class file protected/controllers/admin/UserController.php. If the class file does not exist, a 404 CHttpException will be raised.

When modules are used, the above process is slightly different. In particular, the application will check whether or not the ID refers to a controller inside a module, and if so, the module instance will be created first, followed by the controller instance.