HumHub Documentation (unofficial)

ControllerAccess extends BaseObject
in package

ControllerAccess contains the actual logic to verify whether or not a user can access a controller action by means of a given set of access rules.

By default the AccessCheck will use the current logged in user as permission subject.

The actual permission rule verification is handled by the [[run()]] function.

Subclasses can extend the set of available validators by calling [[registerValidator()]] and providing a validator setting array as:

public function init()
{
   parent::init();
   $this->registerValidator([
     self::RULE_MY_RULE => 'validateMyRule',
     'reason' => Yii::t('error', 'My validation rule could not be verified.'),
     'code' => 401
    ]);
}

The previous example registered a new validator responsible for validating rules with the name validateMyRule and validation handler function validateMyRule which defines an handler method within the subclass.

Custom Validators can also be added by means of a Validator class as in the following example:

$this->registerValidator(MyValidator::class);

where MyValidator is a subclass of [[\humhub\components\access\AccessValidator]]

A single rule is provided as a array. If not specified otherwise, a rule supports the following base format:

['ruleName', 'actions' => ['action1', 'action2']]

or

['ruleName' => ['action1', action2]]

Note: the second format is not supported by all rules e.g. permission rule

If no action array is provided, the rule is considered to be controller global and will be verified for all actions.

If a rule for a given name could not be found, the ControllerAccess tries to determine a custom rule validator set by the controller itself:

['validateMyCustomRule', 'someParameter' => $value]

will search for controller validator function validateMyCustomRule:

public function validateTestRule($rule, $access)
{
    if($rule['someParameter'] == 'valid') {
         $access->code = 401;
         $access->reason = 'Not authorized!';
         return false;
    }

    return true;
}

By defining the [[fixedRules]] array property a ControllerAccess can define rules which are always applied, this property (or [[getFixedRules()]] function may be overwritten by subclasses.

The following rules are available by default:

  • admin: The user has to be system admin to access a action
  • permission Group Permission check
  • login: The user has to be logged in to access a action
  • strict: Will check for guest users against the guest users allowed setting
  • post: Will only accept post requests for the given actions
  • json: Will handle json result requests by setting Yii::$app->response->format = 'json'
  • ajax: Allows only AJAX requests. See: Yii::$app->request->isAjax
  • disabledUser: Checks if the given user is a disabled user (fixed)
  • unapprovedUser: Checks if the given user is a unapproved user (fixed)
Tags
see
AccessValidator
since
1.2.2

Table of Contents

Constants

ACTION_SETTING_TYPE_BOTH  = 1
Allows the action rule setting by extra option ['myRule', 'actions' => ['action1', 'action2']] or immediate ['myRule' => ['action1', 'action2']]
ACTION_SETTING_TYPE_OPTION_ONLY  = 0
Allows the action rule setting only by extra option ['myRule', 'actions' => ['action1', 'action2']]
RULE_ADMIN_ONLY  = 'admin'
Only admins have access to the given set of actions e.g.: ['admin' => ['action1']]
RULE_AJAX_ONLY  = 'ajax'
Only AJAX request is allowed for the actions
RULE_DISABLED_USER  = 'disabledUser'
Check guest if user is disabled
RULE_JSON  = 'json'
Make sure response type is json
RULE_LOGGED_IN_ONLY  = 'login'
Only logged in user have access e.g.: ['login' => ['action1', 'action2']]
RULE_MAINTENANCE_MODE  = 'maintenance'
Maintenance mode is active
RULE_MUST_CHANGE_PASSWORD  = 'mustChangePassword'
Check guest if user must change password
RULE_PERMISSION  = 'permission'
Validate against a given set of permissions e.g.: ['permission' => [MyPermission::class], 'actions' => ['action1']]
RULE_POST  = 'post'
Check guest if request method is post
RULE_STRICT  = 'strict'
Check guest mode e.g.: ['strict'] (mainly used as global)
RULE_UNAPPROVED_USER  = 'unapprovedUser'
Check guest if user is unnapproved

Properties

$action  : string
$code  : int
$codeCallback  : string
$owner  : Controller
$reason  : string
$user  : User
$fixedRules  : array<string|int, mixed>
$rules  : array<string|int, mixed>
$validators  : array<string|int, mixed>

Methods

__call()  : mixed
Calls the named method which is not a class method.
__construct()  : mixed
Constructor.
__get()  : mixed
Returns the value of an object property.
__isset()  : bool
Checks if a property is set, i.e. defined and not null.
__set()  : mixed
Sets value of an object property.
__unset()  : mixed
Sets an object property to null.
canGetProperty()  : bool
Returns a value indicating whether a property can be read.
canSetProperty()  : bool
Returns a value indicating whether a property can be set.
className()  : string
Returns the fully qualified name of this class.
getMaintenanceModeWarningText()  : string
getRules()  : array<string|int, mixed>
hasMethod()  : bool
Returns a value indicating whether a method is defined.
hasProperty()  : bool
Returns a value indicating whether a property is defined.
init()  : mixed
Initializes the object.
isAdmin()  : mixed
isGuest()  : bool
run()  : bool
Runs the current $rule setting against all available validators
setRules()  : mixed
Sets the current set of rules.
validateAdminOnly()  : bool
validateAjaxOnlyRequest()  : mixed
validateDisabledUser()  : bool
validateJsonResponse()  : bool
validateLoggedInOnly()  : bool
validateMaintenanceMode()  : bool
validateMustChangePassword()  : bool
validatePostRequest()  : mixed
validateStrictMode()  : bool
validateUnapprovedUser()  : bool
findValidator()  : mixed
getCustomValidator()  : mixed
getFixedRules()  : array<string|int, mixed>
getName()  : mixed|null
Extracts the ruleName from a given rule option array.
registerValidator()  : mixed
Adds a new validator to the available validators and sets some default values.

Constants

ACTION_SETTING_TYPE_BOTH

Allows the action rule setting by extra option ['myRule', 'actions' => ['action1', 'action2']] or immediate ['myRule' => ['action1', 'action2']]

public mixed ACTION_SETTING_TYPE_BOTH = 1

ACTION_SETTING_TYPE_OPTION_ONLY

Allows the action rule setting only by extra option ['myRule', 'actions' => ['action1', 'action2']]

public mixed ACTION_SETTING_TYPE_OPTION_ONLY = 0

RULE_ADMIN_ONLY

Only admins have access to the given set of actions e.g.: ['admin' => ['action1']]

public mixed RULE_ADMIN_ONLY = 'admin'

RULE_AJAX_ONLY

Only AJAX request is allowed for the actions

public mixed RULE_AJAX_ONLY = 'ajax'

RULE_DISABLED_USER

Check guest if user is disabled

public mixed RULE_DISABLED_USER = 'disabledUser'

RULE_JSON

Make sure response type is json

public mixed RULE_JSON = 'json'

RULE_LOGGED_IN_ONLY

Only logged in user have access e.g.: ['login' => ['action1', 'action2']]

public mixed RULE_LOGGED_IN_ONLY = 'login'

RULE_MAINTENANCE_MODE

Maintenance mode is active

public mixed RULE_MAINTENANCE_MODE = 'maintenance'

RULE_MUST_CHANGE_PASSWORD

Check guest if user must change password

public mixed RULE_MUST_CHANGE_PASSWORD = 'mustChangePassword'
Tags
since
1.8

RULE_PERMISSION

Validate against a given set of permissions e.g.: ['permission' => [MyPermission::class], 'actions' => ['action1']]

public mixed RULE_PERMISSION = 'permission'

RULE_POST

Check guest if request method is post

public mixed RULE_POST = 'post'

RULE_STRICT

Check guest mode e.g.: ['strict'] (mainly used as global)

public mixed RULE_STRICT = 'strict'

RULE_UNAPPROVED_USER

Check guest if user is unnapproved

public mixed RULE_UNAPPROVED_USER = 'unapprovedUser'

Properties

$code

public int $code

http code, can be changed in verify checks for specific error codes

$codeCallback

public string $codeCallback

Name of callback method to run after failed validation

Tags
since
1.8

$owner

public Controller $owner

owner object of this ControllerAccess the owner is mainly used to find custom validation handler

$reason

public string $reason

actual decline message, can be changed in verify checks for specific error messages

$fixedRules

protected array<string|int, mixed> $fixedRules = [[self::RULE_DISABLED_USER], [self::RULE_UNAPPROVED_USER], [self::RULE_MUST_CHANGE_PASSWORD], [self::RULE_MAINTENANCE_MODE]]

fixed rules will always be added to the current rule set

$rules

protected array<string|int, mixed> $rules = []

access rule array

$validators

protected array<string|int, mixed> $validators = []

defines all available validators, this list can be extended by calling registerValidator()

Methods

__call()

Calls the named method which is not a class method.

public __call(string $name, array<string|int, mixed> $params) : mixed

Do not call this method directly as it is a PHP magic method that will be implicitly called when an unknown method is being invoked.

Parameters
$name : string

the method name

$params : array<string|int, mixed>

method parameters

Tags
throws
UnknownMethodException

when calling unknown method

Return values
mixed —

the method return value

__construct()

Constructor.

public __construct([array<string|int, mixed> $config = [] ]) : mixed

The default implementation does two things:

  • Initializes the object with the given configuration $config.
  • Call [[init()]].

If this method is overridden in a child class, it is recommended that

  • the last parameter of the constructor is a configuration array, like $config here.
  • call the parent implementation at the end of the constructor.
Parameters
$config : array<string|int, mixed> = []

name-value pairs that will be used to initialize the object properties

__get()

Returns the value of an object property.

public __get(string $name) : mixed

Do not call this method directly as it is a PHP magic method that will be implicitly called when executing $value = $object->property;.

Parameters
$name : string

the property name

Tags
throws
UnknownPropertyException

if the property is not defined

throws
InvalidCallException

if the property is write-only

see
__set()
Return values
mixed —

the property value

__isset()

Checks if a property is set, i.e. defined and not null.

public __isset(string $name) : bool

Do not call this method directly as it is a PHP magic method that will be implicitly called when executing isset($object->property).

Note that if the property is not defined, false will be returned.

Parameters
$name : string

the property name or the event name

Tags
see
https://www.php.net/manual/en/function.isset.php
Return values
bool —

whether the named property is set (not null).

__set()

Sets value of an object property.

public __set(string $name, mixed $value) : mixed

Do not call this method directly as it is a PHP magic method that will be implicitly called when executing $object->property = $value;.

Parameters
$name : string

the property name or the event name

$value : mixed

the property value

Tags
throws
UnknownPropertyException

if the property is not defined

throws
InvalidCallException

if the property is read-only

see
__get()

__unset()

Sets an object property to null.

public __unset(string $name) : mixed

Do not call this method directly as it is a PHP magic method that will be implicitly called when executing unset($object->property).

Note that if the property is not defined, this method will do nothing. If the property is read-only, it will throw an exception.

Parameters
$name : string

the property name

Tags
throws
InvalidCallException

if the property is read only.

see
https://www.php.net/manual/en/function.unset.php

canGetProperty()

Returns a value indicating whether a property can be read.

public canGetProperty(string $name[, bool $checkVars = true ]) : bool

A property is readable if:

  • the class has a getter method associated with the specified name (in this case, property name is case-insensitive);
  • the class has a member variable with the specified name (when $checkVars is true);
Parameters
$name : string

the property name

$checkVars : bool = true

whether to treat member variables as properties

Tags
see
canSetProperty()
Return values
bool —

whether the property can be read

canSetProperty()

Returns a value indicating whether a property can be set.

public canSetProperty(string $name[, bool $checkVars = true ]) : bool

A property is writable if:

  • the class has a setter method associated with the specified name (in this case, property name is case-insensitive);
  • the class has a member variable with the specified name (when $checkVars is true);
Parameters
$name : string

the property name

$checkVars : bool = true

whether to treat member variables as properties

Tags
see
canGetProperty()
Return values
bool —

whether the property can be written

className()

Returns the fully qualified name of this class.

public static className() : string
Tags
deprecated

since 2.0.14. On PHP >=5.5, use ::class instead.

Return values
string —

the fully qualified name of this class.

getMaintenanceModeWarningText()

public static getMaintenanceModeWarningText([string $beforeCustomInfo = ' ' ]) : string
Parameters
$beforeCustomInfo : string = ' '
Tags
since
1.8
Return values
string —

returns the maintenance mode warning text

getRules()

public getRules() : array<string|int, mixed>
Return values
array<string|int, mixed> —

set of rules

hasMethod()

Returns a value indicating whether a method is defined.

public hasMethod(string $name) : bool

The default implementation is a call to php function method_exists(). You may override this method when you implemented the php magic method __call().

Parameters
$name : string

the method name

Return values
bool —

whether the method is defined

hasProperty()

Returns a value indicating whether a property is defined.

public hasProperty(string $name[, bool $checkVars = true ]) : bool

A property is defined if:

  • the class has a getter or setter method associated with the specified name (in this case, property name is case-insensitive);
  • the class has a member variable with the specified name (when $checkVars is true);
Parameters
$name : string

the property name

$checkVars : bool = true

whether to treat member variables as properties

Tags
see
canGetProperty()
see
canSetProperty()
Return values
bool —

whether the property is defined

isGuest()

public isGuest() : bool
Return values
bool —

Checks if the given $user is set.

run()

Runs the current $rule setting against all available validators

public run() : bool
Return values
bool

setRules()

Sets the current set of rules.

public setRules([array<string|int, mixed> $rules = [] ]) : mixed

Note: This will merge the given set of rules with the fixed rules.

Parameters
$rules : array<string|int, mixed> = []

sets th

validateAdminOnly()

public validateAdminOnly() : bool
Return values
bool —

makes sure the current user has administration rights

validateAjaxOnlyRequest()

public validateAjaxOnlyRequest() : mixed
Return values
mixed —

checks if the current request is an ajax request

validateDisabledUser()

public validateDisabledUser() : bool
Return values
bool —

checks if the current user is a disabled user

validateJsonResponse()

public validateJsonResponse() : bool
Return values
bool —

makes sure the response type is json

validateLoggedInOnly()

public validateLoggedInOnly() : bool
Return values
bool —

makes sure if the current user is loggedIn

validateMaintenanceMode()

public validateMaintenanceMode() : bool
Tags
since
1.8
Return values
bool —

makes sure the current user has an access on maintenance mode

validateMustChangePassword()

public validateMustChangePassword() : bool
Tags
since
1.8
Return values
bool —

checks if the current user must change password

validatePostRequest()

public validatePostRequest() : mixed
Return values
mixed —

checks if the current request is a post request

validateStrictMode()

public validateStrictMode() : bool
Return values
bool —

checks if guest mode is activated for guestaccess

validateUnapprovedUser()

public validateUnapprovedUser() : bool
Return values
bool —

checks if the current user is an unapproved user

findValidator()

protected findValidator(mixed $ruleName) : mixed
Parameters
$ruleName : mixed

getCustomValidator()

protected getCustomValidator(mixed $ruleName) : mixed
Parameters
$ruleName : mixed

getFixedRules()

protected getFixedRules() : array<string|int, mixed>
Return values
array<string|int, mixed> —

returns array of rules which will always be added to the rule set

getName()

Extracts the ruleName from a given rule option array.

protected getName(mixed $arr) : mixed|null
Parameters
$arr : mixed
Return values
mixed|null

registerValidator()

Adds a new validator to the available validators and sets some default values.

protected registerValidator(mixed $options) : mixed

A validator shoud have the following form

['ruleName' => 'handler', 'code' => 401, 'reason' => 'Some message in case the validation failed']

to allow other direct settings required by the action validator e.g. direct permission settings.

Parameters
$options : mixed
Tags
throws
InvalidConfigException 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results