7.5. Roles

In most systems, users belong to one or more groups (i.e., serve one or more roles). The user's identity will not change, but he may take on a new role, leave a role, or have multiple roles in the same system. The Solar_Role set of classes lets you look up what roles a user fulfills in the system.

As with authentication, we don't need to instantiate a separate role object on our own; instead, the registered Solar_User object has a $role property that it sets up automatically.

7.5.1. Adapters

Solar provides different adapters allowing you to discover role information from different backends. The current adapters shipped with Solar are as follows:

[Note] Note

Note that these adapters are read-only. They do not create or manage role assignments for you, they only look up which roles a user belongs to.

An authenticated identity will never change during the login period. However, a user's roles might change during the same session; e.g., being promoted from a moderator to an author while logged in. For this reason, the role adapters re-read the user roles from the storage backend on each new page request.

Solar uses a Solar_Role factory to create the adapter instance, so you need to configure the factory to create the kind of adapter you want to use for role discovery. You can do so in the config file like this:

$config['Solar_Role'] = array(
    'adapter'    => 'Solar_Role_Adapter_Sql',

7.5.2. Configuration

Now that we have told the factory what adapter to create, we need to configure the adapter itself. Role adapters are much easier to configure than authentication adapters, but each has its own settings. You can look up the config keys for each of them on the following pages:

For example, the configuration for an SQL role adapter to use the roles table, with columns handle for the username and name for the assigned role, would look like this:

$config['Solar_Role_Adapter_Sql'] = array(
    'table'      => 'roles',
    'handle_col' => 'handle',
    'role_col'   => 'name',

7.5.3. Usage

Let's say we are using the SQL role adapter to read from roles table with the following information:

# table: roles
handle      name
--------    ----------
bolivar     admin
andy        editor
sarah       editor
andy        author
jameel      author
kornblum    moderator

Let's also say that the user 'andy' has just logged in. The Solar_User object, which has a Solar_Role_Adapter instance inside it, automatically goes to the database and fetches the roles that Andy belongs to. We can then use the following Solar_Role_Adapter methods to find out about Andy's roles in the system. (Remember, we use a Solar_User object instead of instantiating a separate role adapter instance.)

$user = Solar_Registry::get('user');

// what is the list of andy's roles?
$list = $user->role->getList(); // array('editor', 'author')

// is andy an admin?
$is_admin = $user->role->is('admin'); // false

// is andy in any (at least one) of these roles?
$user->role->isAny(array('moderator', 'author', 'admin')); // true

// is andy assigned all of these roles?
$user->role->isAll(array('editor', 'author')); // true