PHP-RBAC API

public bool Rbac->assign(mixed $Role, mixed $Permission)

Assign a role to a permission.

Alias for Rbac->{Entity}->assign().

Role

Accepts one of the following:

• int ID
• string Title
• string Path

Permission

Accepts one of the following:

• int ID
• string Title
• string Path

Returns true if successful, false if unsuccessful.

public bool Rbac->check(mixed $Permission, int $UserID = null)

Checks whether a user has a permission or not.

Permission

Accepts one of the following:

• int ID
• string Title
• string Path

UserID

User ID of a user. Must be an int.

Returns true if a user has a permission, false if otherwise.

public mixed Rbac->enforce(mixed $Permission, int $UserID = null)

Enforces a permission on a user.

Permission

Accepts one of the following:

• int ID
• string Title
• string Path

UserID

User ID of a user. Must be an int.

Returns true if the user has the permission.

If the user does not have the permission two things happen:

• A 403 HTTP status code header will be sent to the web client.
• Script execution will terminate with a 'Forbidden: You do not have permission to access this resource.' message.

public bool Rbac->reset(bool $Ensure = false)

Remove all roles, permissions and assignments.

Ensure

This is a required boolean parameter. If true is not passed an \Exception will be thrown.

Returns true if a all roles, permissions and assignments have been reset to default values, false if otherwise.

If $ensure does not equal true, an \Exception will be thrown.

public int Rbac->{Entity}->add(string $Title, string $Description, int $ParentID = null)

Adds a new Role or Permission.

Title

Accepts string Title of the new entry.

Description

Accepts string Description of the new entry.

ParentID

Optional int ID of the parent Entity in the hierarchy.

Returns int ID of the new entry.

public bool Rbac->{Entity}->addPath(string $Path, array $Descriptions = null)

Adds a Path and all its components.

Will not replace or create siblings if a component exists.

Path

Accepts a string Path. Must begin with a / (forward slash).

Example:

$myPath = '/blog_admin/blog_editor/blog_writer/blog_member';

Descriptions

Accepts an array of string Descriptions. Will add with empty Description if not available.

Example:

$pathDescriptions = array(
    'Blog Admin',
    'Blog Editor',
    'Blog Writer',
    'Blog Member'
);

Returns int Number of Entities created (0 if none created).

public bool Rbac->{Entity}->assign(mixed $Role, mixed $Permission)

Assigns a role to a permission (or vice-verse).

Role

Accepts one of the following:

• int ID
• string Title
• string Path

Permission

Accepts one of the following:

• int ID
• string Title
• string Path

Returns true if successful, false if association already exists.

public array Rbac->{Entity}->children(int $ID)

Returns children of an Entity.

ID

int ID of an Entity

Returns a multidimensional array containing all children of the Entity.

public int Rbac->{Entity}->count()

Return count of the entity.

No Parameters.

Returns the int count of created Entities.

// Returns 20 if 20 Permissions have been created
$countPermissions = $rbac->Permissions->count();

// Returns 20 if 20 Roles have been created
$countRoles = $rbac->Roles->count();

public int Rbac->{Entity}->depth(int $ID)

Return depth of an Entity.

ID

Accepts the int ID of an Entity

Returns an int depth of specified Entity.

public array Rbac->{Entity}->descendants(int $ID)

Returns descendants of an Entity, with their depths in integer.

ID

Accepts an int ID of a specific Entity

Returns an array with keys as titles and:

• string Title
• int ID
• int Depth
• string Description

public bool Rbac->{Entity}->edit(int $ID, string $NewTitle = null, string $NewDescription = null)

Edits an Entity, changing the Title and/or Description. Maintains ID.

ID

Accepts the int ID of the Entity you would like to change.

NewTitle

Accepts a new string Title.

NewDescription

Accepts a new string Description.

Returns true if successful, false if the Entity does not exist.

public mixed Rbac->{Entity}->getDescription(int $ID)

Return description of an Entity.

ID

Accepts the int ID of an Entity

Returns the string Description if Entity exists, null if Entity does not exist.

public string Rbac->{Entity}->getPath(int $ID)

Returns the Path of an Entity.

ID

Accepts the int ID of an Entity

Returns the string Path of the specified Entity.

public string Rbac->{Entity}->getTitle(int $ID)

Returns the Title of an Entity.

ID

Accepts the int ID of an Entity

Returns the string Title of the specified Entity.

public array Rbac->{Entity}->parentNode(int $ID)

Returns parent node of an Entity.

ID

Accepts the int ID of an Entity

Returns an array including:

• string Title
• string Description
• int ID

public mixed Rbac->{Entity}->pathId(string $Path)

Returns ID of a Path.

Path

Accepts a string Path

Returns the int ID of the Path if it exists, null if the Path does not exist.

$somePath = '/role1/role2/role3'; // A single slash is root

public mixed Rbac->{Entity}->returnId(string $Entity = null)

Returns the ID of an Entity.

Entity

Accepts one of the following:

• string Title
• string Path

Returns the Entity's ID if successful, null if unsuccessful.

public int Rbac->{Entity}->titleId(string $Title)

Returns the ID belonging to a Title. Returns the ID to the first node found with the specified Title.

Title

Accepts a string Title

Returns the int ID of specified Title. Returns the int ID to the first node found with the specified Title.

public bool Rbac->{Entity}->unassign(mixed $Role, mixed $Permission)

Unassigns a Role-Permission relation.

Role

Accepts one of the following:

• int ID
• string Title
• string Path

Permission

Accepts one of the following:

• int ID
• string Title
• string Path

Returns true if successful, false if unsuccessful.

public int Rbac->{Entity}->reset(bool $Ensure = false)

Reset the table back to its initial state.

Keep in mind that this will not touch relations.

// Resets all Permissions
$rbac->Permissions->reset(true);

// Resets all Roles
$rbac->Roles->reset(true);

Ensure

Accepts true or false. Must be true to work, otherwise an \Exception will be thrown.

Returns the int count of deleted entries.

public int Rbac->{Entity}->resetAssignments(bool $Ensure = false)

Remove all role-permission relations.

Mostly used for testing.

Ensure

Accepts true or false. Must be true to work, otherwise an \Exception will be thrown.

Returns the int count of deleted assignments.

public bool Rbac->Permissions->remove(int $ID, bool $Recursive = false)

Remove Permissions from system.

ID

The int ID of the Permission.

Recursive

If set to true, all descendants of the Permission will also be removed.

Returns true if successful, false if unsuccessful.

public array Rbac->Permissions->roles(mixed $Permission, bool $OnlyIDs = true)

Returns all Roles assigned to a Permission.

Permission

Accepts one of the following:

• int ID
• string Title
• string Path

OnlyIDs

If true, result will be a 1D array of IDs

Returns a 1D or 2D array depending on the parameter $OnlyIDs.

Returns null if no Roles are assigned to specified Permission.

public int Rbac->Permissions->unassignRoles(int $ID)

Unassigns all Roles belonging to a Permission.

ID

Accepts the int ID of the Permission in question.

Returns int number of assignments deleted.

public bool Rbac->Roles->hasPermission(int $Role, integer $Permission)

Checks to see if a Role has a Permission or not.

Role

Accepts the int ID of a Role

Permission

Accepts the int ID of a Permission

Returns true if the specified Role has the specified Permission, false if otherwise.

public mixed Rbac->Roles->permissions(int $Role, bool $OnlyIDs = true)

Returns all Permissions assigned to a Role.

Role

The int ID of the Role you would like to inspect.

OnlyIDs

If set to true, result is a 1D array of Permission ID's.

If set to false the result is a 2d array that includes the ID, Title and Description of Permissions assigned to the Role.

If the parameter $OnlyIDs is set to true, result is a 1D array of Permission ID's.

If the parameter $OnlyIDs is set to false the result is a 2d array that includes the ID, Title and Description of Permissions assigned to the Role.

Returns null if unsuccessful.

public bool Rbac->Roles->remove(int $ID, bool $Recursive = false)

Remove Roles from system.

ID

The int ID of the Role

Recursive

If set to true, all descendants of the Permission will also be removed.

Returns true if successful, false if unsuccessful.

public int Rbac->Roles->unassignPermissions(int $ID)

Unassigns all Permissions belonging to a Role.

ID

Accepts the int ID of the Role in question.

Returns int number of assignments deleted.

public int Rbac->Roles->unassignUsers(int $ID)

Unassign all Users that have a certain Role.

ID

Accepts the int ID of a Role

Returns int number of assignments deleted.

public mixed Rbac->Users->allRoles(int $UserID = null)

Returns all Roles of a User.

UserID

Accepts the int ID of a User (Not optional)

Throws RbacUserNotProvidedException if not provided

Returns an array of all Roles assigned to the User.

Returns null if no Roles are assigned to the User.

public bool Rbac->Users->assign(mixed $Role, int $UserID = null)

Assigns a role to a user

Role

Accepts one of the following:

• int ID
• string Title
• string Path

UserID

Accepts an int UserID, provided from external User Management System.

Use 0 for Guest.

Returns true if the assignment was created successfuly.

Returns false if the assignment already exists.

Throws \RbacUserNotProvidedException Exception if UserID is not provided.

public bool Rbac->Users->hasRole(mixed $Role, int $UserID = null)

Checks to see whether a User has a Role or not.

Role

Accepts one of the following:

• int ID
• string Title
• string Path

UserID

Accepts an int UserID, provided from external User Management System.

Returns true if successful, false if unsuccessful.

public int Rbac->Users->resetAssignments(bool $Ensure = false)

Remove all Role-User assignments.

Mostly used for testing.

Ensure

Accepts true or false. Must be true to work, otherwise an \Exception will be thrown.

Returns the int count of deleted assignments.

public int Rbac->Users->roleCount(int $UserID = null)

Return count of Roles assigned to a User.

UserID

Accepts the int ID of a User (Not optional)

Throws RbacUserNotProvidedException if not provided

Returns int number of Roles assigned to the User.

public bool Rbac->Users->unassign(mixed $Role, int $UserID = null)

Unassigns a Role from a User.

Role

Accepts one of the following:

• int ID
• string Title
• string Path

UserID

Accepts an int UserID, provided from external User Management System.

Use 0 for Guest.

Returns true if successful, false if unsuccessful.