Roles for access control in ProcessWire

Roles are a way of grouping multiple users and assigning permissions to that group. They are the connection of both users and templates to permissions.

Roles and users

A user can have multiple roles, each with different permissions. Though for simple needs, it's common for a user to just have one non-guest role. However, you may assign as many roles to a user as you need, and the user will gain the access and permissions assigned to all of the roles they belong to.

Default roles

ProcessWire includes two permanent roles by default, though you may add as many roles as you like. The two roles included with every ProcessWire installation are:

  • guest
    The guest role is automatically given to all anonymous site users. You should not give this role any access other than page-view permission.

  • superuser
    The superuser role has all-inclusive access to the site without limitation. This role should only be given to the most trusted users that operate the site. Superuser has all permissions regardless of what you assign with the superuser role.

Custom roles

You can also add as many other roles as you want and selectively assign them to specific users. Each role can be assigned a unique set of permissions. Any given user can have multiple roles, and that user will inherit all permissions assigned to each of their roles. All users also inherit permissions assigned to the guest role.

Checking if a user has a role

To check if a user has a specific role from the API side, use the $user->hasRole('roleName') method:

if($user->hasRole('editor')) {
  // user has the editor role, display editor_notes field
  echo "<h3>Editor notes</h3>" . $page->editor_notes;

Roles and permissions

Roles are essentially a group of permissions that can be assigned to users. Users gain all the permissions assigned to all of their roles.

In some cases a permission doesn't do much until the role containing the permission is also assigned to a template (the context). A good example of this is the page-edit permission. If it were as simple as giving a role page-edit permission, then they would be able to edit any page anywhere in the site, which is usually not what you want. Instead, a permission like page-edit also requires a context, and templates (as used by pages) are that context. So a user might have a general page-edit permission via a role assigned to them, but they won't be able to actually edit any pages until a template also has that same role selected. This is how you can enable granular access (edit, view, create, add, delete, etc.) to some pages and not others.

Assigning permissions to roles

Assigning permissions to roles is as simple as editing the role in your admin at Access > Roles > your_role. Once there, you will see a long list of checkboxes representing the various permissions that you can assign to the role. In some cases (like page-edit permission), clicking a permission reveals numerous other permissions below it. This indicates that such permissions are child permissions of the one you checked, and thus only apply if the role has the parent permission. Though you don't need to think about that, as the role editor adjusts the visibility of permissions according to what is applicable.

Permissions with template context

Some permissions also support a template context. Meaning, the permission won't do much until the role having it is also assigned to a template. When this is the case, the role editor will show the permission along with a checkbox list of all templates where the permission can be assigned (which would be all templates that have access control enabled). If you don't see the template you need, you can enable access control for it (see roles and templates).

Editing permissions with template context in the role editor is convenient because it enables you to edit all permissions for the role, in the context of those access controlled templates, right on a single screen. You can also edit template/role assignments from the template editor (Setup > Template > your_template > Access), but in this case you are editing access for all roles on one template, rather than all templates on one role. It does not matter which one you use, but which is more convenient will depend on whether you've got more templates or more roles.

Roles and templates

Roles are assigned to users, but they are also assigned to templates that have access control enabled. As stated earlier, this is how you limit access (view, edit, create, add, etc.) to certain pages, or groups of pages, in your site. By default, access control is not enabled for a template. When not enabled, pages using the template inherit access from the closest parent page that has access control enabled.

Enabling template access control

You can enable access control for a template from the template editor Access tab (Setup > Templates > your_template > Access). From here you can dictate what roles are allowed to view, edit, create, add new pages, and more. Any role can be assigned for view permission, but only roles that have at least page-edit permission are assignable for edit/add/create access in these template access settings. Once a template has access control enabled, these can also be assigned in the role editor—see the section above on permissions with template context.

Twitter updates

  • Happy New Year! Today I’ve bumped the version on the dev branch to 3.0.170, and it’s quite a lot of updates. This post covers most of them. In this post, there’s also a question for you: what would you like to see in ProcessWire in 2021? More
    1 January 2021
  • In this week’s blog post we’ll take a brief look at a powerful new ProFields module for ProcessWire that’s just around the corner—the Combo field: More
    4 December 2020
  • There’s a new modules directory on the ProcessWire site now up and running. In this post we’ll cover a few details about what’s changed and what’s new—More
    20 November 2020

Latest news

  • ProcessWire Weekly #347
    In the 347th issue of ProcessWire Weekly we'll check out ProcessWire 3.0.170, introduce the PDF Fieldtype/Inputfield module, and more. Read on! / 2 January 2021
  • ProcessWire 3.0.170 core updates
    Happy New Year! Today I’ve bumped the version on the dev branch to 3.0.170, and it’s quite a lot of updates. This post covers most of them. In this post, there’s also a question for you: what would you like to see in ProcessWire in 2021?
    Blog / 1 January 2021
  • Subscribe to weekly ProcessWire news

“To Drupal, or to ProcessWire? The million dollar choice. We decided to make an early switch to PW. And in retrospect, ProcessWire was probably the best decision we made. Thanks are due to ProcessWire and the amazing system and set of modules that are in place.” —Unni Krishnan, Founder of PigtailPundits