CAccessControlFilter

Package system.web.auth
Inheritance class CAccessControlFilter » CFilter » CComponent
Implements IFilter
Since 1.0
Source Code framework/web/auth/CAccessControlFilter.php
CAccessControlFilter performs authorization checks for the specified actions.

By enabling this filter, controller actions can be checked for access permissions. When the user is not denied by one of the security rules or allowed by a rule explicitly, he will be able to access the action.

For maximum security consider adding
array('deny')
as a last rule in a list so all actions will be denied by default.

To specify the access rules, set the rules property, which should be an array of the rules. Each rule is specified as an array of the following structure:
array(
  'allow',  // or 'deny'

  // optional, list of action IDs (case insensitive) that this rule applies to
  // if not specified or empty, rule applies to all actions
  'actions'=>array('edit', 'delete'),

  // optional, list of controller IDs (case insensitive) that this rule applies to
  'controllers'=>array('post', 'admin/user'),

  // optional, list of usernames (case insensitive) that this rule applies to
  // Use * to represent all users, ? guest users, and @ authenticated users
  'users'=>array('thomas', 'kevin'),

  // optional, list of roles (case sensitive!) that this rule applies to.
  'roles'=>array('admin', 'editor'),

  // since version 1.1.11 you can pass parameters for RBAC bizRules
  'roles'=>array('updateTopic'=>array('topic'=>$topic))

  // optional, list of IP address/patterns that this rule applies to
  // e.g. 127.0.0.1, 127.0.0.*
  'ips'=>array('127.0.0.1'),

  // optional, list of request types (case insensitive) that this rule applies to
  'verbs'=>array('GET', 'POST'),

  // optional, a PHP expression whose value indicates whether this rule applies
  // The PHP expression will be evaluated using evaluateExpression.
  // A PHP expression can be any PHP code that has a value. To learn more about what an expression is,
  // please refer to the php manual.
  'expression'=>'!$user->isGuest && $user->level==2',

  // optional, the customized error message to be displayed
  // This option is available since version 1.1.1.
  'message'=>'Access Denied.',

  // optional, the denied method callback name, that will be called once the
  // access is denied, instead of showing the customized error message. It can also be
  // a valid PHP callback, including class method name (array(ClassName/Object, MethodName)),
  // or anonymous function (PHP 5.3.0+). The function/method signature should be as follows:
  // function foo($user, $rule) { ... }
  // where $user is the current application user object and $rule is this access rule.
  // This option is available since version 1.1.11.
  'deniedCallback'=>'redirectToDeniedMethod',
)

Public Properties

Property Type Description Defined By
message string the error message to be displayed when authorization fails. CAccessControlFilter
rules array list of access rules. CAccessControlFilter

Public Methods

Method Description Defined By
__call() Calls the named method which is not a class method. CComponent
__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
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
canGetProperty() Determines whether a property can be read. CComponent
canSetProperty() Determines whether a property can be set. CComponent
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
evaluateExpression() Evaluates a PHP expression or callback under the context of this component. CComponent
filter() Performs the filtering. CFilter
getEventHandlers() Returns the list of attached event handlers for an event. CComponent
getRules() Returns list of access rules. CAccessControlFilter
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 filter. CFilter
raiseEvent() Raises an event. CComponent
setRules() Sets list of access rules. CAccessControlFilter

Protected Methods

Method Description Defined By
accessDenied() Denies the access of the user. CAccessControlFilter
postFilter() Performs the post-action filtering. CFilter
preFilter() Performs the pre-action filtering. CAccessControlFilter
resolveErrorMessage() Resolves the error message to be displayed. CAccessControlFilter

Property Details

message property (available since v1.1.1)

public string $message;

the error message to be displayed when authorization fails. This property can be overridden by individual access rule via CAccessRule::message. If this property is not set, a default error message will be displayed.

rules property

public array getRules()
public void setRules(array $rules)

list of access rules.

Method Details

accessDenied() method

protected void accessDenied(IWebUser $user, string $message)
$user IWebUser the current user
$message string the error message to be displayed
Source Code: framework/web/auth/CAccessControlFilter.php#178 (show)
protected function accessDenied($user,$message)
{
    if(
$user->getIsGuest())
        
$user->loginRequired();
    else
        throw new 
CHttpException(403,$message);
}

Denies the access of the user. This method is invoked when access check fails.

getRules() method

public array getRules()
{return} array list of access rules.
Source Code: framework/web/auth/CAccessControlFilter.php#94 (show)
public function getRules()
{
    return 
$this->_rules;
}

preFilter() method

protected boolean preFilter(CFilterChain $filterChain)
$filterChain CFilterChain the filter chain that the filter is on.
{return} boolean whether the filtering process should continue and the action should be executed.
Source Code: framework/web/auth/CAccessControlFilter.php#128 (show)
protected function preFilter($filterChain)
{
    
$app=Yii::app();
    
$request=$app->getRequest();
    
$user=$app->getUser();
    
$verb=$request->getRequestType();
    
$ip=$request->getUserHostAddress();

    foreach(
$this->getRules() as $rule)
    {
        if((
$allow=$rule->isUserAllowed($user,$filterChain->controller,$filterChain->action,$ip,$verb))>0// allowed
            
break;
        elseif(
$allow<0// denied
        
{
            if(isset(
$rule->deniedCallback))
                
call_user_func($rule->deniedCallback$rule);
            else
                
$this->accessDenied($user,$this->resolveErrorMessage($rule));
            return 
false;
        }
    }

    return 
true;
}

Performs the pre-action filtering.

resolveErrorMessage() method (available since v1.1.1)

protected string resolveErrorMessage(CAccessRule $rule)
$rule CAccessRule the access rule
{return} string the error message
Source Code: framework/web/auth/CAccessControlFilter.php#161 (show)
protected function resolveErrorMessage($rule)
{
    if(
$rule->message!==null)
        return 
$rule->message;
    elseif(
$this->message!==null)
        return 
$this->message;
    else
        return 
Yii::t('yii','You are not authorized to perform this action.');
}

Resolves the error message to be displayed. This method will check message and CAccessRule::message to see what error message should be displayed.

setRules() method

public void setRules(array $rules)
$rules array list of access rules.
Source Code: framework/web/auth/CAccessControlFilter.php#102 (show)
public function setRules($rules)
{
    foreach(
$rules as $rule)
    {
        if(
is_array($rule) && isset($rule[0]))
        {
            
$r=new CAccessRule;
            
$r->allow=$rule[0]==='allow';
            foreach(
array_slice($rule,1) as $name=>$value)
            {
                if(
$name==='expression' || $name==='roles' || $name==='message' || $name==='deniedCallback')
                    
$r->$name=$value;
                else
                    
$r->$name=array_map('strtolower',$value);
            }
            
$this->_rules[]=$r;
        }
    }
}

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