This tutorial is designed to teach you the concepts and terminology needed to work with PHP-RBAC, explain the basics of working with PHP-RBAC, and then finish off with a quick reference of the tasks you can perform with PHP-RBAC.

Key concepts and terminology you'll need to understand while working with PHP-RBAC.

Permissions, Roles and Users

When working with PHP-RBAC you will be working with three things: Permissions, Roles and Users

Permissions

Permissions are essentially 'labels' stored in PHP-RBAC's database. They can be used to allow/restrict access to a resource. It is up to your application logic to define what a Permission means and how it is enforced.

Examples: 'can_delete_posts', 'restricted_content', 'print_balance'

Roles

A Role is a 'label' that signifies a Users responsibilities.

Examples: 'forum_moderator', 'accounts_payable', 'lead_engineer'

Users

A User is defined in your application logic, outside of PHP-RBAC. PHP-RBAC uses the User's Id to make Role assignments.

Note: When we mention 'Entity' we mean either a Role or Permission.

Role/Permission and Role/User assignment

PHP-RBAC uses assignment to manage the relation of Permissions->Roles->Users.

Simply put, Permissions are assigned to Roles, and Roles are assigned to Users.

Permission and Role Hierarchies

Both Permissions and Roles are hierarchical. This means that both Entities can have an unlimited amount of children Entities.

When you assign a Permission to a Role, that Role not only inherits the Permission being assigned, but also all children of the assigned Permission.

The same goes for User->Role assignments. When a Role is assigned to a User, the User not only inherits the Role being assigned, but also all children of the assigned Role.

Id, Title, Path

A Role or Permission can be referenced three ways: By Id, Title, Path

Id

An Id is simply an auto-incremented integer value created when you create an Entity. All Entities can be referenced by using its Id.

Example:

$perm_id = 5;

Title

A Title is a simple string value. If a Title is used to create an Entity you will be able to refer to it using it's Title or Id.

Example:

$perm_title = 'edit_post';

Path

A Path is a string value that contains a hierarchy of Entities separated by a '/' (forward slash). If a Path is used to create an Entity you will be able to refer to it using it's Path, Title or Id.

Example:

$role_path = '/admin/forum_moderator/forum_user';

When this Path is created it will create the 'admin', 'forum_moderator' and 'forum_user' Roles with those Titles. If a Role in this Path already exists PHP-RBAC will not recreate it.

Paths are the easiest way to reference Entities, although retrieving Entities using Paths is slower than using Id's or Titles.

Let's get into the code!

Examining the 'PhpRbac\Rbac' Class

---

Instantiate a 'PhpRbac\Rbac' Object

After Autoloading PHP-RBAC you can create an Rbac Object.

With a 'use' statement:

use PhpRbac\Rbac;
$rbac = new Rbac();

Without a 'use' statement, outside of a namespace:

$rbac = new PhpRbac\Rbac();

Without a 'use' statement, inside of another namespace (notice the leading backslash):

$rbac = new \PhpRbac\Rbac();

---

The structure of an PhpRbac\Rbac object

The $rbac object contains three Objects and four Methods:

Objects:

$rbac->Permissions
$rbac->Roles
$rbac->Users

Methods:

$rbac->assign()
$rbac->check()
$rbac->enforce()
$rbac->reset() // Should be used mainly for testing purposes

Creating Permissions and Roles

You can create Entities using a Title or a Path.

---

With a Title

Creating an Entity using a Title:

// Create a Permission
$perm_id = $rbac->Permissions->add('delete_posts', 'Can delete forum posts');

// Create a Role
$role_id = $rbac->Roles->add('forum_moderator', 'User can moderate forums');

---

With a Path

Creating an Entity using a Path:

$perm_descriptions = array(
    'Can delete users',
    'Can edit user profiles',
    'Can view users'
);

$rbac->Permissions->addPath('/delete_users/edit_users/view_users', $perm_descriptions);

$role_descriptions = array(
    'Forum Administrator',
    'Forum Moderator',
    'Registered Forum Member'
);

$rbac->Roles->addPath('/admin/forum_moderator/forum_member', $role_descriptions);

Creating Role/Permission Associations

Assigning Permissions to Roles using Entity Object:

// Create Role and Permission
$perm_id = $rbac->Permissions->add('delete_posts', 'Can delete forum posts');
$role_id = $rbac->Roles->add('forum_moderator', 'User can moderate forums');

// The following are equivalent statements
$rbac->Permissions->assign($role_id, $perm_id);
$rbac->Roles->assign($role_id, $perm_id);

Alternate Method:

// Create Role and Permission
$perm_id = $rbac->Permissions->add('delete_posts', 'Can delete forum posts');
$role_id = $rbac->Roles->add('forum_moderator', 'User can moderate forums');

// Assign Permission to Role
$rbac->assign($role_id, $perm_id);

Creating User/Role Associations

Assigning Roles to Users:

// Create Role and Permission
$perm_id = $rbac->Permissions->add('delete_posts', 'Can delete forum posts');
$role_id = $rbac->Roles->add('forum_moderator', 'User can moderate forums');

// Assign Permission to Role
$rbac->Roles->assign($role_id, $perm_id);

// Assign Role to User (The UserID is provided by the application's User Management System)
$rbac->Users->assign($role_id, 5);

Use these Methods to make changes to Entities.

Editing Existing Entities

Editing Entities:

// Get Entity Id's
$perm_id = $rbac->Permissions->returnId('delete_posts');
$role_id = $rbac->Roles->returnId('forum_moderator');

// Edit Entities
$rbac->Permissions->edit($perm_id, 'delete_own_posts', 'Can delete posts they create');
$rbac->Roles->edit('forum_spam_moderator', 'User is responsible for spam moderation);

Removing Existing Permissions and Roles

Removing Permissions:

// Get Permission Id
$perm_id = $rbac->Permissions->returnId('delete_posts');

// Remove single Permission
$rbac->Permissions->remove($perm_id);

// Remove Permission and all descendants
$rbac->Permissions->remove($perm_id, true);

Removing Roles:

// Get Permission Id
$role_id = $rbac->Roles->returnId('forum_moderator');

// Remove single Role
$rbac->Roles->remove($role_id);

// Remove Role and all descendants
$rbac->Roles->remove($role_id, true);

Unassigning Role/Permission Associations

Unassign a single Permission/Role assignment:

// Unassign a single Permission/Role assignment using Titles.
// The following are equivalent statements.
$rbac->Permissions->unassign('forum_moderator', 'delete_posts');
$rbac->Roles->unassign('forum_moderator', 'delete_posts');

Unassign all Permissions assigned to a Role:

// Get Role Id
$role_id = $rbac->Roles->returnId('forum_moderator');

// Unassign all Permissions assigned to a Role
$rbac->Roles->unassignPermissions($role_id);

Unassign all Permission/Role assignments related to Permission:

// Get Permission Id
$perm_id = $rbac->Permissions->returnId('delete_posts');

// Unassign all Permission/Role assignments related to Permission
$rbac->Permissions->unassignRoles($perm_id);

Unassigning User/Role Associations

Unassign a Role belonging to a User:

// Unassign 'forum_user' Role assigned to a User using the Role's Path
$rbac->Users->unassign('/admin/forum_moderator/forum_user', 26);

Use these Methods to make sure a User has a Permission or Role.

Checking for a User’s Roles and Permissions

Make sure a User has a Role:

// Get Role Id
$role_id = $rbac->Roles->returnId('forum_moderator');

// Make sure User has 'forum_user' Role
$rbac->Users->hasRole($role_id, 105);

Checks whether a User has a Permission or not:

// Check to see if User has 'delete_posts' Permission
$rbac->check('delete_posts', 105);

Enforce a Permission on a User:

// Will return a 403 HTTP status code and an 'Access Denied' message if User does not have Role
$rbac->enforce('forum_moderator', 105);

This is a good start regarding the proper use of PHP-RBAC. For in depth knowledge regarding PHP-RBAC please refer to the PHP-RBAC API.