Core:ACL Class

From Habari Project

Jump to: navigation, search

The default Habari ACL class implements groups, and group permissions:

  • Users are assigned to one or more groups.
  • Groups are assigned one or more permissions.
  • Permissions are either granted or denied.

Granted permissions are additive: membership in any group that grants a permission means you have that permission. Denied permissions override granted permissions: membership in any group that denies that permission denies the user that permission, even if another group grants that permission.

The acl class provides a programmatic mechanism for creating, destroying, and interrogating permissions. The Habari installation process creates a set of default permissions, and assigns those to a set of default groups. The user created during installation is assigned full administrative control during installation.

To understand how the ACL system works, and interacts with other Habari classes, let's examine how a fictitious plugin, "X-Ray Specs", might make use of it. The X-Ray Specs (XRS) plugin permits a certain group of people to see comments that are pending moderation. It does not permit these users to approve, delete, or modify these comments: it merely permits them to see unmoderated comments along with approved comments when viewing a post.

Upon activation, the XRS plugin adds a new permission called "xray specs" with the following:

ACL::create_permission('xray specs', "Grants the ability to see comments pending moderation when viewing a post's comments.");

The create_permission() method invokes ACL::permission_exists() first, to make sure that duplicate permissions are not created. The name supplied to the create_permission() method will be normalized to replace spaces and non-alphanumeric characters with underscores, so our "xray specs" permission will become "xray_specs". All ACL methods should normalize the permission names for you, so you can pass either the sanitized version or the friendly "with spaces" version, as you choose.

Once created, the new 'xray specs' permission will be listed with all the other permissions available to be assigned to any group. A user with appropriate permission could either assign the xray specs permission to an existing group, or they could create a new group, add users to that group, and then assign the xray specs permission to that group. To add users to a group, the UserGroup class executes the add() method. When adding permissions to a group, the UserGroup class executes grant() or deny(), depending on whether the permission was granted or denied. For this example, let's say that we created a new group called seers, and assigned the seers group the xray specs permission. We then add a few users to the seers group.

There are several ways that the XRS plugin could perform its task of allowing the seers group to see comments pending moderation. For the sake of convenience, let's assume that the following code is placed at the bottom of your theme's comments.php file:

$user= User::identify()
if ( $user->can('xray specs') ) {
  if ( $post->comments->unapproved ) {
    foreach ( $post->comments->unapproved as $comment ) {

The $user->can() method merely invokes the ACL::user_can() method, which checks whether any of the groups to which the user belongs has been granted or denied the permission in question. If no groups grant the permission, or if one or more groups deny the permission, then the current user will not be permitted to see the comments pending moderation. If one or more groups grant the permission, and no groups deny it, then the current user will be permitted to see the comments pending moderation.

Other Development Pages · Developer Introduction
This page describes a PHP class that is in the Habari software. For more comprehensive technical information visit the API Documentation.
Other Class Pages
Personal tools