How to: User groups

Easily adding user groups

User group XML files are stored in plugins/usermgr/groups. Users can be assigned to a group in 3 ways:

1. If the user XML file has no <GROUP>group_name</GROUP> node, the user is admin by default. This is useful so existing users don't get locked out of their admin dashboard.
2. If the user XML file has no <GROUP>group_name</GROUP> node, but a group file exists with the same name as the user in plugins/usermgr/groups/, then the user will be assigned to that group (this is a group with only one possible member). This is useful if you only have 1-3 users which all must have different permissions.
3. If the user XML file has a <GROUP>group_name</GROUP>, the user will be assigned to that group.

Example

Suppose your only other user (except yourself) is 'getsimple-user'. You have a user file /data/users/getsimple-user.xml, and have just installed usermgr plugin. The user file has no <GROUP> node. The user's group is admin. You want to restrict some permissions for this single user and you create a group file in /plugins/usermgr/groups/getsimple-user.xml. The user's group is now 'getsimple-user'. Later, you give access to the admin dashboard to 3 other users, who should only be able to post blog articles. You edit their user.xml files and add a <GROUP>publisher</GROUP> node. The 3 new users now all belong to the standard user group 'publisher'.

Creating user groups

The easiest way to create a group, is simply copying one of the existing standard user groups, and giving it another filename and <name> node value. The following is an example of a user group file (publisher.xml):

<?xml version="1.0" encoding="UTF-8"?>
<item>
  <extend>admin</extend>
  <deny>
    <permission>access_theme</permission>
    <permission>access_theme-edit</permission>
    <permission>access_components</permission>
    <permission>access_sitemap</permission>
    <permission>access_archives</permission>
    <permission>access_support</permission>
    <permission>access_plugins</permission>
    <permission>access_backups</permission>
    <permission>access_deletefile</permission>
    <permission>access_menu-manager</permission>
    <permission>delete_page</permission>
    <permission>delete_file</permission>
    <permission>access_settings</permission>
    <permission>access_health-check</permission>
    <permission>access_support</permission>
    <permission>delete_backup</permission>
    <permission>delete_all_backups</permission>
    <permission>delete_archive</permission>
    <permission>restore_backup</permission>
  </deny>
</item>

The name of the file (without the extension) is the group name.
The <extend> node (optional) is the ID of the group on which this group is based. That means the group will get the same base permissions as the <extend> group. Additional permissions can be granted to/ denied from that base. Groups with the admin group as base are certain to have newly added permissions granted by default.
Note: because the admin role has all permissions granted, granting it new permissions will have no effect.
The <deny> node (optional) indicates permissions that should be denied for this group.
The <grant> node (optional) indicates permissions that should be granted for this group.

Some other examples:

Group with NO permissions (except profile, login/out)

<?xml version="1.0" encoding="UTF-8"?>
<item></item>

Group with ALL permissions (also newly registered ones)

<?xml version="1.0" encoding="UTF-8"?>
<item>
  <extend>admin</extend>
</item>

Group with limited, fixed permissions

<?xml version="1.0" encoding="UTF-8"?>
<item>
  <grant>
    <permission>access_pages</permission>
    <permission>access_theme</permission>
    <permission>access_support</permission>
    <permission>access_plugins</permission>
    <permission>access_backups</permission>
    <permission>access_settings</permission>
    <permission>access_profile</permission>
  </grant>
</item>

PHP API

New user groups can be registered, if they haven't been registered previously. For example, you could create a group that is not allowed to delete anything: pages, files, archives, etc.

$usrmgr = usermgr();

$nodelete_group_definition = array(
  'name'   => 'nodelete',
  'extend' => 'admin',
  'deny'   =>  array('access_deletefile', 'delete_archive')
);

$nodelete_group = UserGroup::create('custom_group');
$usrmgr->register('groups', $nodelete_group);
// or $usrmgr->groups->register($nodelete_group);

Existing user groups can be granted or denied additional permissions:

$usrmgr = usermgr();
$publisher = $usrmgr->get('groups', 'publisher');

$publisher->grant('access_deletefile', 'access_theme');
$publisher->deny('access_files');

User groups can extend existing user groups, inheriting all the granted and denied permissions.

$usermgr = usermgr();
$group = $usermgr->get('groups', 'publisher');
$admin_group = $usrmgr->get('groups', 'admin');
$group->extend('admin');
$manager->extend('editor', array('additional_perm1', 'additional_perm2'));

All permissions granted to a user group can be consulted:

$usermgr = usermgr();
$publisher = $usermgr->get('groups', 'publisher');
debugLog($publisher->permissions());