Users / $users, Roles / $roles, Permissions / $permissions

$users, $roles, and $permissions (and $languages) all extend PagesType. The following methods are common to all three access-control managers.

find($selectorString)

Find all items of this type matching the given selector.

• Arguments: find(string $selectorString, array $options = [])
• Returns: PageArray
• Access control is bypassed (findAll=true implied); all matching items are returned regardless of the current user's access level.
• Template and parent constraints for the type are added automatically.

$editors = $users->find('roles=editor');
$customRoles = $roles->find('name!=guest, name!=superuser');

findIDs($selectorString)

Find matching page IDs without loading the pages.

• Arguments: findIDs(string $selectorString, array $options = [])
• Returns: array

$userIds = $users->findIDs('roles=editor');

get($selectorString)

Get a single item by ID, name, or selector string.

• Arguments: get(string|int $selectorString)
• Returns: User|Role|Permission|NullPage
• Returns a NullPage if not found.
• A bare integer or digit string is treated as a page ID.
• A string with no = and no / is treated as a page name.

$admin = $users->get('admin');         // by name
$admin = $users->get(41);             // by ID
$role = $roles->get('name=editor');  // by selector

All three managers support direct iteration:

foreach($users as $u) echo $u->name . "\n";
foreach($roles as $role) echo $role->name . "\n";
foreach($permissions as $permission) echo $permission->name . "\n";

add($name)

Create, save, and return a new item with the given name.

• Arguments: add(string $name)
• Returns: User|Role|Permission|NullPage — returns NullPage on error
• This is a hookable method (___add()).

$john = $users->add('john');
$editor = $roles->add('editor');
$permission = $permissions->add('page-publish');

new($name, $options)

Create a new item, optionally saving it. Available 3.0.263.

• Arguments: new(string|array $nameOrOptions = null, array $options = [])
• Returns: User|Role|Permission
• This is a hookable method (___new()).
• Pass a string name as the first argument to create and save in one step.
• Pass an array or nothing to create in memory only (call save() yourself).

// Create and save immediately (string name)
$john = $users->new('john');
$editor = $roles->new('editor');
$mike = $users->new('mike', ['email' => 'mike@example.com']);

// Create in memory only (set fields, then save manually)
$john = $users->new();
$john->name = 'john';
$john->pass = 'secret123';
$john->addRole('editor');
$john->save();

save($page)

Save a user, role, or permission.

• Arguments: save(Page $page)
• Returns: bool
• Equivalent to calling $page->save().
• This is a hookable method (___save()).

$users->save($someUser);
// or equivalently:
$u->save();

delete($page)

Permanently delete a user, role, or permission.

• Arguments: delete(Page $page, bool $recursive = false)
• Returns: bool
• This is a hookable method (___delete()).

$users->delete($someUser);

count($selectorString)

Return the number of items, optionally filtered by a selector.

• Arguments: count(string $selectorString = '', array $options = [])
• Returns: int

$total = $users->count();
$numEditors = $users->count('roles=editor');

Hooks

User, Role, and Permission inherit the full set of Page lifecycle hooks. Use the class name to register a static hook that fires for all instances of that type:

$wire->addHookAfter('User::saved', function(HookEvent $event) {
    $user = $event->object; // User object
    $changes = $event->arguments(0); // array of changed field names
});

$wire->addHookAfter('Role::deleted', function(HookEvent $event) {
    $role = $event->object; // Role object
});

Available hooks (all inherited from Page):

User extends Page and represents an individual user. The $user API variable (an instance of User) holds the current user. Every User is guaranteed to have at least the guest role. Users that are not logged-in are represented by the user named guest with id of $config->guestUserPageID (default=40).

Built-in fields/properties

In addition to the built-in fields/properties above, User has all of the built-in fields/properties of Page, and any custom fields added to the user template.

Changing a password:

$u = $users->get('john');
$u->setAndSave('pass', 'new-plain-text-password'); // hashes on save

$user->hasRole($role)

Return whether the user has the given role.

• Arguments: hasRole(string|int|Role $role) — name, ID, or Role object
• Returns: bool

if($user->hasRole('editor')) {
    // user has the editor role
}

$user->addRole($role) / $user->removeRole($role)

Add or remove a role. Remember to call save() to persist the change.

• Arguments: Role name, ID, or Role object
• Returns: bool — false if the role was not recognized

$user->addRole('editor');
$user->removeRole('subscriber');
$user->save();

$user->hasPermission($name, $context)

Return whether the user has the given permission, accounting for all their roles.

• Arguments: hasPermission(string|int|Permission $name, Page|Template|bool|string $context = null)
• Returns: bool|array
• Superusers return true for boolean permission checks. When $context is 'templates', superusers return the matching template array like other users.

// Global permission check (across all roles)
if($user->hasPermission('page-publish')) { ... }

// Check permission in the context of a specific page
if($user->hasPermission('page-edit', $page)) { ... }

// Check permission in the context of a specific template
if($user->hasPermission('page-edit', $templates->get('blog-post'))) { ... }

// Return true if the user has the permission or permission added on any template
if($user->hasPermission('page-edit', true)) { ... }

// Return an array of Template objects where the user has the permission
$tpls = $user->hasPermission('page-edit', 'templates');

$user->getPermissions($page)

Get all permissions this user has, optionally scoped to a page.

• Arguments: getPermissions(Page $page = null)
• Returns: PageArray of Permission objects
• Returns all permissions for superusers.

$allPermissions = $user->getPermissions();
$pagePermissions = $user->getPermissions($page);
foreach($pagePermissions as $permission) {
    echo $permission->name . "\n";
}

$user->isSuperuser()

Return whether the user has the superuser role.

• Returns: bool
• Result is cached per request.

if($user->isSuperuser()) {
    // unrestricted access
}

$user->isGuest()

Return whether this is the non-logged-in guest user.

• Returns: bool

if($user->isGuest()) {
    // user is not logged in
}

$user->isLoggedin()

Return whether this User object is the current logged-in user.

• Returns: bool
• Returns false for the guest user.
• Useful when you have a User object obtained from $users->get() and need to know whether it is the same person who is currently browsing the site.

$someUser = $users->get(123);
if($someUser->isLoggedin()) {
    // this user is currently logged in
}

$user->setLanguage($language)

Set the user's language without tracking it as a change (it will not be saved). This is how ProcessWire sets the current user's language when the URL or page dictates the language.

• Arguments: setLanguage(Language|string|int $language) — Language object, name, or ID
• Returns: $this
• Silently does nothing if LanguageSupport is not installed.
• Throws WireException for an unrecognized language when LanguageSupport is installed.
• Available 3.0.186.

$user->setLanguage('default');
$user->setLanguage($languages->get('de'));

$user->hasTfa($getInstance)

Return whether two-factor authentication is enabled for this user.

• Arguments: hasTfa(bool $getInstance = false)
• Returns: false|string|Tfa — false if not enabled; the TFA module name (string) if enabled; a Tfa module instance if $getInstance = true
• Available 3.0.162.

$tfa = $user->hasTfa();
if($tfa) {
    echo "TFA enabled: $tfa"; // e.g. "TfaEmail"
}

Permission extends Page and represents an individual permission.

Properties

$permission = $permissions->get('page-publish');
echo $permission->name;  // page-publish
echo $permission->title; // "Publish or unpublish pages"