CController

Package system.web
Inheritance class CController » CBaseController » CComponent
Subclasses CCodeGenerator, CExtController
Since 1.0
Source Code framework/web/CController.php
CController manages a set of actions which deal with the corresponding user requests.

Through the actions, CController coordinates the data flow between models and views.

When a user requests an action 'XYZ', CController will do one of the following: 1. Method-based action: call method 'actionXYZ' if it exists; 2. Class-based action: create an instance of class 'XYZ' if the class is found in the action class map (specified via actions(), and execute the action; 3. Call missingAction(), which by default will raise a 404 HTTP exception.

If the user does not specify an action, CController will run the action specified by defaultAction, instead.

CController may be configured to execute filters before and after running actions. Filters preprocess/postprocess the user request/response and may quit executing actions if needed. They are executed in the order they are specified. If during the execution, any of the filters returns true, the rest filters and the action will no longer get executed.

Filters can be individual objects, or methods defined in the controller class. They are specified by overriding filters() method. The following is an example of the filter specification:
array(
    'accessControl - login',
    'ajaxOnly + search',
    array(
        'COutputCache + list',
        'duration'=>300,
    ),
)
The above example declares three filters: accessControl, ajaxOnly, COutputCache. The first two are method-based filters (defined in CController), which refer to filtering methods in the controller class; while the last refers to an object-based filter whose class is 'system.web.widgets.COutputCache' and the 'duration' property is initialized as 300 (s).

For method-based filters, a method named 'filterXYZ($filterChain)' in the controller class will be executed, where 'XYZ' stands for the filter name as specified in filters(). Note, inside the filter method, you must call $filterChain->run() if the action should be executed. Otherwise, the filtering process would stop at this filter.

Filters can be specified so that they are executed only when running certain actions. For method-based filters, this is done by using '+' and '-' operators in the filter specification. The '+' operator means the filter runs only when the specified actions are requested; while the '-' operator means the filter runs only when the requested action is not among those actions. For object-based filters, the '+' and '-' operators are following the class name.

Public Properties

Property Type Description Defined By
action CAction the action currently being executed, null if no active action. CController
actionParams array Returns the request parameters that will be used for action parameter binding. CController
cachingStack CStack stack of COutputCache objects CController
clips CMap Returns the list of clips. CController
defaultAction string the name of the default action. CController
id string ID of the controller CController
layout mixed the name of the layout to be applied to this controller's views. CController
module CWebModule the module that this controller belongs to. CController
pageTitle string the page title. CController
route string the route (module ID, controller ID and action ID) of the current request. CController
uniqueId string the controller ID that is prefixed with the module ID (if any). CController
viewPath string Returns the directory containing view files for this controller. CController

Public Methods

Method Description Defined By
__call() Calls the named method which is not a class method. CComponent
__construct() CController
__get() Returns a property value, an event handler list or a behavior based on its name. CComponent
__isset() Checks if a property value is null. CComponent
__set() Sets value of a component property. CComponent
__unset() Sets a component property to be null. CComponent
accessRules() Returns the access rules for this controller. CController
actions() Returns a list of external action classes. CController
asa() Returns the named behavior object. CComponent
attachBehavior() Attaches a behavior to this component. CComponent
attachBehaviors() Attaches a list of behaviors to the component. CComponent
attachEventHandler() Attaches an event handler to an event. CComponent
beginCache() Begins fragment caching. CBaseController
beginClip() Begins recording a clip. CBaseController
beginContent() Begins the rendering of content that is to be decorated by the specified view. CBaseController
beginWidget() Creates a widget and executes it. CBaseController
behaviors() Returns a list of behaviors that this controller should behave as. CController
canGetProperty() Determines whether a property can be read. CComponent
canSetProperty() Determines whether a property can be set. CComponent
clearPageStates() Removes all page states. CController
createAbsoluteUrl() Creates an absolute URL for the specified action defined in this controller. CController
createAction() Creates the action instance based on the action name. CController
createUrl() Creates a relative URL for the specified action defined in this controller. CController
createWidget() Creates a widget and initializes it. CBaseController
detachBehavior() Detaches a behavior from the component. CComponent
detachBehaviors() Detaches all behaviors from the component. CComponent
detachEventHandler() Detaches an existing event handler. CComponent
disableBehavior() Disables an attached behavior. CComponent
disableBehaviors() Disables all behaviors attached to this component. CComponent
enableBehavior() Enables an attached behavior. CComponent
enableBehaviors() Enables all behaviors attached to this component. CComponent
endCache() Ends fragment caching. CBaseController
endClip() Ends recording a clip. CBaseController
endContent() Ends the rendering of content. CBaseController
endWidget() Ends the execution of the named widget. CBaseController
evaluateExpression() Evaluates a PHP expression or callback under the context of this component. CComponent
filterAccessControl() The filter method for 'accessControl' filter. CController
filterAjaxOnly() The filter method for 'ajaxOnly' filter. CController
filterPostOnly() The filter method for 'postOnly' filter. CController
filters() Returns the filter configurations. CController
forward() Processes the request using another controller action. CController
getAction() Returns the action currently being executed, null if no active action. CController
getActionParams() Returns the request parameters that will be used for action parameter binding. CController
getCachingStack() Returns stack of COutputCache objects CController
getClips() Returns the list of clips. CController
getEventHandlers() Returns the list of attached event handlers for an event. CComponent
getId() Returns ID of the controller CController
getLayoutFile() Looks for the layout view script based on the layout name. CController
getModule() Returns the module that this controller belongs to. It returns null if the controller does not belong to any module CController
getPageState() Returns a persistent page state value. CController
getPageTitle() Returns the page title. Defaults to the controller name and the action name. CController
getRoute() Returns the route (module ID, controller ID and action ID) of the current request. CController
getUniqueId() Returns the controller ID that is prefixed with the module ID (if any). CController
getViewFile() Looks for the view file according to the given view name. CController
getViewPath() Returns the directory containing view files for this controller. CController
hasEvent() Determines whether an event is defined. CComponent
hasEventHandler() Checks whether the named event has attached handlers. CComponent
hasProperty() Determines whether a property is defined. CComponent
init() Initializes the controller. CController
invalidActionParams() This method is invoked when the request parameters do not satisfy the requirement of the specified action. CController
isCachingStackEmpty() Returns whether the caching stack is empty. CController
missingAction() Handles the request whose action is not recognized. CController
processDynamicOutput() Postprocesses the dynamic output. CController
processOutput() Postprocesses the output generated by render(). CController
raiseEvent() Raises an event. CComponent
recordCachingAction() Records a method call when an output cache is in effect. CController
redirect() Redirects the browser to the specified URL or route (controller/action). CController
refresh() Refreshes the current page. CController
render() Renders a view with a layout. CController
renderClip() Renders a named clip with the supplied parameters. CController
renderDynamic() Renders dynamic content returned by the specified callback. CController
renderDynamicInternal() This method is internally used. CController
renderFile() Renders a view file. CBaseController
renderInternal() Renders a view file. CBaseController
renderPartial() Renders a view. CController
renderText() Renders a static text string. CController
resolveViewFile() Finds a view file based on its name. CController
run() Runs the named action. CController
runAction() Runs the action after passing through all filters. CController
runActionWithFilters() Runs an action with the specified filters. CController
setAction() Sets the action currently being executed. CController
setPageState() Saves a persistent page state value. CController
setPageTitle() Sets the page title. CController
widget() Creates a widget and executes it. CBaseController

Protected Methods

Method Description Defined By
afterAction() This method is invoked right after an action is executed. CController
afterRender() This method is invoked after the specified view is rendered by calling render(). CController
beforeAction() This method is invoked right before an action is to be executed (after all possible filters.) CController
beforeRender() This method is invoked at the beginning of render(). CController
createActionFromMap() Creates the action instance based on the action map. CController
loadPageStates() Loads page states from a hidden input. CController
replaceDynamicOutput() Replaces the dynamic content placeholders with actual content. CController
savePageStates() Saves page states as a base64 string. CController

Property Details

action property

public CAction getAction()
public void setAction(CAction $value)

the action currently being executed, null if no active action.

actionParams property read-only (available since v1.1.7)

public array getActionParams()

Returns the request parameters that will be used for action parameter binding. By default, this method will return $_GET. You may override this method if you want to use other request parameters (e.g. $_GET+$_POST).

cachingStack property read-only

public CStack getCachingStack(boolean $createIfNull=true)

stack of COutputCache objects

clips property read-only

public CMap getClips()

Returns the list of clips. A clip is a named piece of rendering result that can be inserted at different places.

See Also

defaultAction property

public string $defaultAction;

the name of the default action. Defaults to 'index'.

id property read-only

public string getId()

ID of the controller

layout property

public mixed $layout;

the name of the layout to be applied to this controller's views. Defaults to null, meaning the application layout is used. If it is false, no layout will be applied. The module layout will be used if the controller belongs to a module and this layout property is null.

module property read-only

public CWebModule getModule()

the module that this controller belongs to. It returns null if the controller does not belong to any module

pageTitle property

public string getPageTitle()
public void setPageTitle(string $value)

the page title. Defaults to the controller name and the action name.

route property read-only (available since v1.1.0)

public string getRoute()

the route (module ID, controller ID and action ID) of the current request.

uniqueId property read-only

public string getUniqueId()

the controller ID that is prefixed with the module ID (if any).

viewPath property read-only

public string getViewPath()

Returns the directory containing view files for this controller. The default implementation returns 'protected/views/ControllerID'. Child classes may override this method to use customized view path. If the controller belongs to a module, the default view path is the module view path appended with the controller ID.

Method Details

__construct() method

public void __construct(string $id, CWebModule $module=NULL)
$id string id of this controller
$module CWebModule the module that this controller belongs to.
Source Code: framework/web/CController.php#110 (show)
public function __construct($id,$module=null)
{
    
$this->_id=$id;
    
$this->_module=$module;
    
$this->attachBehaviors($this->behaviors());
}

accessRules() method

public array accessRules()
{return} array list of access rules. See CAccessControlFilter for details about rule specification.
Source Code: framework/web/CController.php#243 (show)
public function accessRules()
{
    return array();
}

Returns the access rules for this controller. Override this method if you use the accessControl filter.

actions() method

public array actions()
{return} array list of external action classes
Source Code: framework/web/CController.php#208 (show)
public function actions()
{
    return array();
}

Returns a list of external action classes. Array keys are action IDs, and array values are the corresponding action class in dot syntax (e.g. 'edit'=>'application.controllers.article.EditArticle') or arrays representing the configuration of the actions, such as the following,

return array(
    'action1'=>'path.to.Action1Class',
    'action2'=>array(
        'class'=>'path.to.Action2Class',
        'property1'=>'value1',
        'property2'=>'value2',
    ),
);
Derived classes may override this method to declare external actions.

Note, in order to inherit actions defined in the parent class, a child class needs to merge the parent actions with child actions using functions like array_merge().

You may import actions from an action provider (such as a widget, see CWidget::actions), like the following:
return array(
    ...other actions...
    // import actions declared in ProviderClass::actions()
    // the action IDs will be prefixed with 'pro.'
    'pro.'=>'path.to.ProviderClass',
    // similar as above except that the imported actions are
    // configured with the specified initial property values
    'pro2.'=>array(
        'class'=>'path.to.ProviderClass',
        'action1'=>array(
            'property1'=>'value1',
        ),
        'action2'=>array(
            'property2'=>'value2',
        ),
    ),
)


In the above, we differentiate action providers from other action declarations by the array keys. For action providers, the array keys must contain a dot. As a result, an action ID 'pro2.action1' will be resolved as the 'action1' action declared in the 'ProviderClass'.

See Also

afterAction() method

protected void afterAction(CAction $action)
$action CAction the action just executed.
Source Code: framework/web/CController.php#1106 (show)
protected function afterAction($action)
{
}

This method is invoked right after an action is executed. You may override this method to do some postprocessing for the action.

afterRender() method (available since v1.1.5)

protected void afterRender(string $view, string &$output)
$view string the view that has been rendered
$output string the rendering result of the view. Note that this parameter is passed as a reference. That means you can modify it within this method.
Source Code: framework/web/CController.php#821 (show)
protected function afterRender($view, &$output)
{
}

This method is invoked after the specified view is rendered by calling render(). Note that this method is invoked BEFORE processOutput(). You may override this method to do some postprocessing for the view rendering.

beforeAction() method

protected boolean beforeAction(CAction $action)
$action CAction the action to be executed.
{return} boolean whether the action should be executed.
Source Code: framework/web/CController.php#1096 (show)
protected function beforeAction($action)
{
    return 
true;
}

This method is invoked right before an action is to be executed (after all possible filters.) You may override this method to do last-minute preparation for the action.

beforeRender() method (available since v1.1.5)

protected boolean beforeRender(string $view)
$view string the view to be rendered
{return} boolean whether the view should be rendered.
Source Code: framework/web/CController.php#807 (show)
protected function beforeRender($view)
{
    return 
true;
}

This method is invoked at the beginning of render(). You may override this method to do some preprocessing when rendering a view.

behaviors() method

public array behaviors()
{return} array the behavior configurations (behavior name=>behavior configuration)
Source Code: framework/web/CController.php#233 (show)
public function behaviors()
{
    return array();
}

Returns a list of behaviors that this controller should behave as. The return value should be an array of behavior configurations indexed by behavior names. Each behavior configuration can be either a string specifying the behavior class or an array of the following structure:

'behaviorName'=>array(
    'class'=>'path.to.BehaviorClass',
    'property1'=>'value1',
    'property2'=>'value2',
)


Note, the behavior classes must implement IBehavior or extend from CBehavior. Behaviors declared in this method will be attached to the controller when it is instantiated.

For more details about behaviors, see CComponent.

clearPageStates() method

public void clearPageStates()
Source Code: framework/web/CController.php#1197 (show)
public function clearPageStates()
{
    
$this->_pageStates=array();
}

Removes all page states.

createAbsoluteUrl() method

public string createAbsoluteUrl(string $route, array $params=array ( ), string $schema='', string $ampersand='&')
$route string the URL route. This should be in the format of 'ControllerID/ActionID'. If the ControllerPath is not present, the current controller ID will be prefixed to the route. If the route is empty, it is assumed to be the current action.
$params array additional GET parameters (name=>value). Both the name and value will be URL-encoded.
$schema string schema to use (e.g. http, https). If empty, the schema used for the current request will be used.
$ampersand string the token separating name-value pairs in the URL.
{return} string the constructed URL
Source Code: framework/web/CController.php#983 (show)
public function createAbsoluteUrl($route,$params=array(),$schema='',$ampersand='&')
{
    
$url=$this->createUrl($route,$params,$ampersand);
    if(
strpos($url,'http')===0)
        return 
$url;
    else
        return 
Yii::app()->getRequest()->getHostInfo($schema).$url;
}

Creates an absolute URL for the specified action defined in this controller.

createAction() method

public CAction createAction(string $actionID)
$actionID string ID of the action. If empty, the default action will be used.
{return} CAction the action instance, null if the action does not exist.
Source Code: framework/web/CController.php#411 (show)
public function createAction($actionID)
{
    if(
$actionID==='')
        
$actionID=$this->defaultAction;
    if(
method_exists($this,'action'.$actionID) && strcasecmp($actionID,'s')) // we have actions method
        
return new CInlineAction($this,$actionID);
    else
    {
        
$action=$this->createActionFromMap($this->actions(),$actionID,$actionID);
        if(
$action!==null && !method_exists($action,'run'))
            throw new 
CException(Yii::t('yii''Action class {class} must implement the "run" method.', array('{class}'=>get_class($action))));
        return 
$action;
    }
}

Creates the action instance based on the action name. The action can be either an inline action or an object. The latter is created by looking up the action map specified in actions.

See Also

createActionFromMap() method

protected CAction createActionFromMap(array $actionMap, string $actionID, string $requestActionID, array $config=array ( ))
$actionMap array the action map
$actionID string the action ID that has its prefix stripped off
$requestActionID string the originally requested action ID
$config array the action configuration that should be applied on top of the configuration specified in the map
{return} CAction the action instance, null if the action does not exist.
Source Code: framework/web/CController.php#438 (show)
protected function createActionFromMap($actionMap,$actionID,$requestActionID,$config=array())
{
    if((
$pos=strpos($actionID,'.'))===false && isset($actionMap[$actionID]))
    {
        
$baseConfig=is_array($actionMap[$actionID]) ? $actionMap[$actionID] : array('class'=>$actionMap[$actionID]);
        return 
Yii::createComponent(empty($config)?$baseConfig:array_merge($baseConfig,$config),$this,$requestActionID);
    }
    elseif(
$pos===false)
        return 
null;

    
// the action is defined in a provider
    
$prefix=substr($actionID,0,$pos+1);
    if(!isset(
$actionMap[$prefix]))
        return 
null;
    
$actionID=(string)substr($actionID,$pos+1);

    
$provider=$actionMap[$prefix];
    if(
is_string($provider))
        
$providerType=$provider;
    elseif(
is_array($provider) && isset($provider['class']))
    {
        
$providerType=$provider['class'];
        if(isset(
$provider[$actionID]))
        {
            if(
is_string($provider[$actionID]))
                
$config=array_merge(array('class'=>$provider[$actionID]),$config);
            else
                
$config=array_merge($provider[$actionID],$config);
        }
    }
    else
        throw new 
CException(Yii::t('yii','Object configuration must be an array containing a "class" element.'));

    
$class=Yii::import($providerType,true);
    
$map=call_user_func(array($class,'actions'));

    return 
$this->createActionFromMap($map,$actionID,$requestActionID,$config);
}

Creates the action instance based on the action map. This method will check to see if the action ID appears in the given action map. If so, the corresponding configuration will be used to create the action instance.

createUrl() method

public string createUrl(string $route, array $params=array ( ), string $ampersand='&')
$route string the URL route. This should be in the format of 'ControllerID/ActionID'. If the ControllerID is not present, the current controller ID will be prefixed to the route. If the route is empty, it is assumed to be the current action. If the controller belongs to a module, the module ID will be prefixed to the route. (If you do not want the module ID prefix, the route should start with a slash '/'.)
$params array additional GET parameters (name=>value). Both the name and value will be URL-encoded. If the name is '#', the corresponding value will be treated as an anchor and will be appended at the end of the URL.
$ampersand string the token separating name-value pairs in the URL.
{return} string the constructed URL
Source Code: framework/web/CController.php#962 (show)
public function createUrl($route,$params=array(),$ampersand='&')
{
    if(
$route==='')
        
$route=$this->getId().'/'.$this->getAction()->getId();
    elseif(
strpos($route,'/')===false)
        
$route=$this->getId().'/'.$route;
    if(
$route[0]!=='/' && ($module=$this->getModule())!==null)
        
$route=$module->getId().'/'.$route;
    return 
Yii::app()->createUrl(trim($route,'/'),$params,$ampersand);
}

Creates a relative URL for the specified action defined in this controller.

filterAccessControl() method

public void filterAccessControl(CFilterChain $filterChain)
$filterChain CFilterChain the filter chain that the filter is on.
Source Code: framework/web/CController.php#1144 (show)
public function filterAccessControl($filterChain)
{
    
$filter=new CAccessControlFilter;
    
$filter->setRules($this->accessRules());
    
$filter->filter($filterChain);
}

The filter method for 'accessControl' filter. This filter is a wrapper of CAccessControlFilter. To use this filter, you must override accessRules method.

filterAjaxOnly() method

public void filterAjaxOnly(CFilterChain $filterChain)
$filterChain CFilterChain the filter chain that the filter is on.
Source Code: framework/web/CController.php#1130 (show)
public function filterAjaxOnly($filterChain)
{
    if(
Yii::app()->getRequest()->getIsAjaxRequest())
        
$filterChain->run();
    else
        throw new 
CHttpException(400,Yii::t('yii','Your request is invalid.'));
}

The filter method for 'ajaxOnly' filter. This filter throws an exception (CHttpException with code 400) if the applied action is receiving a non-AJAX request.

filterPostOnly() method

public void filterPostOnly(CFilterChain $filterChain)
$filterChain CFilterChain the filter chain that the filter is on.
Source Code: framework/web/CController.php#1116 (show)
public function filterPostOnly($filterChain)
{
    if(
Yii::app()->getRequest()->getIsPostRequest())
        
$filterChain->run();
    else
        throw new 
CHttpException(400,Yii::t('yii','Your request is invalid.'));
}

The filter method for 'postOnly' filter. This filter throws an exception (CHttpException with code 400) if the applied action is receiving a non-POST request.

filters() method

public array filters()
{return} array a list of filter configurations.
Source Code: framework/web/CController.php#153 (show)
public function filters()
{
    return array();
}

Returns the filter configurations.

By overriding this method, child classes can specify filters to be applied to actions.

This method returns an array of filter specifications. Each array element specify a single filter.

For a method-based filter (called inline filter), it is specified as 'FilterName[ +|- Action1, Action2, ...]', where the '+' ('-') operators describe which actions should be (should not be) applied with the filter.

For a class-based filter, it is specified as an array like the following:

array(
    'FilterClass[ +|- Action1, Action2, ...]',
    'name1'=>'value1',
    'name2'=>'value2',
    ...
)
where the name-value pairs will be used to initialize the properties of the filter.

Note, in order to inherit filters defined in the parent class, a child class needs to merge the parent filters with child filters using functions like array_merge().

See Also

forward() method (available since v1.1.0)

public void forward(string $route, boolean $exit=true)
$route string the route of the new controller action. This can be an action ID, or a complete route with module ID (optional in the current module), controller ID and action ID. If the former, the action is assumed to be located within the current controller.
$exit boolean whether to end the application after this call. Defaults to true.
Source Code: framework/web/CController.php#747 (show)
public function forward($route,$exit=true)
{
    if(
strpos($route,'/')===false)
        
$this->run($route);
    else
    {
        if(
$route[0]!=='/' && ($module=$this->getModule())!==null)
            
$route=$module->getId().'/'.$route;
        
Yii::app()->runController($route);
    }
    if(
$exit)
        
Yii::app()->end();
}

Processes the request using another controller action. This is like redirect, but the user browser's URL remains unchanged. In most cases, you should call redirect instead of this method.

getAction() method

public CAction getAction()
{return} CAction the action currently being executed, null if no active action.
Source Code: framework/web/CController.php#493 (show)
public function getAction()
{
    return 
$this->_action;
}

getActionParams() method (available since v1.1.7)

public array getActionParams()
{return} array the request parameters to be used for action parameter binding
Source Code: framework/web/CController.php#323 (show)
public function getActionParams()
{
    return 
$_GET;
}

Returns the request parameters that will be used for action parameter binding. By default, this method will return $_GET. You may override this method if you want to use other request parameters (e.g. $_GET+$_POST).

getCachingStack() method

public CStack getCachingStack(boolean $createIfNull=true)
$createIfNull boolean whether to create a stack if it does not exist yet. Defaults to true.
{return} CStack stack of COutputCache objects
Source Code: framework/web/CController.php#1072 (show)
public function getCachingStack($createIfNull=true)
{
    if(!
$this->_cachingStack)
        
$this->_cachingStack=new CStack;
    return 
$this->_cachingStack;
}

getClips() method

public CMap getClips()
{return} CMap the list of clips
Source Code: framework/web/CController.php#729 (show)
public function getClips()
{
    if(
$this->_clips!==null)
        return 
$this->_clips;
    else
        return 
$this->_clips=new CMap;
}

Returns the list of clips. A clip is a named piece of rendering result that can be inserted at different places.

See Also

getId() method

public string getId()
{return} string ID of the controller
Source Code: framework/web/CController.php#509 (show)
public function getId()
{
    return 
$this->_id;
}

getLayoutFile() method

public string getLayoutFile(mixed $layoutName)
$layoutName mixed layout name
{return} string the view file for the layout. False if the view file cannot be found
Source Code: framework/web/CController.php#636 (show)
public function getLayoutFile($layoutName)
{
    if(
$layoutName===false)
        return 
false;
    if((
$theme=Yii::app()->getTheme())!==null && ($layoutFile=$theme->getLayoutFile($this,$layoutName))!==false)
        return 
$layoutFile;

    if(empty(
$layoutName))
    {
        
$module=$this->getModule();
        while(
$module!==null)
        {
            if(
$module->layout===false)
                return 
false;
            if(!empty(
$module->layout))
                break;
            
$module=$module->getParentModule();
        }
        if(
$module===null)
            
$module=Yii::app();
        
$layoutName=$module->layout;
    }
    elseif((
$module=$this->getModule())===null)
        
$module=Yii::app();

    return 
$this->resolveViewFile($layoutName,$module->getLayoutPath(),Yii::app()->getViewPath(),$module->getViewPath());
}

Looks for the layout view script based on the layout name.

The layout name can be specified in one of the following ways:

  • layout is false: returns false, meaning no layout.
  • layout is null: the currently active module's layout will be used. If there is no active module, the application's layout will be used.
  • a regular view name.


The resolution of the view file based on the layout view is similar to that in getViewFile. In particular, the following rules are followed:

Otherwise, this method will return the corresponding view file based on the following criteria:
  • When a theme is currently active, this method will call CTheme::getLayoutFile to determine which view file should be returned.
  • absolute view within a module: the view name starts with a single slash '/'. In this case, the view will be searched for under the currently active module's view path. If there is no active module, the view will be searched for under the application's view path.
  • absolute view within the application: the view name starts with double slashes '//'. In this case, the view will be searched for under the application's view path. This syntax has been available since version 1.1.3.
  • aliased view: the view name contains dots and refers to a path alias. The view file is determined by calling YiiBase::getPathOfAlias(). Note that aliased views cannot be themed because they can refer to a view file located at arbitrary places.
  • relative view: otherwise. Relative views will be searched for under the currently active module's layout path. In case when there is no active module, the view will be searched for under the application's layout path.


After the view file is identified, this method may further call CApplication::findLocalizedFile to find its localized version if internationalization is needed.

getModule() method

public CWebModule getModule()
{return} CWebModule the module that this controller belongs to. It returns null if the controller does not belong to any module
Source Code: framework/web/CController.php#538 (show)
public function getModule()
{
    return 
$this->_module;
}

getPageState() method

public mixed getPageState(string $name, mixed $defaultValue=NULL)
$name string the state name
$defaultValue mixed the value to be returned if the named state is not found
{return} mixed the page state value
Source Code: framework/web/CController.php#1162 (show)
public function getPageState($name,$defaultValue=null)
{
    if(
$this->_pageStates===null)
        
$this->_pageStates=$this->loadPageStates();
    return isset(
$this->_pageStates[$name])?$this->_pageStates[$name]:$defaultValue;
}

Returns a persistent page state value. A page state is a variable that is persistent across POST requests of the same page. In order to use persistent page states, the form(s) must be stateful which are generated using CHtml::statefulForm.

getPageTitle() method

public string getPageTitle()
{return} string the page title. Defaults to the controller name and the action name.
Source Code: framework/web/CController.php#995 (show)
public function getPageTitle()
{
    if(
$this->_pageTitle!==null)
        return 
$this->_pageTitle;
    else
    {
        
$name=ucfirst(basename($this->getId()));
        if(
$this->getAction()!==null && strcasecmp($this->getAction()->getId(),$this->defaultAction))
            return 
$this->_pageTitle=Yii::app()->name.' - '.ucfirst($this->getAction()->getId()).' '.$name;
        else
            return 
$this->_pageTitle=Yii::app()->name.' - '.$name;
    }
}

getRoute() method (available since v1.1.0)

public string getRoute()
{return} string the route (module ID, controller ID and action ID) of the current request.
Source Code: framework/web/CController.php#526 (show)
public function getRoute()
{
    if((
$action=$this->getAction())!==null)
        return 
$this->getUniqueId().'/'.$action->getId();
    else
        return 
$this->getUniqueId();
}

getUniqueId() method

public string getUniqueId()
{return} string the controller ID that is prefixed with the module ID (if any).
Source Code: framework/web/CController.php#517 (show)
public function getUniqueId()
{
    return 
$this->_module $this->_module->getId().'/'.$this->_id $this->_id;
}

getViewFile() method

public string getViewFile(string $viewName)
$viewName string view name
{return} string the view file path, false if the view file does not exist
Source Code: framework/web/CController.php#587 (show)
public function getViewFile($viewName)
{
    if((
$theme=Yii::app()->getTheme())!==null && ($viewFile=$theme->getViewFile($this,$viewName))!==false)
        return 
$viewFile;
    
$moduleViewPath=$basePath=Yii::app()->getViewPath();
    if((
$module=$this->getModule())!==null)
        
$moduleViewPath=$module->getViewPath();
    return 
$this->resolveViewFile($viewName,$this->getViewPath(),$basePath,$moduleViewPath);
}

Looks for the view file according to the given view name.

When a theme is currently active, this method will call CTheme::getViewFile to determine which view file should be returned.

Otherwise, this method will return the corresponding view file based on the following criteria:

  • absolute view within a module: the view name starts with a single slash '/'. In this case, the view will be searched for under the currently active module's view path. If there is no active module, the view will be searched for under the application's view path.
  • absolute view within the application: the view name starts with double slashes '//'. In this case, the view will be searched for under the application's view path. This syntax has been available since version 1.1.3.
  • aliased view: the view name contains dots and refers to a path alias. The view file is determined by calling YiiBase::getPathOfAlias(). Note that aliased views cannot be themed because they can refer to a view file located at arbitrary places.
  • relative view: otherwise. Relative views will be searched for under the currently active controller's view path.


After the view file is identified, this method may further call CApplication::findLocalizedFile to find its localized version if internationalization is needed.

getViewPath() method

public string getViewPath()
{return} string the directory containing the view files for this controller. Defaults to 'protected/views/ControllerID'.
Source Code: framework/web/CController.php#551 (show)
public function getViewPath()
{
    if((
$module=$this->getModule())===null)
        
$module=Yii::app();
    return 
$module->getViewPath().DIRECTORY_SEPARATOR.$this->getId();
}

Returns the directory containing view files for this controller. The default implementation returns 'protected/views/ControllerID'. Child classes may override this method to use customized view path. If the controller belongs to a module, the default view path is the module view path appended with the controller ID.

init() method

public void init()
Source Code: framework/web/CController.php#122 (show)
public function init()
{
}

Initializes the controller. This method is called by the application before the controller starts to execute. You may override this method to perform the needed initialization for the controller.

invalidActionParams() method (available since v1.1.7)

public void invalidActionParams(CAction $action)
$action CAction the action being executed
Source Code: framework/web/CController.php#335 (show)
public function invalidActionParams($action)
{
    throw new 
CHttpException(400,Yii::t('yii','Your request is invalid.'));
}

This method is invoked when the request parameters do not satisfy the requirement of the specified action. The default implementation will throw a 400 HTTP exception.

isCachingStackEmpty() method

public boolean isCachingStackEmpty()
{return} boolean whether the caching stack is empty. If not empty, it means currently there are some output cache in effect. Note, the return result of this method may change when it is called in different output regions, depending on the partition of output caches.
Source Code: framework/web/CController.php#1085 (show)
public function isCachingStackEmpty()
{
    return 
$this->_cachingStack===null || !$this->_cachingStack->getCount();
}

Returns whether the caching stack is empty.

loadPageStates() method

protected array loadPageStates()
{return} array the loaded page states
Source Code: framework/web/CController.php#1206 (show)
protected function loadPageStates()
{
    if(!empty(
$_POST[self::STATE_INPUT_NAME]))
    {
        if((
$data=base64_decode($_POST[self::STATE_INPUT_NAME]))!==false)
        {
            if(
extension_loaded('zlib'))
                
$data=@gzuncompress($data);
            if((
$data=Yii::app()->getSecurityManager()->validateData($data))!==false)
                return 
unserialize($data);
        }
    }
    return array();
}

Loads page states from a hidden input.

missingAction() method

public void missingAction(string $actionID)
$actionID string the missing action name
Source Code: framework/web/CController.php#484 (show)
public function missingAction($actionID)
{
    throw new 
CHttpException(404,Yii::t('yii','The system is unable to find the requested action "{action}".',
        array(
'{action}'=>$actionID==''?$this->defaultAction:$actionID)));
}

Handles the request whose action is not recognized. This method is invoked when the controller cannot find the requested action. The default implementation simply throws an exception.

processDynamicOutput() method

public string processDynamicOutput(string $output)
$output string output to be processed
{return} string the processed output
Source Code: framework/web/CController.php#375 (show)
public function processDynamicOutput($output)
{
    if(
$this->_dynamicOutput)
    {
        
$output=preg_replace_callback('/<###dynamic-(\d+)###>/',array($this,'replaceDynamicOutput'),$output);
    }
    return 
$output;
}

Postprocesses the dynamic output. This method is internally used. Do not call this method directly.

processOutput() method

public string processOutput(string $output)
$output string the output generated by the current action
{return} string the output that has been processed.
Source Code: framework/web/CController.php#350 (show)
public function processOutput($output)
{
    
Yii::app()->getClientScript()->render($output);

    
// if using page caching, we should delay dynamic output replacement
    
if($this->_dynamicOutput!==null && $this->isCachingStackEmpty())
    {
        
$output=$this->processDynamicOutput($output);
        
$this->_dynamicOutput=null;
    }

    if(
$this->_pageStates===null)
        
$this->_pageStates=$this->loadPageStates();
    if(!empty(
$this->_pageStates))
        
$this->savePageStates($this->_pageStates,$output);

    return 
$output;
}

Postprocesses the output generated by render(). This method is invoked at the end of render() and renderText(). If there are registered client scripts, this method will insert them into the output at appropriate places. If there are dynamic contents, they will also be inserted. This method may also save the persistent page states in hidden fields of stateful forms in the page.

recordCachingAction() method

public void recordCachingAction(string $context, string $method, array $params)
$context string a property name of the controller. It refers to an object whose method is being called. If empty it means the controller itself.
$method string the method name
$params array parameters passed to the method
Source Code: framework/web/CController.php#1059 (show)
public function recordCachingAction($context,$method,$params)
{
    if(
$this->_cachingStack// record only when there is an active output cache
    
{
        foreach(
$this->_cachingStack as $cache)
            
$cache->recordAction($context,$method,$params);
    }
}

Records a method call when an output cache is in effect. When the content is served from the output cache, the recorded method will be re-invoked.

See Also

redirect() method

public void redirect(mixed $url, boolean $terminate=true, integer $statusCode=302)
$url mixed the URL to be redirected to. If the parameter is an array, the first element must be a route to a controller action and the rest are GET parameters in name-value pairs.
$terminate boolean whether to terminate the current application after calling this method. Defaults to true.
$statusCode integer the HTTP status code. Defaults to 302. See http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html for details about HTTP status code.
Source Code: framework/web/CController.php#1026 (show)
public function redirect($url,$terminate=true,$statusCode=302)
{
    if(
is_array($url))
    {
        
$route=isset($url[0]) ? $url[0] : '';
        
$url=$this->createUrl($route,array_splice($url,1));
    }
    
Yii::app()->getRequest()->redirect($url,$terminate,$statusCode);
}

Redirects the browser to the specified URL or route (controller/action).

refresh() method

public void refresh(boolean $terminate=true, string $anchor='')
$terminate boolean whether to terminate the current application after calling this method
$anchor string the anchor that should be appended to the redirection URL. Defaults to empty. Make sure the anchor starts with '#' if you want to specify it.
Source Code: framework/web/CController.php#1044 (show)
public function refresh($terminate=true,$anchor='')
{
    
$this->redirect(Yii::app()->getRequest()->getUrl().$anchor,$terminate);
}

Refreshes the current page. The effect of this method call is the same as user pressing the refresh button on the browser (without post data).

render() method

public string render(string $view, array $data=NULL, boolean $return=false)
$view string name of the view to be rendered. See getViewFile for details about how the view script is resolved.
$data array data to be extracted into PHP variables and made available to the view script
$return boolean whether the rendering result should be returned instead of being displayed to end users.
{return} string the rendering result. Null if the rendering result is not required.
Source Code: framework/web/CController.php#781 (show)
public function render($view,$data=null,$return=false)
{
    if(
$this->beforeRender($view))
    {
        
$output=$this->renderPartial($view,$data,true);
        if((
$layoutFile=$this->getLayoutFile($this->layout))!==false)
            
$output=$this->renderFile($layoutFile,array('content'=>$output),true);

        
$this->afterRender($view,$output);

        
$output=$this->processOutput($output);

        if(
$return)
            return 
$output;
        else
            echo 
$output;
    }
}

Renders a view with a layout.

This method first calls renderPartial to render the view (called content view). It then renders the layout view which may embed the content view at appropriate place. In the layout view, the content view rendering result can be accessed via variable $content. At the end, it calls processOutput to insert scripts and dynamic contents if they are available.

By default, the layout view script is "protected/views/layouts/main.php". This may be customized by changing layout.

renderClip() method (available since v1.1.8)

public mixed renderClip(string $name, array $params=array ( ), boolean $return=false)
$name string the name of the clip
$params array an array of named parameters (name=>value) that should replace their corresponding placeholders in the clip
$return boolean whether to return the clip content or echo it.
{return} mixed either the clip content or null
Source Code: framework/web/CController.php#897 (show)
public function renderClip($name,$params=array(),$return=false)
{
    
$text=isset($this->clips[$name]) ? strtr($this->clips[$name], $params) : '';

    if(
$return)
        return 
$text;
    else
        echo 
$text;
}

Renders a named clip with the supplied parameters. This is similar to directly accessing the clips property. The main difference is that it can take an array of named parameters which will replace the corresponding placeholders in the clip.

renderDynamic() method

public void renderDynamic(callback $callback)
$callback callback a PHP callback which returns the needed dynamic content. When the callback is specified as a string, it will be first assumed to be a method of the current controller class. If the method does not exist, it is assumed to be a global PHP function. Note, the callback should return the dynamic content instead of echoing it.
Source Code: framework/web/CController.php#926 (show)
public function renderDynamic($callback)
{
    
$n=count($this->_dynamicOutput);
    echo 
"<###dynamic-$n###>";
    
$params=func_get_args();
    
array_shift($params);
    
$this->renderDynamicInternal($callback,$params);
}

Renders dynamic content returned by the specified callback. This method is used together with COutputCache. Dynamic contents will always show as their latest state even if the content surrounding them is being cached. This is especially useful when caching pages that are mostly static but contain some small dynamic regions, such as username or current time. We can use this method to render these dynamic regions to ensure they are always up-to-date.

The first parameter to this method should be a valid PHP callback, while the rest parameters will be passed to the callback.

Note, the callback and its parameter values will be serialized and saved in cache. Make sure they are serializable.

renderDynamicInternal() method

public void renderDynamicInternal(callback $callback, array $params)
$callback callback a PHP callback which returns the needed dynamic content.
$params array parameters passed to the PHP callback
Source Code: framework/web/CController.php#941 (show)
public function renderDynamicInternal($callback,$params)
{
    
$this->recordCachingAction('','renderDynamicInternal',array($callback,$params));
    if(
is_string($callback) && method_exists($this,$callback))
        
$callback=array($this,$callback);
    
$this->_dynamicOutput[]=call_user_func_array($callback,$params);
}

This method is internally used.

See Also

renderPartial() method

public string renderPartial(string $view, array $data=NULL, boolean $return=false, boolean $processOutput=false)
$view string name of the view to be rendered. See getViewFile for details about how the view script is resolved.
$data array data to be extracted into PHP variables and made available to the view script
$return boolean whether the rendering result should be returned instead of being displayed to end users
$processOutput boolean whether the rendering result should be postprocessed using processOutput.
{return} string the rendering result. Null if the rendering result is not required.
Source Code: framework/web/CController.php#868 (show)
public function renderPartial($view,$data=null,$return=false,$processOutput=false)
{
    if((
$viewFile=$this->getViewFile($view))!==false)
    {
        
$output=$this->renderFile($viewFile,$data,true);
        if(
$processOutput)
            
$output=$this->processOutput($output);
        if(
$return)
            return 
$output;
        else
            echo 
$output;
    }
    else
        throw new 
CException(Yii::t('yii','{controller} cannot find the requested view "{view}".',
            array(
'{controller}'=>get_class($this), '{view}'=>$view)));
}

Renders a view.

The named view refers to a PHP script (resolved via getViewFile) that is included by this method. If $data is an associative array, it will be extracted as PHP variables and made available to the script.

This method differs from render() in that it does not apply a layout to the rendered result. It is thus mostly used in rendering a partial view, or an AJAX response.

renderText() method

public string renderText(string $text, boolean $return=false)
$text string the static text string
$return boolean whether the rendering result should be returned instead of being displayed to end users.
{return} string the rendering result. Null if the rendering result is not required.
Source Code: framework/web/CController.php#833 (show)
public function renderText($text,$return=false)
{
    if((
$layoutFile=$this->getLayoutFile($this->layout))!==false)
        
$text=$this->renderFile($layoutFile,array('content'=>$text),true);

    
$text=$this->processOutput($text);

    if(
$return)
        return 
$text;
    else
        echo 
$text;
}

Renders a static text string. The string will be inserted in the current controller layout and returned back.

See Also

replaceDynamicOutput() method

protected string replaceDynamicOutput(array $matches)
$matches array matches
{return} string the replacement
Source Code: framework/web/CController.php#391 (show)
protected function replaceDynamicOutput($matches)
{
    
$content=$matches[0];
    if(isset(
$this->_dynamicOutput[$matches[1]]))
    {
        
$content=$this->_dynamicOutput[$matches[1]];
        
$this->_dynamicOutput[$matches[1]]=null;
    }
    return 
$content;
}

Replaces the dynamic content placeholders with actual content. This is a callback function used internally.

See Also

resolveViewFile() method

public mixed resolveViewFile(string $viewName, string $viewPath, string $basePath, string $moduleViewPath=NULL)
$viewName string the view name
$viewPath string the directory that is used to search for a relative view name
$basePath string the directory that is used to search for an absolute view name under the application
$moduleViewPath string the directory that is used to search for an absolute view name under the current module. If this is not set, the application base view path will be used.
{return} mixed the view file path. False if the view file does not exist.
Source Code: framework/web/CController.php#690 (show)
public function resolveViewFile($viewName,$viewPath,$basePath,$moduleViewPath=null)
{
    if(empty(
$viewName))
        return 
false;

    if(
$moduleViewPath===null)
        
$moduleViewPath=$basePath;

    if((
$renderer=Yii::app()->getViewRenderer())!==null)
        
$extension=$renderer->fileExtension;
    else
        
$extension='.php';
    if(
$viewName[0]==='/')
    {
        if(
strncmp($viewName,'//',2)===0)
            
$viewFile=$basePath.$viewName;
        else
            
$viewFile=$moduleViewPath.$viewName;
    }
    elseif(
strpos($viewName,'.'))
        
$viewFile=Yii::getPathOfAlias($viewName);
    else
        
$viewFile=$viewPath.DIRECTORY_SEPARATOR.$viewName;

    if(
is_file($viewFile.$extension))
        return 
Yii::app()->findLocalizedFile($viewFile.$extension);
    elseif(
$extension!=='.php' && is_file($viewFile.'.php'))
        return 
Yii::app()->findLocalizedFile($viewFile.'.php');
    else
        return 
false;
}

Finds a view file based on its name. The view name can be in one of the following formats:

  • absolute view within a module: the view name starts with a single slash '/'. In this case, the view will be searched for under the currently active module's view path. If there is no active module, the view will be searched for under the application's view path.
  • absolute view within the application: the view name starts with double slashes '//'. In this case, the view will be searched for under the application's view path. This syntax has been available since version 1.1.3.
  • aliased view: the view name contains dots and refers to a path alias. The view file is determined by calling YiiBase::getPathOfAlias(). Note that aliased views cannot be themed because they can refer to a view file located at arbitrary places.
  • relative view: otherwise. Relative views will be searched for under the currently active controller's view path.
For absolute view and relative view, the corresponding view file is a PHP file whose name is the same as the view name. The file is located under a specified directory. This method will call CApplication::findLocalizedFile to search for a localized file, if any.

run() method

public void run(string $actionID)
$actionID string action ID
Source Code: framework/web/CController.php#257 (show)
public function run($actionID)
{
    if((
$action=$this->createAction($actionID))!==null)
    {
        if((
$parent=$this->getModule())===null)
            
$parent=Yii::app();
        if(
$parent->beforeControllerAction($this,$action))
        {
            
$this->runActionWithFilters($action,$this->filters());
            
$parent->afterControllerAction($this,$action);
        }
    }
    else
        
$this->missingAction($actionID);
}

Runs the named action. Filters specified via filters() will be applied.

runAction() method

public void runAction(CAction $action)
$action CAction action to run
Source Code: framework/web/CController.php#302 (show)
public function runAction($action)
{
    
$priorAction=$this->_action;
    
$this->_action=$action;
    if(
$this->beforeAction($action))
    {
        if(
$action->runWithParams($this->getActionParams())===false)
            
$this->invalidActionParams($action);
        else
            
$this->afterAction($action);
    }
    
$this->_action=$priorAction;
}

Runs the action after passing through all filters. This method is invoked by runActionWithFilters after all possible filters have been executed and the action starts to run.

runActionWithFilters() method

public void runActionWithFilters(CAction $action, array $filters)
$action CAction the action to be executed.
$filters array list of filters to be applied to the action.
Source Code: framework/web/CController.php#283 (show)
public function runActionWithFilters($action,$filters)
{
    if(empty(
$filters))
        
$this->runAction($action);
    else
    {
        
$priorAction=$this->_action;
        
$this->_action=$action;
        
CFilterChain::create($this,$action,$filters)->run();
        
$this->_action=$priorAction;
    }
}

Runs an action with the specified filters. A filter chain will be created based on the specified filters and the action will be executed then.

savePageStates() method

protected void savePageStates(array $states, string &$output)
$states array the states to be saved.
$output string the output to be modified. Note, this is passed by reference.
Source Code: framework/web/CController.php#1226 (show)
protected function savePageStates($states,&$output)
{
    
$data=Yii::app()->getSecurityManager()->hashData(serialize($states));
    if(
extension_loaded('zlib'))
        
$data=gzcompress($data);
    
$value=base64_encode($data);
    
$output=str_replace(CHtml::pageStateField(''),CHtml::pageStateField($value),$output);
}

Saves page states as a base64 string.

setAction() method

public void setAction(CAction $value)
$value CAction the action currently being executed.
Source Code: framework/web/CController.php#501 (show)
public function setAction($value)
{
    
$this->_action=$value;
}

setPageState() method

public void setPageState(string $name, mixed $value, mixed $defaultValue=NULL)
$name string the state name
$value mixed the page state value
$defaultValue mixed the default page state value. If this is the same as the given value, the state will be removed from persistent storage.
Source Code: framework/web/CController.php#1181 (show)
public function setPageState($name,$value,$defaultValue=null)
{
    if(
$this->_pageStates===null)
        
$this->_pageStates=$this->loadPageStates();
    if(
$value===$defaultValue)
        unset(
$this->_pageStates[$name]);
    else
        
$this->_pageStates[$name]=$value;

    
$params=func_get_args();
    
$this->recordCachingAction('','setPageState',$params);
}

Saves a persistent page state value. A page state is a variable that is persistent across POST requests of the same page. In order to use persistent page states, the form(s) must be stateful which are generated using CHtml::statefulForm.

setPageTitle() method

public void setPageTitle(string $value)
$value string the page title.
Source Code: framework/web/CController.php#1012 (show)
public function setPageTitle($value)
{
    
$this->_pageTitle=$value;
}

© 2008–2017 by Yii Software LLC
Licensed under the three clause BSD license.
http://www.yiiframework.com/doc/api/1.1/CController