User Permissions

• On this Page

  • Requiring Permissions
  • Checking Permissions

Modules and plugins can register new user permissions to the system using the EVENT_REGISTER_PERMISSIONS (opens new window) event:

use craft\events\RegisterUserPermissionsEvent;
use craft\services\UserPermissions;
use yii\base\Event;

public function init()
{
    parent::init();

    Event::on(
        UserPermissions::class,
        UserPermissions::EVENT_REGISTER_PERMISSIONS,
        function(RegisterUserPermissionsEvent $event) {
            $event->permissions['Permission Group Name'] = [
                'permissionName' => [
                    'label' => 'Permission Label',
                ],
            ];
        }
    );
}

Permissions can also have nested permissions by adding a nested key to the permission array.

'permissionName' => [
    'label' => 'Permission Label',
    'nested' => [
        'nestedPermissionName' => [
            'label' => 'Nested Permission Label',
        ],
    ],
];

Nesting is meant for UI only; if you wanted to reference nestedPermissionName in the example above you would use exactly that key.

Requiring Permissions

Controllers can require that the logged-in user has a permission by calling requirePermission() (opens new window).

public function actionStayUpLate()
{
    // Require the `stayUpLate` permission
    $this->requirePermission('stayUpLate');
}

If the user doesn’t have that permission, then a 403 error will be returned.

Templates can also ensure that the user has a permission with the requirePermission tag:

{% requirePermission 'stayUpLate' %}

Checking Permissions

You can check if the logged-in user has a permission by calling craft\web\User::checkPermission() (opens new window):

// See if they have the `stayUpLate` permission
if (Craft::$app->user->checkPermission('stayUpLate')) {
    // ...
}

You can also see if any given user has a permission by calling craft\elements\User::can() (opens new window):

/** @var \craft\elements\User $user */
if ($user->can('stayUpLate')) {
    // ...
}