summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorAlex Pott2015-01-21 20:07:38 (GMT)
committerAlex Pott2015-01-21 20:07:38 (GMT)
commit165cd5586cc366eca9a15edf314fe8f38e2bef63 (patch)
tree2d2ca7908000cb4758ed7eba9d76c4af9caefae1
parentb4f1849a821e9d35ef35d5c05eb7d364fb208e79 (diff)
Issue #2390239 by apratt, larowlan, eojthebrave: No information about format of permissions.yml in permissions topic
-rw-r--r--core/modules/system/core.api.php6
-rw-r--r--core/modules/user/src/PermissionHandler.php35
2 files changed, 32 insertions, 9 deletions
diff --git a/core/modules/system/core.api.php b/core/modules/system/core.api.php
index 3ffb004..7f6acd2 100644
--- a/core/modules/system/core.api.php
+++ b/core/modules/system/core.api.php
@@ -575,10 +575,8 @@
* appropriately for their particular sites.
*
* @section sec_define Defining permissions
- * Modules define permissions via a $module.permissions.yml file. This file
- * defines machine names, human-readable names, and optionally
- * descriptions for each permission type. The machine names are the canonical
- * way to refer to permissions for access checking.
+ * Modules define permissions via a $module.permissions.yml file. See
+ * \Drupal\user\PermissionHandler for documentation of permissions.yml files.
*
* @section sec_access Access permission checking
* Depending on the situation, there are several methods for ensuring that
diff --git a/core/modules/user/src/PermissionHandler.php b/core/modules/user/src/PermissionHandler.php
index d41b05e..2bb4523 100644
--- a/core/modules/user/src/PermissionHandler.php
+++ b/core/modules/user/src/PermissionHandler.php
@@ -16,14 +16,39 @@ use Drupal\Core\StringTranslation\TranslationInterface;
/**
* Provides the available permissions based on yml files.
*
- * To define permissions you can use a $module.permissions.yml file:
+ * 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):
* @code
- * administer permissions:
- * title: Administer permissions
- * restrict access: true
- * description: some description
+ * # 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
+ *
+ * # An array of callables used to generate dynamic permissions.
+ * permission_callbacks:
+ * # Each item in the array should return an associative array with one or
+ * # more permissions following the same keys as the permission defined above.
+ * - Drupal\filter\FilterPermissions::permissions
* @endcode
+ *
+ * @see filter.permissions.yml
+ * @see \Drupal\filter\FilterPermissions
+ * @see user_api
*/
class PermissionHandler implements PermissionHandlerInterface {