From 17e003e2bc79f63f9e82a74416028f4584e6472e Mon Sep 17 00:00:00 2001
From: erinlefeyijimi <feyijimi.erinle@datamellon.com>
Date: Thu, 20 Nov 2025 10:04:07 +0100
Subject: [PATCH 1/2] 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 <feyijimi.erinle@datamellon.com>
Date: Mon, 24 Nov 2025 12:27:07 +0100
Subject: [PATCH 2/2] 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