Front-end permissions allow administrators to control which member groups can perform which actions (for example, being able to view the content items inside the node, creating new content items, commenting on content items, and so forth).
Your nodes can have up to 7 different permissions, customizable depending on the needs of your application.
Implementing permissions changes the behavior of a few node methods, and adds several new permission-based methods you can call.
Configuring your model
In order to use front-end permissions, your model needs to extend the \IPS\Node\Permissions interface, like so:
class _ExampleModel extends \IPS\Node\Model implements \IPS\Node\Permissions { //... }
Next, there's three properties you need to define on your model.
A unique (to your application) key that represents this set of permissions in the suite, e.g. 'forums' or 'categories'.
Your application key, enabling the suite to associate your permissions to your application correctly.
This property is an array that maps the permission keys you want to define to the permission index, which must either the value 'view' or an integer between 2 and 7. As noted above, you must at least define a key with view as the value; you don't need to define all 7 permissions if you don't plan on using them. As an example:
$permissionMap = array( 'view' => 'view', 'read' => 2, 'add' => 3, 'reply' => 4, 'export' => 5, 'download' => 6 );
In this example, we define the required view key, as well as five other keys our application will use. The keys you define here are the means by which you will check permissions in other methods later, and also form part of the language string keys you'll define to name your permissions.
Some keys are required if your models implement certain other functionality:
- view (can see the node) is always required (defined as the value 'view')
- read (can read content items) is always required
- add (can add content items) is always required
- reply (can reply to content items) is required if your content items can be commented on
- review (can review content items) is required if your content items support reviews
The permission matrix interface in the AdminCP will show the permissions in the order you define them here. The column names are defined by the language string with the key perm__{$key} where $key is the key from the above array, so you will need to add these to your application's lang.php file.
Changed behaviors after implementing \IPS\Node\Permissions
Once implemented in your model, the following three methods will (by default) only return the child nodes that the currently-logged in member has permission to view:
- hasChildren()
- childrenCount()
- children()
These methods take two optional parameters that allow you to control this behavior. The parameter signature is the same for all three; children() is shown here as an example.
-
$permissionCheck (string, optional, default 'view')
Determines which permission is checked when working with children; should be one of the permission keys you defined earlier. The view permission is used if none is specified. -
$member (\IPS\Member, optional)
Controls which members' permissions are checked. By default, the currently-logged in member is used, but you can override this and specify a different member here.
In addition to the above, the loadAndCheckPerms() method will now throw an OutOfRangeException exception if a node is loaded that the currently-logged in member doesn't have permission to view.
Additional methods
Returns true if the user has the requested permission on any node that uses this model.
-
$permission (string, required)
The permission type to check. -
$member (\IPS\Member, optional)
If provided, uses this member's permissions when performing the check. By default, the currently-logged in member is used.
Returns true if the user has the requested permission on the node object.
-
$permission (string, required)
The permission type to check. -
$member (\IPS\Member, optional)
If provided, uses this member's permissions when performing the check. By default, the currently-logged in member is used.
Returns an array representing the node's row from the core_permission_index table, which contains which groups have which permissions. The array contains the keys perm_view and perm_2 through perm_7, representing the permission types you configured. Each of these values is a comma-separated list of group IDs that have this permission. For example:
$permissions = $myNode->permissions(); $groupsWithPermission = explode( ",", $permissions['perm_2'] ); // perm_2 might be 'read' in our node foreach( $groupsWithPermission as $id ) { echo "Group #{$id} has permission to read items in this node"; }
This method is primarily useful when constructing queries based on groups that have a given permission.
Report Document