User Permissions

Modules and plugins can register new user permissions to the system using the EVENT_REGISTER_PERMISSIONS 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',
        ],
    ],
];

Requiring Permissions

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

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():

// 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():

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