From 17e003e2bc79f63f9e82a74416028f4584e6472e Mon Sep 17 00:00:00 2001 From: erinlefeyijimi Date: Thu, 20 Nov 2025 10:04:07 +0100 Subject: [PATCH 1/6] docs:migrating roles and permisison components to the latest developer documentation --- docs/index.rst | 1 + docs/plugins/roles_and_permissions.rst | 0 2 files changed, 1 insertion(+) create mode 100644 docs/plugins/roles_and_permissions.rst diff --git a/docs/index.rst b/docs/index.rst index df41b368..0027400b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -120,6 +120,7 @@ There are several ways to support Mautic other than contributing with code. plugins/event_listeners plugins/installation plugins/data + plugins/roles_and_permissions plugins/translations plugins/continuous-integration plugins/from-4-to-5 diff --git a/docs/plugins/roles_and_permissions.rst b/docs/plugins/roles_and_permissions.rst new file mode 100644 index 00000000..e69de29b From 4e7a58466471f964fd8d105064311d85964b9c18 Mon Sep 17 00:00:00 2001 From: erinlefeyijimi Date: Mon, 24 Nov 2025 12:27:07 +0100 Subject: [PATCH 2/6] docs:migrated Roles and Permissions to the new documentation platform --- docs/plugins/roles_and_permissions.rst | 164 +++++++++++++++++++++++++ 1 file changed, 164 insertions(+) diff --git a/docs/plugins/roles_and_permissions.rst b/docs/plugins/roles_and_permissions.rst index e69de29b..08e6b288 100644 --- a/docs/plugins/roles_and_permissions.rst +++ b/docs/plugins/roles_and_permissions.rst @@ -0,0 +1,164 @@ +Roles and Permissions +################### + +Mautic lets you define custom permissions for each Role. These permissions determine what Users can view or do within different parts of the system. + +How Permissions Work +-------------------- + +Mautic assigns permissions using bit values. These bits double as they increase: + +``1, 2, 4, 8, 16, 32, 64, 128...`` + +Bits should always follow this sequence. Avoid values like ``3`` or ``5`` because permission checks will fail. + +Example permission set: + ++--------------+-----+ +| Permission | Bit | ++--------------+-----+ +| view | 1 | +| edit | 2 | +| create | 4 | +| delete | 8 | +| full | 16 | ++--------------+-----+ + +A permission notation looks like this: + +``plugin:helloWorld:worlds:view`` + +This checks the ``view`` permission for the ``worlds`` level of the plugin. + +How Bit Storage Works +~~~~~~~~~~~~~~~~~~~~~ + +Mautic stores permissions by adding the bits of all permissions assigned to a Role. + +Examples: + +* ``view`` + ``edit`` = ``1 + 2 = 3`` +* ``view`` + ``create`` = ``1 + 4 = 5`` + +When checking a permission, Mautic verifies whether the bit exists within the stored sum. + +The ``full`` permission should always use the highest bit. It automatically grants all lower permissions. + +Using Permissions +----------------- + +Use the Security service to check permissions. + +Example in Twig: + +.. code-block:: twig + + {% if security.isGranted('user:roles:edit') %} + {# User can edit roles #} + {% endif %} + +Permission notation: + +* Core bundles: ``bundle:level:permission`` +* Plugins: ``plugin:bundle:level:permission`` + +Example: + +``user:roles:view`` + +Creating Custom Permissions +--------------------------- + +Plugins can define their own Permission classes. + +Each Permission class must: + +* Extend ``Mautic\CoreBundle\Security\Permissions\AbstractPermissions`` +* Implement ``__construct()`` +* Implement ``buildForm()`` +* Implement ``getName()`` + +Constructor +~~~~~~~~~~~ + +Inside ``__construct()``: + +1. Call ``parent::__construct($params)`` or assign ``$this->params = $params``. +2. Define ``$this->permissions`` as an array of permission levels and bits. + +Example level definition: + +* Level: ``worlds`` +* Permissions: ``use_telescope``, ``send_probe``, ``visit``, ``full`` + +Access check example: + +``plugin:helloWorld:worlds:send_probe`` + +Helper Methods for Permission Sets +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Mautic includes helper methods: + +* ``addStandardPermissions()`` adds view, edit, create, delete, publish, full +* ``addExtendedPermissions()`` adds creator-based permissions +* ``addManagePermission()`` adds a single manage permission + +buildForm() +~~~~~~~~~~~ + +``buildForm()`` adds permission fields to the Role form. + +Available helpers: + +* ``addStandardFormFields()`` +* ``addExtendedFormFields()`` +* ``addManageFormFields()`` + +getName() +~~~~~~~~~ + +This must return the bundle name in camelCase. + +Example: + +* Bundle: ``HelloWorldBundle`` +* Method return value: ``helloWorld`` +* File name: ``HelloWorldPermissions.php`` + +Permission Aliases +------------------ + +Use ``getSynonym()`` to map a permission name to another one. + +Example: + +``editown`` maps to ``edit`` if ``editown`` is not defined. + +Analyzing Permissions Before Saving +----------------------------------- + +Plugins can adjust permissions before saving. + +Use: + +``analyzePermissions()`` + +If a second pass is needed, return ``true``. +The next call will include ``$isSecondRound = true``. + +Advanced Permission Checks +-------------------------- + +To override bit-based checking, extend: + +``isGranted($userPermissions, $name, $level)`` + +Advanced Support Logic +---------------------- + +You can customize support checks by overriding: + +``isSupported()`` + +Use this for backward compatibility or custom permission rules. \ No newline at end of file From f3a681e81fb33410a259a76dcc6fd838cd4d2e64 Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Wed, 4 Mar 2026 17:10:43 +0100 Subject: [PATCH 3/6] move content from docs/plugins/roles_and_permissions.rst to docs/plugins/permissions.rst --- docs/plugins/permissions.rst | 170 ++++++++++++++++++++++++++++++++++- 1 file changed, 166 insertions(+), 4 deletions(-) diff --git a/docs/plugins/permissions.rst b/docs/plugins/permissions.rst index 964608ee..73980496 100644 --- a/docs/plugins/permissions.rst +++ b/docs/plugins/permissions.rst @@ -1,6 +1,3 @@ -Roles and permissions -##################### - .. vale off .. note:: @@ -11,4 +8,169 @@ Roles and permissions Please read the :xref:`dev docs contributing guidelines` and :xref:`Contributing to Mautic’s documentation` to get started. -.. vale on \ No newline at end of file +.. vale on + +Roles and Permissions +################### + +Mautic lets you define custom permissions for each Role. These permissions determine what Users can view or do within different parts of the system. + +How Permissions Work +-------------------- + +Mautic assigns permissions using bit values. These bits double as they increase: + +``1, 2, 4, 8, 16, 32, 64, 128...`` + +Bits should always follow this sequence. Avoid values like ``3`` or ``5`` because permission checks will fail. + +Example permission set: + ++--------------+-----+ +| Permission | Bit | ++--------------+-----+ +| view | 1 | +| edit | 2 | +| create | 4 | +| delete | 8 | +| full | 16 | ++--------------+-----+ + +A permission notation looks like this: + +``plugin:helloWorld:worlds:view`` + +This checks the ``view`` permission for the ``worlds`` level of the plugin. + +How Bit Storage Works +~~~~~~~~~~~~~~~~~~~~~ + +Mautic stores permissions by adding the bits of all permissions assigned to a Role. + +Examples: + +* ``view`` + ``edit`` = ``1 + 2 = 3`` +* ``view`` + ``create`` = ``1 + 4 = 5`` + +When checking a permission, Mautic verifies whether the bit exists within the stored sum. + +The ``full`` permission should always use the highest bit. It automatically grants all lower permissions. + +Using Permissions +----------------- + +Use the Security service to check permissions. + +Example in Twig: + +.. code-block:: twig + + {% if security.isGranted('user:roles:edit') %} + {# User can edit roles #} + {% endif %} + +Permission notation: + +* Core bundles: ``bundle:level:permission`` +* Plugins: ``plugin:bundle:level:permission`` + +Example: + +``user:roles:view`` + +Creating Custom Permissions +--------------------------- + +Plugins can define their own Permission classes. + +Each Permission class must: + +* Extend ``Mautic\CoreBundle\Security\Permissions\AbstractPermissions`` +* Implement ``__construct()`` +* Implement ``buildForm()`` +* Implement ``getName()`` + +Constructor +~~~~~~~~~~~ + +Inside ``__construct()``: + +1. Call ``parent::__construct($params)`` or assign ``$this->params = $params``. +2. Define ``$this->permissions`` as an array of permission levels and bits. + +Example level definition: + +* Level: ``worlds`` +* Permissions: ``use_telescope``, ``send_probe``, ``visit``, ``full`` + +Access check example: + +``plugin:helloWorld:worlds:send_probe`` + +Helper Methods for Permission Sets +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Mautic includes helper methods: + +* ``addStandardPermissions()`` adds view, edit, create, delete, publish, full +* ``addExtendedPermissions()`` adds creator-based permissions +* ``addManagePermission()`` adds a single manage permission + +buildForm() +~~~~~~~~~~~ + +``buildForm()`` adds permission fields to the Role form. + +Available helpers: + +* ``addStandardFormFields()`` +* ``addExtendedFormFields()`` +* ``addManageFormFields()`` + +getName() +~~~~~~~~~ + +This must return the bundle name in camelCase. + +Example: + +* Bundle: ``HelloWorldBundle`` +* Method return value: ``helloWorld`` +* File name: ``HelloWorldPermissions.php`` + +Permission Aliases +------------------ + +Use ``getSynonym()`` to map a permission name to another one. + +Example: + +``editown`` maps to ``edit`` if ``editown`` is not defined. + +Analyzing Permissions Before Saving +----------------------------------- + +Plugins can adjust permissions before saving. + +Use: + +``analyzePermissions()`` + +If a second pass is needed, return ``true``. +The next call will include ``$isSecondRound = true``. + +Advanced Permission Checks +-------------------------- + +To override bit-based checking, extend: + +``isGranted($userPermissions, $name, $level)`` + +Advanced Support Logic +---------------------- + +You can customize support checks by overriding: + +``isSupported()`` + +Use this for backward compatibility or custom permission rules. \ No newline at end of file From f06d652dcde99f0be6ca02541b5fbd2bba7775c2 Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Wed, 4 Mar 2026 17:11:13 +0100 Subject: [PATCH 4/6] remove docs/plugins/roles_and_permissions.rst --- docs/plugins/roles_and_permissions.rst | 164 ------------------------- 1 file changed, 164 deletions(-) delete mode 100644 docs/plugins/roles_and_permissions.rst diff --git a/docs/plugins/roles_and_permissions.rst b/docs/plugins/roles_and_permissions.rst deleted file mode 100644 index 08e6b288..00000000 --- a/docs/plugins/roles_and_permissions.rst +++ /dev/null @@ -1,164 +0,0 @@ -Roles and Permissions -################### - -Mautic lets you define custom permissions for each Role. These permissions determine what Users can view or do within different parts of the system. - -How Permissions Work --------------------- - -Mautic assigns permissions using bit values. These bits double as they increase: - -``1, 2, 4, 8, 16, 32, 64, 128...`` - -Bits should always follow this sequence. Avoid values like ``3`` or ``5`` because permission checks will fail. - -Example permission set: - -+--------------+-----+ -| Permission | Bit | -+--------------+-----+ -| view | 1 | -| edit | 2 | -| create | 4 | -| delete | 8 | -| full | 16 | -+--------------+-----+ - -A permission notation looks like this: - -``plugin:helloWorld:worlds:view`` - -This checks the ``view`` permission for the ``worlds`` level of the plugin. - -How Bit Storage Works -~~~~~~~~~~~~~~~~~~~~~ - -Mautic stores permissions by adding the bits of all permissions assigned to a Role. - -Examples: - -* ``view`` + ``edit`` = ``1 + 2 = 3`` -* ``view`` + ``create`` = ``1 + 4 = 5`` - -When checking a permission, Mautic verifies whether the bit exists within the stored sum. - -The ``full`` permission should always use the highest bit. It automatically grants all lower permissions. - -Using Permissions ------------------ - -Use the Security service to check permissions. - -Example in Twig: - -.. code-block:: twig - - {% if security.isGranted('user:roles:edit') %} - {# User can edit roles #} - {% endif %} - -Permission notation: - -* Core bundles: ``bundle:level:permission`` -* Plugins: ``plugin:bundle:level:permission`` - -Example: - -``user:roles:view`` - -Creating Custom Permissions ---------------------------- - -Plugins can define their own Permission classes. - -Each Permission class must: - -* Extend ``Mautic\CoreBundle\Security\Permissions\AbstractPermissions`` -* Implement ``__construct()`` -* Implement ``buildForm()`` -* Implement ``getName()`` - -Constructor -~~~~~~~~~~~ - -Inside ``__construct()``: - -1. Call ``parent::__construct($params)`` or assign ``$this->params = $params``. -2. Define ``$this->permissions`` as an array of permission levels and bits. - -Example level definition: - -* Level: ``worlds`` -* Permissions: ``use_telescope``, ``send_probe``, ``visit``, ``full`` - -Access check example: - -``plugin:helloWorld:worlds:send_probe`` - -Helper Methods for Permission Sets -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Mautic includes helper methods: - -* ``addStandardPermissions()`` adds view, edit, create, delete, publish, full -* ``addExtendedPermissions()`` adds creator-based permissions -* ``addManagePermission()`` adds a single manage permission - -buildForm() -~~~~~~~~~~~ - -``buildForm()`` adds permission fields to the Role form. - -Available helpers: - -* ``addStandardFormFields()`` -* ``addExtendedFormFields()`` -* ``addManageFormFields()`` - -getName() -~~~~~~~~~ - -This must return the bundle name in camelCase. - -Example: - -* Bundle: ``HelloWorldBundle`` -* Method return value: ``helloWorld`` -* File name: ``HelloWorldPermissions.php`` - -Permission Aliases ------------------- - -Use ``getSynonym()`` to map a permission name to another one. - -Example: - -``editown`` maps to ``edit`` if ``editown`` is not defined. - -Analyzing Permissions Before Saving ------------------------------------ - -Plugins can adjust permissions before saving. - -Use: - -``analyzePermissions()`` - -If a second pass is needed, return ``true``. -The next call will include ``$isSecondRound = true``. - -Advanced Permission Checks --------------------------- - -To override bit-based checking, extend: - -``isGranted($userPermissions, $name, $level)`` - -Advanced Support Logic ----------------------- - -You can customize support checks by overriding: - -``isSupported()`` - -Use this for backward compatibility or custom permission rules. \ No newline at end of file From deb68a72da620f8865d0da399c319b69c2bf9fcc Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Thu, 5 Mar 2026 09:45:01 +0100 Subject: [PATCH 5/6] update content to follow original version --- docs/plugins/permissions.rst | 365 +++++++++++++++++++++++------------ 1 file changed, 242 insertions(+), 123 deletions(-) diff --git a/docs/plugins/permissions.rst b/docs/plugins/permissions.rst index 73980496..6aaab383 100644 --- a/docs/plugins/permissions.rst +++ b/docs/plugins/permissions.rst @@ -1,176 +1,295 @@ -.. vale off - -.. note:: - - The content for this page requires a major update. The legacy page contains outdated and potentially inaccurate information. You can still access it in the :xref:`legacy repository`. - - If you're interested in helping develop the new content for this page and others, consider joining the documentation efforts. - - Please read the :xref:`dev docs contributing guidelines` and :xref:`Contributing to Mautic’s documentation` to get started. - -.. vale on - -Roles and Permissions -################### - -Mautic lets you define custom permissions for each Role. These permissions determine what Users can view or do within different parts of the system. - -How Permissions Work --------------------- - -Mautic assigns permissions using bit values. These bits double as they increase: +Roles and permissions +##################### -``1, 2, 4, 8, 16, 32, 64, 128...`` +Mautic defines custom Role permissions through Permission objects. -Bits should always follow this sequence. Avoid values like ``3`` or ``5`` because permission checks will fail. +How permissions work +******************** -Example permission set: +Mautic calculates permissions based on bits assigned to a Plugin level and permission. Bits are integers that increase by doubling the value - 1, 2, 4, 8, 16, 32, 64, 128, 512, 1024, and so forth. Avoid assigning numbers in between - such as 3 or 5 - because the permission won't calculate correctly. -+--------------+-----+ -| Permission | Bit | -+--------------+-----+ -| view | 1 | -| edit | 2 | -| create | 4 | -| delete | 8 | -| full | 16 | -+--------------+-----+ +For example, if ``HelloWorldBundle`` manages access to a ``worlds`` entity, the permission set for ``plugin:helloWorld:worlds`` resembles this setup: -A permission notation looks like this: +.. list-table:: + :widths: 50 50 + :header-rows: 1 -``plugin:helloWorld:worlds:view`` + * - Permission + - Bit + * - view + - 1 + * - edit + - 2 + * - create + - 4 + * - delete + - 8 + * - full + - 16 -This checks the ``view`` permission for the ``worlds`` level of the plugin. - -How Bit Storage Works -~~~~~~~~~~~~~~~~~~~~~ - -Mautic stores permissions by adding the bits of all permissions assigned to a Role. - -Examples: - -* ``view`` + ``edit`` = ``1 + 2 = 3`` -* ``view`` + ``create`` = ``1 + 4 = 5`` - -When checking a permission, Mautic verifies whether the bit exists within the stored sum. - -The ``full`` permission should always use the highest bit. It automatically grants all lower permissions. - -Using Permissions ------------------ +.. note:: -Use the Security service to check permissions. + The notation ``plugin:helloWorld:worlds:view`` typically requests permission in Mautic. This notation tells Mautic to verify the ``view`` permission for the Plugin, ``HelloWorldBundle``, within the ``worlds`` level. Levels allow Plugins to set permissions for multiple areas. -Example in Twig: +Mautic takes the summation of the bits for the permissions given to a Role and stores it in the database. For example, if a Role has ``view`` and ``edit`` access, the stored bit is 3. If given ``view`` and ``create`` access, the stored bit is 5. -.. code-block:: twig +When permission verification is necessary - for instance ``plugin:helloWorld:worlds:create`` - Mautic verifies if the Role's generated bit for ``plugin:helloWorld:worlds`` includes bit 4. If so, Mautic grants permission. - {% if security.isGranted('user:roles:edit') %} - {# User can edit roles #} - {% endif %} +.. note:: -Permission notation: + The ``full`` permission grants access to all prior permissions and should always be the highest bit. -* Core bundles: ``bundle:level:permission`` -* Plugins: ``plugin:bundle:level:permission`` +Using permissions +***************** -Example: +.. code-block:: php -``user:roles:view`` + get('mautic.security'); -Plugins can define their own Permission classes. + // Check if user is granted a single permission + if ($security->isGranted('plugin:helloWorld:worlds:view')) { + // do something + } + + // Check if user is granted multiple permissions (must be granted to all to be true) + if ($security->isGranted( + array( + 'plugin:helloWorld:worlds:view', + 'plugin:helloWorld:worlds:create', + ) + )) { + // do something + } + + // Check if user is granted to at least one permission + if ($security->isGranted( + array( + 'plugin:helloWorld:worlds:view', + 'plugin:helloWorld:worlds:edit', + ), + 'MATCH_ONE' + )) { + // do something + } + + // Get an array of user permissions + $permissions = $security->isGranted( + array( + 'plugin:helloWorld:worlds:view', + 'plugin:helloWorld:worlds:edit', + ), + 'RETURN_ARRAY' + ); -Each Permission class must: + if ($permissions['plugin:helloWorld:worlds:view']) { + // do something + } -* Extend ``Mautic\CoreBundle\Security\Permissions\AbstractPermissions`` -* Implement ``__construct()`` -* Implement ``buildForm()`` -* Implement ``getName()`` + // Check if user has access to view leads + if ($security->isGranted('lead:leads:viewother')) { + // do something + } + +To determine if a User has a specific permission, use the Mautic security service which you can obtain from the ``mautic.security`` service. + +Mautic uses specific notation to identify permissions: + +* **Core bundles**: use the format ``bundleName:permissionLevel:permission``. +* **Plugins**: append the ``plugin:`` prefix. For example, ``plugin:bundleName:permissionLevel:permission``. Plugins require this prefix because it directs Mautic to search for the permission class within the ``plugins/`` directory and the ``MauticPlugin`` namespace. + +Core bundles or Plugins set the permission level and permissions. For example, the Core UserBundle has ``users`` and ``roles`` levels with ``view``, ``edit``, ``create``, ``delete``, and ``full`` permissions for each. To verify if a User has permission to edit Roles, use: + +.. code-block:: php + + $security->isGranted('user:roles:edit'); + +Creating custom permissions +*************************** + +A Plugin creates its own set of permissions by defining a Permission class. Each permission class must extend ``Mautic\CoreBundle\Security\Permissions\AbstractPermissions``. + +.. code-block:: php + + permissions = array( + 'worlds' => array( + 'use_telescope' => 1, + 'send_probe' => 2, + 'visit' => 4, + 'full' => 1024 + ) + ); + + // Add standard category permissions + $this->addStandardPermissions('categories'); + } + + public function buildForm(FormBuilderInterface &$builder, array $options, array $data) + { + // Add standard category form fields + $this->addStandardFormFields('helloWorld', 'categories', $builder, $data); + + // Add custom 'worlds' level form fields + $builder->add( + 'helloWorld:worlds', + 'permissionlist', + array( + 'choices' => array( + 'use_telescope' => 'plugin.helloworld.permissions.use_telescope', + 'send_probe' => 'plugin.helloworld.permissions.send_probe', + 'visit' => 'plugin.helloworld.permissions.visit', + 'full' => 'mautic.core.permissions.full', + ), + 'label' => 'plugin.helloworld.permissions', + 'data' => (!empty($data['worlds']) ? $data['worlds'] : array()), + 'bundle' => 'helloWorld', + 'level' => 'worlds' + ) + ); + } + + public function getName() + { + return 'helloWorld'; + } + } + +Most permission classes require three methods: ``__construct()``, ``buildForm()``, and ``getName()``. -Constructor -~~~~~~~~~~~ +``__construct()`` +================= -Inside ``__construct()``: +The constructor performs two tasks. It calls ``parent::__construct($params)`` or sets ``$this->params = $params;``. It then defines the ``$this->permissions`` array. This array organizes permissions into levels, where each level contains specific permissions assigned to bits. -1. Call ``parent::__construct($params)`` or assign ``$this->params = $params``. -2. Define ``$this->permissions`` as an array of permission levels and bits. +For example, in the code sample, a custom level of ``worlds`` includes ``use_telescope``, ``send_probe``, ``visit``, and ``full``. To verify if a User has the ``send_probe`` permission for the ``worlds`` level, use: -Example level definition: +.. code-block:: php -* Level: ``worlds`` -* Permissions: ``use_telescope``, ``send_probe``, ``visit``, ``full`` + $mauticSecurity->isGranted('plugin:helloWorld:worlds:send_probe'); -Access check example: +Mautic provides helper methods for common permission sets: -``plugin:helloWorld:worlds:send_probe`` +.. list-table:: + :widths: 30 70 + :header-rows: 1 -Helper Methods for Permission Sets -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + * - Method + - Description + * - ``addStandardPermissions()`` + - Sets ``view``, ``edit``, ``create``, ``delete``, ``publish`` - with an option to exclude - and ``full`` permissions. + * - ``addExtendedPermissions()`` + - Sets creator-level restrictions - ``viewown``, ``viewother``, ``editown``, ``editother``, ``create``, ``deleteown``, ``deleteother``, ``publishown``, ``publishother``, and ``full``. + * - ``addManagePermission()`` + - Sets a single ``manage`` permission. -Mautic includes helper methods: +``buildForm()`` +=============== -* ``addStandardPermissions()`` adds view, edit, create, delete, publish, full -* ``addExtendedPermissions()`` adds creator-based permissions -* ``addManagePermission()`` adds a single manage permission +.. vale off -buildForm() -~~~~~~~~~~~ +The ``buildForm()`` method appends permission toggles to the Role's Form. See :doc:`/plugin_extensions/forms` for details on Form builders and review the comments in the code sample for implementation details. -``buildForm()`` adds permission fields to the Role form. +.. vale on -Available helpers: +Mautic provides complementary helper methods for common permission sets: -* ``addStandardFormFields()`` -* ``addExtendedFormFields()`` -* ``addManageFormFields()`` +.. list-table:: + :widths: 30 70 + :header-rows: 1 -getName() -~~~~~~~~~ + * - Method + - Description + * - ``addStandardFormFields()`` + - Appends the standard permission sets to the Form. + * - ``addExtendedFormFields()`` + - Appends the extended - creator restricted - permissions to the Form. + * - ``addManageFormFields()`` + - Appends the single manager element to the Form. -This must return the bundle name in camelCase. +``getName()`` +============= -Example: +This method is mandatory. The return value must match the ``bundleName`` and the filename. For example, if the bundle name is ``HelloWorldBundle``, this method returns ``helloWorld`` and the file is ``HelloWorldPermissions.php``. -* Bundle: ``HelloWorldBundle`` -* Method return value: ``helloWorld`` -* File name: ``HelloWorldPermissions.php`` +Permission aliases +****************** -Permission Aliases ------------------- +.. code-block:: php -Use ``getSynonym()`` to map a permission name to another one. + permissions`` property for that level doesn't define ``editown``. -Use: +Manipulating permissions before saving +************************************** -``analyzePermissions()`` +.. code-block:: php -If a second pass is needed, return ``true``. -The next call will include ``$isSecondRound = true``. + &$perms) { + foreach ($perms as $perm) { + $include = array(); + switch ($perm) { + case 'send_probe': + $include = array('use_telescope'); + break; + case 'visit': + $include = array('use_telescope', 'send_probe'); + break; + } + if (!empty($include)) { + foreach ($include as $r) { + list($ignore, $r) = $this->getSynonym($level, $r); + if ($this->isSupported($level, $r) && !in_array($r, $perms)) { + $perms[] = $r; + } + } + } + } + } + + return false; + } -To override bit-based checking, extend: +Plugins can adjust permissions based on other selections to prevent User error. For example, if a User has ``edit`` permission, they also require ``view`` permission. Use the ``analyzePermissions()`` method to modify permissions before Mautic persists them to the database. -``isGranted($userPermissions, $name, $level)`` +To re-adjust permissions based on factors outside the Plugin's control, return ``true`` from ``analyzePermissions()``. This triggers a second round of analysis after all other bundles and Plugins finish their processing. During this round, the ``$isSecondRound`` argument is ``true``. -Advanced Support Logic ----------------------- +Advanced ``isGranted()`` logic +============================== -You can customize support checks by overriding: +Override the parent method - ``public function isGranted($userPermissions, $name, $level)`` - to run custom logic rather than simple bit comparisons. Use this to define unique behavior for the class's own levels and individual permissions. -``isSupported()`` +Advanced ``isSupported()`` logic +================================ -Use this for backward compatibility or custom permission rules. \ No newline at end of file +The same rules apply to the ``isSupported()`` method. This method determines if a bundle or Plugin includes the requested permission and permission level. Use this to provide backward compatibility - BC - support. \ No newline at end of file From 760445bebc59a2af2f0c6b66650a299f5a62d7e3 Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Thu, 5 Mar 2026 09:56:34 +0100 Subject: [PATCH 6/6] minor wording adjustments for clarity --- docs/plugins/permissions.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/plugins/permissions.rst b/docs/plugins/permissions.rst index 6aaab383..47927a32 100644 --- a/docs/plugins/permissions.rst +++ b/docs/plugins/permissions.rst @@ -6,7 +6,7 @@ Mautic defines custom Role permissions through Permission objects. How permissions work ******************** -Mautic calculates permissions based on bits assigned to a Plugin level and permission. Bits are integers that increase by doubling the value - 1, 2, 4, 8, 16, 32, 64, 128, 512, 1024, and so forth. Avoid assigning numbers in between - such as 3 or 5 - because the permission won't calculate correctly. +Mautic calculates permissions based on bits assigned to a Plugin level and permission. Bits are integers that increase by doubling the value - 1, 2, 4, 8, 16, 32, 64, 128, 512, 1024, and so forth. Avoid assigning numbers in between, such as 3 or 5, because the permission won't calculate correctly. For example, if ``HelloWorldBundle`` manages access to a ``worlds`` entity, the permission set for ``plugin:helloWorld:worlds`` resembles this setup: @@ -29,9 +29,9 @@ For example, if ``HelloWorldBundle`` manages access to a ``worlds`` entity, the .. note:: - The notation ``plugin:helloWorld:worlds:view`` typically requests permission in Mautic. This notation tells Mautic to verify the ``view`` permission for the Plugin, ``HelloWorldBundle``, within the ``worlds`` level. Levels allow Plugins to set permissions for multiple areas. + The notation ``plugin:helloWorld:worlds:view`` typically requests permission in Mautic. This notation tells Mautic to verify the ``view`` permission for the Plugin ``HelloWorldBundle`` at the ``worlds`` level. Levels allow Plugins to set permissions for multiple areas. -Mautic takes the summation of the bits for the permissions given to a Role and stores it in the database. For example, if a Role has ``view`` and ``edit`` access, the stored bit is 3. If given ``view`` and ``create`` access, the stored bit is 5. +Mautic sums the bits for the permissions granted to a Role and stores the result in the database. For example, if a Role has ``view`` and ``edit`` access, the stored bit is 3. If given ``view`` and ``create`` access, the stored bit is 5. When permission verification is necessary - for instance ``plugin:helloWorld:worlds:create`` - Mautic verifies if the Role's generated bit for ``plugin:helloWorld:worlds`` includes bit 4. If so, Mautic grants permission. @@ -92,14 +92,14 @@ Using permissions // do something } -To determine if a User has a specific permission, use the Mautic security service which you can obtain from the ``mautic.security`` service. +To determine if a User has a specific permission, use the Mautic security service, which you can obtain from the ``mautic.security`` service. Mautic uses specific notation to identify permissions: * **Core bundles**: use the format ``bundleName:permissionLevel:permission``. * **Plugins**: append the ``plugin:`` prefix. For example, ``plugin:bundleName:permissionLevel:permission``. Plugins require this prefix because it directs Mautic to search for the permission class within the ``plugins/`` directory and the ``MauticPlugin`` namespace. -Core bundles or Plugins set the permission level and permissions. For example, the Core UserBundle has ``users`` and ``roles`` levels with ``view``, ``edit``, ``create``, ``delete``, and ``full`` permissions for each. To verify if a User has permission to edit Roles, use: +Core bundles or Plugins set the permission level and permissions. For example, the core UserBundle has ``users`` and ``roles`` levels with ``view``, ``edit``, ``create``, ``delete``, and ``full`` permissions for each. To verify if a User has permission to edit Roles, use: .. code-block:: php