docs: add docs

user_guide_src/source/changelogs/v4.5.4.rst

@@ -32,6 +32,9 @@ Bugs Fixed
 
 - **CURLRequest:** Fixed a bug preventing the use of strings for ``version`` in the config array
   when making requests.
+- **Registrars:** Added check to prevent Auto-Discovery of Registrars from running
+  twice. If it is executed twice, an exception will be raised. See
+  :ref:`upgrade-454-registrars-with-dirty-hack`.
 
 See the repo's
 `CHANGELOG.md <https://github.com/codeigniter4/CodeIgniter4/blob/develop/CHANGELOG.md>`_

user_guide_src/source/installation/upgrade_454.rst

@@ -20,6 +20,28 @@ Mandatory File Changes
 Breaking Changes
 ****************
 
+.. _upgrade-454-registrars-with-dirty-hack:
+
+Registrars with Dirty Hack
+==========================
+
+To prevent Auto-Discovery of :ref:`registrars` from running twice, when a registrar
+class is loaded or instantiated, if it instantiates a Config class (which extends
+``CodeIgniter\Config\BaseConfig``), ``ConfigException`` will be raised.
+
+This is because if Auto-Discovery of Registrars is performed twice, duplicate
+values may be added to properties of Config classes.
+
+All registrar classes (**Config/Registrar.php** in all namespaces) must be modified
+so that they do not instantiate any Config class when loaded or instantiated.
+
+If the packages/modules you are using provide such registrar classes, the registrar
+classes in the packages/modules need to be fixed.
+
+The following is an example of code that will no longer work:
+
+.. literalinclude:: upgrade_454/001.php
+
 *********************
 Breaking Enhancements
 *********************

user_guide_src/source/installation/upgrade_454/001.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace CodeIgniter\Shield\Config;
+
+use Config\App;
+
+class Registrar
+{
+    public function __construct()
+    {
+        $config = new App(); // Bad. When this class is instantiated, Config\App will be instantiated.
+
+        // Does something.
+    }
+
+    public static function Pager(): array
+    {
+        return [
+            'templates' => [
+                'module_pager' => 'MyModule\Views\Pager',
+            ],
+        ];
+    }
+
+    public static function hack(): void
+    {
+        $config = config('Cache');
+
+        // Does something.
+    }
+}
+
+Registrar::hack(); // Bad. When this class is loaded, Config\Cache will be instantiated.