User Permissions

You are viewing documentation for an unreleased version of Craft CMS. Please be aware that some pages, screenshots, and technical reference may still reflect older versions.

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[] = [
                'heading' => 'Permission Group Name',
                'permissions' => [
                    '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')) {
    // ...
}