Tutorial: Permissions¶

Introduction¶

Adding new permissions in an extension is an easy three-step process:

Create permissions with a migration.

Define permissions with language keys.

Wire up permissions with events.

Create permissions¶

There are four permission types:

a_* Administrator

m_* Moderator

u_* User

f_* Forum

You can create new permissions for each of these types and assign them to user groups or permission roles. You can also define new roles to assign your permissions to if desired.

Permissions must first be created in a migration using the Permission Tool. It helps with adding, removing, setting, and unsetting permissions and adding or removing permission roles. For example, to create a new User permission u_foo_bar and set it to “yes” for the Registered Users group and the Standard User Role:

return array(
    array('permission.add', array('u_foo_bar')),
    array('permission.permission_set', array('REGISTERED', 'u_foo_bar', 'group')),
    array('permission.permission_set', array('ROLE_USER_STANDARD', 'u_foo_bar')),
);

Define permissions¶

Permissions must have a corresponding language key definition. All language keys for permissions should be placed in a language file that starts with permissions_ and the keys will be automatically loaded into the ACP language array. For example, the language file permissions_foobar.php:

$lang = array_merge($lang, array(
    'ACL_U_FOOBAR' => 'Can post foobars',
));

Wire up permissions¶

Wiring up permissions simply refers to making phpBB aware of your new permissions by adding them to the permission data array. The array uses the permission name as its key and an array value defining the permission’s language key and the category it should belong to.

This is done in an event listener using the core.permissions event to add your new permissions to phpBB’s permission data array:

$permissions = $event['permissions'];
$permissions['u_foo_bar'] = array('lang' => 'ACL_U_FOOBAR', 'cat' => 'post');
$event['permissions'] = $permissions;

Note

Note how the permissions event variable is first copied by assigning it to a local variable, then modified, and then copied back. This is because the event variables are overloaded, which is a limitation in PHP. For example, this shortcut will not work:

$event['permissions']['u_foo_bar'] = array('lang' => 'ACL_U_FOOBAR', 'cat' => 'post');