Permissions can define dependencies

Permissions can be generated dynamically using permission callbacks. For example, the Node module generates permissions based upon the available node types. If the conditions that cause such permissions to exist change and they no longer exist then the permission needs to be removed from any role it is assigned to.

To support removing such permissions, a new dependencies key has been added to the permission information array. The current structure of this array is:

 * # The key is the permission machine name, and is required.
 * administer filters:
 *   # (required) Human readable name of the permission used in the UI.
 *   title: 'Administer text formats and filters'
 *   # (optional) Additional description fo the permission used in the UI.
 *   description: 'Define how text is handled by combining filters into text formats.'
 *   # (optional) Boolean, when set to true a warning about site security will
 *   # be displayed on the Permissions page. Defaults to false.
 *   restrict access: false
 *   # (optional) Dependency array following the same structure as the return
 *   # config entities dependencies.
 *   dependencies:
 *     config:
 *       - node.type.article

Adding permissions with BundlePermissionHandlerTrait

There is a new Drupal\Core\Entity\BundlePermissionHandlerTrait, with the method generatePermissions(), to help add dependencies.

For example, Drupal\node\NodePermissions already has the method buildPermissions(), which returns an array of arrays. The keys of the outer array are permission machine names, and the inner arrays are keyed by 'title' (required) and 'description' (optional).

Before Drupal 9.3.0

  public function nodeTypePermissions() {
    $perms = [];
    // Generate node permissions for all node types.
    foreach (NodeType::loadMultiple() as $type) {
      $perms += $this->buildPermissions($type);
    }

    return $perms;
  }

In Drupal 9.3.0 and later

use Drupal\Core\Entity\BundlePermissionHandlerTrait;

class NodePermissions {
  use BundlePermissionHandlerTrait;
  // ...
  public function nodeTypePermissions() {
    return $this->generatePermissions(NodeType::loadMultiple(), [$this, 'buildPermissions']);
  }
  // ...
}

When node types are removed now, the permissions will be automatically cleaned up.