1. class
  2. Drupal
  3. \
  4. user
  5. \
  6. PermissionHandler

PermissionHandler

class PermissionHandler implements PermissionHandlerInterface (View source)

Provides the available permissions based on yml files.

To define permissions you can use a $module.permissions.yml file. This file defines machine names, human-readable names, restrict access (if required for security warning), and optionally descriptions for each permission type. The machine names are the canonical way to refer to permissions for access checking.

If your module needs to define dynamic permissions you can use the permission_callbacks key to declare a callable that will return an array of permissions, keyed by machine name. Each item in the array can contain the same keys as an entry in $module.permissions.yml.

Here is an example from the core filter module (comments have been added):

Traits

StringTranslationTrait

Wrapper methods for \Drupal\Core\StringTranslation\TranslationInterface.

Properties

protected TranslationInterface $stringTranslation

The string translation service.

 from  StringTranslationTrait
protected ModuleHandlerInterface $moduleHandler

The module handler.
protected YamlDiscovery $yamlDiscovery

The YAML discovery class to find all .permissions.yml files.
protected ControllerResolverInterface $controllerResolver

The controller resolver.

Methods

TranslatableMarkup
t(string $string, array $args = [], array $options = [])

Translates a string to the current language or to a given language.

from  StringTranslationTrait
formatPlural($count, $singular, $plural, array $args = [], array $options = [])

Formats a string containing a count of items.

from  StringTranslationTrait
getNumberOfPlurals($langcode = NULL)

Returns the number of plurals supported by a given language.

from  StringTranslationTrait
TranslationInterface
getStringTranslation()

Gets the string translation service.

from  StringTranslationTrait
$this
setStringTranslation(TranslationInterface $translation)

Sets the string translation service to use.

from  StringTranslationTrait
__construct(ModuleHandlerInterface $module_handler, TranslationInterface $string_translation, ControllerResolverInterface $controller_resolver)

Constructs a new PermissionHandler.

YamlDiscovery
getYamlDiscovery()

Gets the YAML discovery.

array
getPermissions()

Gets all available permissions.

bool
moduleProvidesPermissions(string $module_name)

Determines whether a module provides some permissions.

array[]
buildPermissionsYaml()

Builds all permissions provided by .permissions.yml files.

array[]
sortPermissions(array $all_permissions = [])

Sorts the given permissions by provider name and title.

string[]
getModuleNames()

Returns all module names.

Details

in StringTranslationTrait at line 70
protected TranslatableMarkup t(string $string, array $args = [], array $options = [])

Translates a string to the current language or to a given language.

See \Drupal\Core\StringTranslation\TranslatableMarkup::__construct() for important security information and usage guidelines.

In order for strings to be localized, make them available in one of the ways supported by the

Parameters

string $string

A string containing the English text to translate.
array $args

(optional) An associative array of replacements to make after translation. Based on the first character of the key, the value is escaped and/or themed. See \Drupal\Component\Render\FormattableMarkup::placeholderFormat() for details.
array $options

(optional) An associative array of additional options, with the following elements:

  • 'langcode' (defaults to the current language): A language code, to translate to a language other than what is used to display the page.
  • 'context' (defaults to the empty context): The context the source string belongs to. See the @link i18n Internationalization topic @endlink for more information about string contexts.

Return Value

TranslatableMarkup

An object that, when cast to a string, returns the translated string.

See also

FormattableMarkup::placeholderFormat
TranslatableMarkup::__construct

in StringTranslationTrait at line 79
protected formatPlural($count, $singular, $plural, array $args = [], array $options = [])

Formats a string containing a count of items.

Parameters

$count
$singular
$plural
array $args
array $options

See also

TranslationInterface::formatPlural

in StringTranslationTrait at line 88
protected getNumberOfPlurals($langcode = NULL)

Returns the number of plurals supported by a given language.

Parameters

$langcode

See also

PluralFormulaInterface::getNumberOfPlurals

in StringTranslationTrait at line 102
protected TranslationInterface getStringTranslation()

Gets the string translation service.

Return Value

TranslationInterface

The string translation service.

in StringTranslationTrait at line 118
$this setStringTranslation(TranslationInterface $translation)

Sets the string translation service to use.

Parameters

TranslationInterface $translation

The string translation service.

Return Value

$this

at line 87
__construct(ModuleHandlerInterface $module_handler, TranslationInterface $string_translation, ControllerResolverInterface $controller_resolver)

Constructs a new PermissionHandler.

Parameters

ModuleHandlerInterface $module_handler

The module handler.
TranslationInterface $string_translation

The string translation.
ControllerResolverInterface $controller_resolver

The controller resolver.

at line 101
protected YamlDiscovery getYamlDiscovery()

Gets the YAML discovery.

Return Value

YamlDiscovery

The YAML discovery.

at line 111
array getPermissions()

Gets all available permissions.

Return Value

array

An array whose keys are permission names and whose corresponding values are arrays containing the following key-value pairs:

  • title: The human-readable name of the permission, to be shown on the permission administration page. This should be wrapped in the t() function so it can be translated.
  • description: (optional) A description of what the permission does. This should be wrapped in the t() function so it can be translated.
  • restrict access: (optional) A boolean which can be set to TRUE to indicate that site administrators should restrict access to this permission to trusted users. This should be used for permissions that have inherent security risks across a variety of potential use cases (for example, the "administer filters" and "bypass node access" permissions provided by Drupal core). When set to TRUE, a standard warning message defined in user_admin_permissions() will be displayed with the permission on the permission administration page. Defaults to FALSE.
  • warning: (optional) A translated warning message to display for this permission on the permission administration page. This warning overrides the automatic warning generated by 'restrict access' being set to TRUE. This should rarely be used, since it is important for all permissions to have a clear, consistent security warning that is the same across the site. Use the 'description' key instead to provide any information that is specific to the permission you are defining.
  • dependencies: (optional) An array of dependency entities used when building this permission, structured in the same way as the return of ConfigEntityInterface::calculateDependencies(). For example, if this permission was generated as effect of the existence of node type 'article', then value of the dependency key is: @code 'dependencies' => ['config' => ['node.type.article']] @endcode The module providing this permission doesn't have to be added as a dependency. It is automatically parsed, stored and retrieved from the 'provider' key.
  • provider: The provider name of the permission. This is set automatically to the module that provides the permission.yml file.

at line 120
bool moduleProvidesPermissions(string $module_name)

Determines whether a module provides some permissions.

Parameters

string $module_name

The module name.

Return Value

bool

Returns TRUE if the module provides some permissions, otherwise FALSE.

at line 142
protected array[] buildPermissionsYaml()

Builds all permissions provided by .permissions.yml files.

Return Value

array[]

An array with the same structure as PermissionHandlerInterface::getPermissions().

See also

PermissionHandlerInterface::getPermissions

at line 205
protected array[] sortPermissions(array $all_permissions = [])

Sorts the given permissions by provider name and title.

Parameters

array $all_permissions

The permissions to be sorted.

Return Value

array[]

An array with the same structure as PermissionHandlerInterface::getPermissions().

See also

PermissionHandlerInterface::getPermissions

at line 227
protected string[] getModuleNames()

Returns all module names.

Return Value

string[]

Returns the human readable names of all modules keyed by machine name.