Permission class

From Cloudrexx Development Wiki
Jump to: navigation, search

The Permission class is a set of requirements the current user and request needs to fulfill in order to get a permission.

Define a permission requirements set

The requirements for a permission are passed as arguments when instantiating a Permission instance. All arguments are optional, however the following defaults are set:

$permission = new \Cx\Core_Modules\Access\Model\Entity\Permission(
    $allowedProtocols = ['http', 'https'],
    $allowedMethods = ['get', 'post'],
    $requiresLogin = true,
    $validUserGroups = [],
    $validAccessIds = [],
    $callback = null
);

Set arguments as required:

  1. allowedProtocols: A combination of allowed protocols (in lowercase): http / https
    If request method is cli then the protocol check will be skipped/ignored.
  2. allowedMethods: A combination of allowed request methods (in lowercase): get / post / put / patch / update / delete / options / head / cli (Use to allow access over CLI)
  3. requiresLogin: true by default. If set to false, no login is required to get this permission. Note: setting validUserGroups or validAccessIds implies requiresLogin=true.
  4. validUserGroups: List of group IDs. The user needs to be in one of those groups in order to get access or the user is an administrator (flag admin is set). If the list is empty it is ignored. Setting validUserGroups implies requiresLogin=true.
  5. validAccessIds: List of access IDS. The user needs have been granted at least one of these IDs in order to get access or the user is an administrator (flag admin is set). If the list is empty it is ignored. Setting validAccessIds implies requiresLogin=true.
  6. callback: A custom callback can be specified in order to check for additional requirements. Please see Specify a requirement using a callback.

When a Permission is evaluated, then each requirement is validated in the above mentioned order. As soon as one requirement evaluates to false the validation process is immediately stopped and the Permission won't be granted (→ Permission::hasAccess() will emmit false).


Specify a requirement using a callback

In order to specify a callback you may pass an instance of \Cx\Core_Modules\Access\Model\Entity\Callback or an anonymous function. If you want to persist a Permission instance with callback, then the callback must be a persistable object. The callback will be called with one argument of type array. The data and structure of the passed array depends on the element the Permission instance is being checked on:

Element Passed Argument
Backend Component Section Empty array
Exposed Method called as CLI command One dimensional array of arguments passed as <params> when calling the Exposed Method as CLI command
Exposed Method called over a HTTP endpoint
Exposed Method called through the Javascript Framework Two dimensional array where the first dimension consists of the following elements:
  • get: HTTP-GET arguments of method call
  • post HTTP-POST arguments of method call
  • response Response object of the current request
Exposed Method called as a DataSource N/A
Custom $params as passed to Permission::hasAccess($params)

The callback must return true to grant access or false to deny access.

Check requirements

In order to check if the requirements are fulfilled you can simply call

$permission->hasAccess($params);

$params is optional. It will get passed to the registered callback (if any).

Virtual vs. non-virtual Permission instances

By default Permission instances are virtual. They can be manually set to be non-virtual (if you need to persist one) by calling

$permission->setVirtual(false);

Please note that this only works if there's no callback specified or the callback is serializable.