Merge branch '5.x' into ui-Displaying-Elements-Based-on-User-Permissions

RCheesley · web-flow · commit 614a8dd98b9e · 2024-10-24T13:38:58.000+01:00
diff --git a/.all-contributorsrc b/.all-contributorsrc
@@ -32,6 +32,15 @@
         "doc",
         "review"
       ]
+    },
+    {
+      "login": "ifeoluwafavour",
+      "name": "Ife",
+      "avatar_url": "https://avatars.githubusercontent.com/u/64481442?v=4",
+      "profile": "http://ifeoluwafavour.hashnode.dev",
+      "contributions": [
+        "doc"
+      ]
     }
   ],
   "contributorsPerLine": 7,
@@ -40,5 +49,6 @@
   "repoType": "github",
   "repoHost": "https://github.com",
   "skipCi": true,
-  "commitConvention": "angular"
+  "commitConvention": "angular",
+  "commitType": "docs"
 }
diff --git a/.github/styles/config/vocabularies/Mautic/accept.txt b/.github/styles/config/vocabularies/Mautic/accept.txt
diff --git a/.github/workflows/linting.yml b/.github/workflows/linting.yml
@@ -4,48 +4,49 @@ on:
 
 jobs:
   prose:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04  # See https://github.com/errata-ai/vale-action/issues/128 before upgrading
+    permissions:
+      contents: read
+      pull-requests: write
     steps:
-    - name: Checkout
-      uses: actions/checkout@v4
-      with:
-        fetch-depth: 0
-
-    - uses: actions/setup-python@v4
-      with:
-        python-version: '3.x'
-        cache: 'pip'
-
-    - name: Install Python dependencies
-      run: pip3 install -r docs/requirements.txt
-
-    - name: Vale
-      uses: errata-ai/vale-action@reviewdog
-      with:
-        # Please keep version in sync with the version in .gitpod.Dockerfile for a consistent experience
-        version: 2.29.2
-        fail_on_error: true
-      env:
-        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.x'
+          cache: 'pip'
+
+      - name: Install Python dependencies
+        run: pip3 install -r docs/requirements.txt
+
+      - name: Vale
+        uses: errata-ai/vale-action@reviewdog
+        with:
+          version: 3.7.1  # Please keep version in sync with the version in .gitpod.Dockerfile for a consistent experience
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
   build:
     runs-on: ubuntu-latest
     steps:
-    - name: Checkout
-      uses: actions/checkout@v4
-
-    - uses: actions/setup-python@v4
-      with:
-        python-version: '3.x'
-        cache: 'pip'
-
-    - name: Install Python dependencies
-      run: pip3 install -r docs/requirements.txt
-
-    - name: Build docs
-      working-directory: docs
-      run: make html
-
-    - name: Check links
-      working-directory: docs
-      run: make checklinks
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.x'
+          cache: 'pip'
+
+      - name: Install Python dependencies
+        run: pip3 install -r docs/requirements.txt
+      
+      - name: Build docs
+        working-directory: docs
+        run: make html
+
+      - name: Check links
+        working-directory: docs
+        run: make checklinks
diff --git a/.gitpod.Dockerfile b/.gitpod.Dockerfile
@@ -2,7 +2,7 @@ FROM python:3.11
 
 # Don't update to a higher version until this issue has been fixed: https://github.com/errata-ai/vale/issues/528
 # Please keep version in sync with the version in .github/workflows/linting.yml for a consistent experience
-ENV VALE_VERSION=2.29.2
+ENV VALE_VERSION=3.7.1
 
 WORKDIR /workspace
 
diff --git a/.gitpod.yml b/.gitpod.yml
@@ -1,6 +1,5 @@
-# Since Gitpod doesn't support caching custom Dockerfiles yet, we temporarily
-# use this once which has Python 3.9 and Vale preinstalled.
-image: dennisameling/python-vale:latest
+image: 
+  file: .gitpod.Dockerfile
 
 tasks:
   - before: pip install -r docs/requirements.txt
@@ -9,7 +8,6 @@ tasks:
 vscode:
   extensions:
     - ms-python.python
-    - lextudio.restructuredtext
-    - errata-ai.vale-server
+    - lextudio.restructuredtext@190.1.4 # See https://github.com/mautic/user-documentation/pull/334#issuecomment-2405922370 before upgrading.    - errata-ai.vale-server
     - eamodio.gitlens
     - trond-snekvik.simple-rst
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -5,5 +5,8 @@
     "esbonio.sphinx.confDir": "${workspaceFolder}/docs",
     "restructuredtext.pythonRecommendation.disabled": true,
     "restructuredtext.preview.name": "sphinx",
+    "esbonio.sphinx.pythonCommand": "python3",
+    "esbonio.sphinx.buildCommand": "sphinx-build",
+    "esbonio.logging.level": "debug",
     "gitlens.showWhatsNewAfterUpgrades": false
 }
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 [![Documentation Status][RTD badge URL]][RTD URL]
 <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
-[![All Contributors](https://img.shields.io/badge/all_contributors-3-orange.svg?style=flat-square)](#contributors-)
+[![All Contributors](https://img.shields.io/badge/all_contributors-4-orange.svg?style=flat-square)](#contributors-)
 <!-- ALL-CONTRIBUTORS-BADGE:END -->
 
 [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/mautic/developer-documentation-new)
@@ -120,9 +120,10 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
 <table>
   <tbody>
     <tr>
-      <td align="center"><a href="https://robert-parker.me"><img src="https://avatars.githubusercontent.com/u/25473863?v=4?s=100" width="100px;" alt="Robert Parker"/><br /><sub><b>Robert Parker</b></sub></a><br /><a href="https://github.com/mautic/developer-documentation-new/commits?author=diaboloshogunate" title="Documentation">📖</a></td>
-      <td align="center"><a href="https://github.com/shinde-rahul"><img src="https://avatars.githubusercontent.com/u/1046788?v=4?s=100" width="100px;" alt="Rahul Shinde"/><br /><sub><b>Rahul Shinde</b></sub></a><br /><a href="https://github.com/mautic/developer-documentation-new/commits?author=shinde-rahul" title="Documentation">📖</a></td>
-      <td align="center"><a href="https://dennisameling.com"><img src="https://avatars.githubusercontent.com/u/17739158?v=4?s=100" width="100px;" alt="Dennis Ameling"/><br /><sub><b>Dennis Ameling</b></sub></a><br /><a href="https://github.com/mautic/developer-documentation-new/commits?author=dennisameling" title="Documentation">📖</a> <a href="https://github.com/mautic/developer-documentation-new/pulls?q=is%3Apr+reviewed-by%3Adennisameling" title="Reviewed Pull Requests">👀</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://robert-parker.me"><img src="https://avatars.githubusercontent.com/u/25473863?v=4?s=100" width="100px;" alt="Robert Parker"/><br /><sub><b>Robert Parker</b></sub></a><br /><a href="https://github.com/mautic/developer-documentation-new/commits?author=diaboloshogunate" title="Documentation">📖</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/shinde-rahul"><img src="https://avatars.githubusercontent.com/u/1046788?v=4?s=100" width="100px;" alt="Rahul Shinde"/><br /><sub><b>Rahul Shinde</b></sub></a><br /><a href="https://github.com/mautic/developer-documentation-new/commits?author=shinde-rahul" title="Documentation">📖</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://dennisameling.com"><img src="https://avatars.githubusercontent.com/u/17739158?v=4?s=100" width="100px;" alt="Dennis Ameling"/><br /><sub><b>Dennis Ameling</b></sub></a><br /><a href="https://github.com/mautic/developer-documentation-new/commits?author=dennisameling" title="Documentation">📖</a> <a href="https://github.com/mautic/developer-documentation-new/pulls?q=is%3Apr+reviewed-by%3Adennisameling" title="Reviewed Pull Requests">👀</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="http://ifeoluwafavour.hashnode.dev"><img src="https://avatars.githubusercontent.com/u/64481442?v=4?s=100" width="100px;" alt="Ife"/><br /><sub><b>Ife</b></sub></a><br /><a href="https://github.com/mautic/developer-documentation-new/commits?author=ifeoluwafavour" title="Documentation">📖</a></td>
     </tr>
   </tbody>
 </table>
diff --git a/docs/components/cache.rst b/docs/components/cache.rst
@@ -43,6 +43,7 @@ All you need to do now is to clear all tagged items:
 .. code-block:: php
 
     $cache->invalidateTags(['firstTag']);
+
 Pools clearing
 ==============
 
@@ -54,6 +55,7 @@ Cache Pools include methods to delete a cache item, some of them, or all of them
 .. code-block:: php
 
     $isDeleted = $cache->deleteItem('user_'.$userId);
+
 Use the ``Psr\\Cache\\CacheItemPoolInterface::deleteItems`` method to delete several cache items simultaneously - it returns true only if all the items have been deleted, even when any or some of them don't exist.
 
 Configuration
@@ -68,6 +70,7 @@ These are the default settings:
     'cache_adapter' => 'mautic.cache.adapter.filesystem',
     'cache_prefix' => 'app',
     'cache_lifetime' => 86400
+
 They can be overridden in ``local.php`` like this:
 
 .. code-block:: php
@@ -84,6 +87,7 @@ Delivered adapters
 - ``mautic.cache.adapter.memcached``
 
 .. code-block:: php
+    
     'memcached' => [
         'servers' => ['memcached://localhost'],
         'options' => [
diff --git a/docs/design/retrieving_system_information.rst b/docs/design/retrieving_system_information.rst
@@ -1,10 +1,10 @@
 Retrieving Mautic settings in Twig
-=============================================
+##################################
 
 Mautic allows you to access configuration settings directly in Twig templates using the ``configGetParameter`` function. This feature is particularly useful for creating display conditions or showing existing data in your templates.
 
 Basic usage
------------
+***********
 
 To retrieve a setting, use the ``configGetParameter`` function with the parameter name as its argument:
 
@@ -13,7 +13,7 @@ To retrieve a setting, use the ``configGetParameter`` function with the paramete
    {{ configGetParameter('parameter_name') }}
 
 Display conditions
-------------------
+==================
 
 Use ``configGetParameter`` in conditional statements to control the display of content based on configuration settings:
 
@@ -24,7 +24,7 @@ Use ``configGetParameter`` in conditional statements to control the display of c
    {% endif %}
 
 Displaying configuration values
--------------------------------
+===============================
 
 To directly display a configuration value in your template, use the following syntax:
 
@@ -45,12 +45,12 @@ For example, to display the API OAuth2 access token lifetime:
    API OAuth2 Access Token Lifetime: {{ configGetParameter('api_oauth2_access_token_lifetime') }}
 
 Finding available parameters
-----------------------------
+============================
 
 The ``/config/local.php`` file contains available configuration parameters, once you save the global configuration form for the first time. This file contains the complete list of settings that are accessible using ``configGetParameter``.
 
 Identifying parameter names
----------------------------
+===========================
 
 To find the correct parameter name for a specific setting:
 
@@ -67,7 +67,7 @@ For example, if you see:
 The corresponding parameter name would be ``api_oauth2_access_token_lifetime``.
 
 Additional information
-----------------------
+**********************
 
 - Be cautious when displaying sensitive configuration data in templates.
 - Always consider providing default values when using configuration parameters to handle cases where the setting aren't defined.
diff --git a/docs/index.rst b/docs/index.rst
@@ -56,8 +56,7 @@ There are several ways to support Mautic other than contributing with code.
    :caption: Design and UX
    :hidden:
 
-   design/retrieving_system_settings
-   design/displaying_elements_based_on_user_permissions
+   design/retrieving_system_information
 
 .. toctree::
    :maxdepth: 2
diff --git a/docs/links/symfony_docs_event_subscribers.py b/docs/links/symfony_docs_event_subscribers.py
@@ -0,0 +1,8 @@
+from . import link
+
+link_name = "symfony-event-subscribers"
+link_text = "Symfony's documentation"
+link_url = "https://symfony.com/doc/current/components/event_dispatcher.html#using-event-subscribers"
+
+link.xref_links.update({link_name: (link_text, link_url)})
+
diff --git a/docs/plugins/dependencies.rst b/docs/plugins/dependencies.rst
@@ -7,4 +7,4 @@ The first is to include dependencies with your distributable Plugin package. How
 
 The recommended approach is to use Composer and make the Plugin available through the new Marketplace.
 
-:ref: `marketplace/listing:Preparing your Plugin for the Marketplace` by leveraging :xref:`Mautic's Composer plugin`. For detailed instructions, refer to the :doc:`/marketplace/listing`.
+:ref:`marketplace/listing:Preparing your Plugin for the Marketplace` by leveraging :xref:`Mautic's Composer plugin`. For detailed instructions, refer to the :doc:`/marketplace/listing`.
diff --git a/docs/plugins/from-4-to-5.rst b/docs/plugins/from-4-to-5.rst
@@ -1,17 +1,17 @@
 Update Plugins for Mautic 5
-=======================================
+###########################
 
 Here is a list of steps that most of the Plugins may need to take to upgrade from Mautic 4 to Mautic 5. You should be able to get through each step, make a commit, move to the next one and once you are at finished you have upgraded your Plugin.
 
 Continuous Integration
--------------------------
+**********************
 
 If you don't have CI configured, this is the time to do it. This is an optional step but it makes sense to do it at the beginning rather than later. Here's how to get it done: :doc:`/plugins/continuous-integration`.
 
 In your PR add also support for PHP 8.1 and 8.2, and upgrade the Mautic version from 4.4 to 5.1. One more thing is that Mautic 5 have ``local.php`` in ``config/local.php`` instead of ``app/config/local.php`` so update that as well.
 
 Autowiring
--------------
+**********
 
 Mautic 5 comes with autowiring of PHP services which means the developer experience is much improved, and the code size is reduced.
 
@@ -24,7 +24,7 @@ To quickly verify that the wiring of services is complete and configured correct
   .. note:: Ideally, you should be able to delete the whole ``services`` section from your ``config.php`` file, but do that as a cherry on top once you are sure everything is working as the later steps in this process may yet cause you difficulties.
 
 ``config.php`` - controllers
----------------------------
+****************************
 
 ``config.php`` should be much lighter now when all services are gone after autowiring is configured. There is one more thing to verify. The controllers are now defined with a different syntax. Here is an example:
 
@@ -36,7 +36,7 @@ To quickly verify that the wiring of services is complete and configured correct
 Symfony 5 is much more explicit. That's a good thing even if it's longer. You don't have to guess what the syntax is. It's basically just standard FQCN (Fully Qualified Class Name) with the full method name behind the 2 colons. You don't even need to call the controller method `*Action` any more.
 
 Rendering views
-------------------
+***************
 
 As Symfony 5 removed the PHP templating engine, Mautic had to switch to Twig. Your Plugin must also update the any views from PHP to Twig. Here is a helpful resource on how to migrate the ``*.html.php`` files to ``*.html.twig`` files:
 
@@ -58,7 +58,7 @@ Running this command is faster than refreshing all the views in the browser. It
 .. vale off
 
 The Integration class
-------------------------
+*********************
 
 .. vale on
 
@@ -72,7 +72,7 @@ If you went ahead and deleted all services from ``config.php``, you may experien
 .. note:: Replace `[MY_INTEGRATION]` with your Plugin name.
 
 Compiler passes
-------------------
+***************
 
 If your Plugin uses a compiler pass, you may have to verify that it works correctly. In many cases you may have to change the service alias with FQCN like so:
 
@@ -82,7 +82,7 @@ If your Plugin uses a compiler pass, you may have to verify that it works correc
    + ->setDecoratedService(EmailType::class, 'mautic.form.type.email.inner')
 
 Getting container in tests
------------------------------
+**************************
 
 This one is a quick find and replace:
 
@@ -94,7 +94,7 @@ This one is a quick find and replace:
 Notice you can also use FQCN instead of string service keys which is more convenient.
 
 Automated refactoring
-------------------------
+**********************
 
 Your Plugin should be working on Mautic 5 by now. Wouldn't it be great to shorten the code a little more? Mautic 5 uses PHP 8.0+ so can take advantage of the syntax. Rector can upgrade the code for you.
 
@@ -103,14 +103,14 @@ Run ``bin/rector process plugins/MyBundle`` and review the changes.
 .. note:: Update MyBundle with your bundle name.
 
 Automated code style
------------------------
+********************
 
 Another great way how to improve your Plugin code base quality is to run the CS Fixer: ``bin/php-cs-fixer fix plugins/MyBundle``.
 
 .. note:: Update MyBundle with your bundle name.
 
 Static analysis
--------------------
+***************
 
 PHPSTAN is another amazing tool that detects bugs for you. It's better to run it on the whole codebase including core Mautic, so it's aware of all classes.
 
@@ -119,6 +119,6 @@ Run ``composer phpstan``
 If your Plugin has more PHPSTAN errors than you can handle right now, consider using :xref:`PHPSTAN baseline`. It allows you to store your tech debt to a single file and it forces you to write better code from now on. And you can reduce the baseline by small chunks every month to get to 0.
 
 Conclusion
-----------
+**********
 
 This list of steps is compiled by Mautic Plugin developers for the Mautic Plugin developers. If you find that some common problem isn't addressed here, please add it.
diff --git a/docs/requirements.txt b/docs/requirements.txt

Original file line number	Diff line number	Diff line change
`@@ -5,5 +5,8 @@`
`5`	`5`	`"esbonio.sphinx.confDir": "${workspaceFolder}/docs",`
`6`	`6`	`"restructuredtext.pythonRecommendation.disabled": true,`
`7`	`7`	`"restructuredtext.preview.name": "sphinx",`
	`8`	`+ "esbonio.sphinx.pythonCommand": "python3",`
	`9`	`+ "esbonio.sphinx.buildCommand": "sphinx-build",`
	`10`	`+ "esbonio.logging.level": "debug",`
`8`	`11`	`"gitlens.showWhatsNewAfterUpgrades": false`
`9`	`12`	`}`