Merge remote-tracking branch 'origin/main' into 5.0

# Conflicts:
#	migrations/44-50/removed-backward-incompatibility.md

Author: hleithner

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+    "githubPullRequests.ignoredPullRequestBranches": [
+        "main"
+    ]
+}

docs/general-concept/dependencies.md

@@ -0,0 +1,28 @@
+---
+title: The Dependency Injection Container
+sidebar_position: 2
+---
+# The Dependency Injection Container
+The Joomla Dependency Injection Container, DIC for short, is basically a repository of key-value pairs where: 
+- the key is a string which is (usually) the fully qualified name of a class or interface 
+- the value is an instance of the relevant class, or a function that returns an instance of that class.
+
+It doesn't *really* matter what the key is set to - as long as it's intelligible and you use the same key for putting entries in and taking entries out. Of course, it has to be unique.
+
+![DIC](_assets/dic.jpg "DIC")
+
+You put things into the container using `set()` passing: 
+- the key = the class name or interface name
+- the value = a function which returns an instance of the class (or the value can be just an instance of the class, without the enveloping function)
+- shared - a boolean defining whether the class instance may be shared or not (ie if there is a second request to the DIC to supply that instance, does it return the same instance or a new one)
+- protected - a boolean defining whether this entry into the DI container is protected or not (an error will be raised if you try to overwrite a protected entry by calling `set()` again using the same key).
+
+The function `share()` is basically the same as `set()` with the shared boolean set to true. 
+
+You get things out of the container by calling `get()` passing the key of the resource you want. The DI functionality will 
+- find the key in the container 
+- if the value isn't already a class instance, then it will run the associated function to generate an instance of the class 
+- if the resource is shared, it will store the class instance, so that on subsequent invocations of `get()` it can just return the instance 
+- return the class instance to you
+
+You can also define aliases for each key in the container, which means that you call `get()` passing either the key or an alias of the key. 

docs/general-concept/dependency-injection/DIC.md

@@ -0,0 +1,25 @@
+---
+title: Basic Concept
+sidebar_position: 1
+---
+# Basic Concept
+The basic idea behind Joomla dependency injection is that developers should no longer get access to key Joomla class instances by calling
+```php
+$obj = new JoomlaClass();
+or
+$obj = JoomlaClass::getInstance();
+```
+Instead they should make a request to the Dependency Injection Container (DIC):
+```php
+$obj = $container( – please give me an instance of JoomlaClass – );
+```
+or get an instance via the Application class or a Factory class which has been obtained from the DIC.
+
+The main reason for this is to enable better testing by making it easier to mock classes. If the code has multiple calls to `JoomlaClass::getInstance()` then it's hard to mock that class for testing.
+
+If instead the code always uses the DIC to get an instance of the class, then to mock it all we have to do is put the mocked class into the DIC instead of the real one. 
+To make it less obvious that a specific class is being requested we can ask instead for a class which meets a particular interface:
+```php
+$obj = $container( – please give me an instance of a class that implements JoomlaInterface – );
+```
+The DIC will then return either the real class or the mocked class, depending upon how it has been configured. However, using a class name versus an interface name has no bearing on the functionality; as we shall see, the key used for putting things into and getting things out of the DIC is just a string, so we just have to ensure that we use the same key string for both operations.

docs/general-concept/dependency-injection/_assets/child-dic.jpg

@@ -0,0 +1,45 @@
+---
+title: Dependency Injection Issues
+sidebar_position: 7
+---
+# Dependency Injection Issues
+Dependency Injection was introduced in Joomla 4, with the intention of removing direct access to most key classes via `getInstance()` calls, including via `Factory::` calls, and many of these API calls are deprecated in Joomla 4. Note that not all `getInstance()` calls are deprecated; examples which are not deprecated include `Uri::getInstance()` and `Filter\InputFilter::getInstance()`. 
+
+However, some issues do remain, which you should be aware of. Early versions of Joomla 5 still have a lot of these `getInstance` calls!
+
+## Toolbar::getInstance()
+The `Toolbar` class is used for managing the buttons on the forms within the Joomla administrator back-end. The [Toolbar API](https://api.joomla.org/cms-4/classes/Joomla-CMS-Toolbar-Toolbar.html) documentation seems to suggest that we should replace 
+```php
+$bar = Toolbar::getInstance('toolbar');
+```
+with
+```php
+$bar = Factory::getContainer()->get(ToolbarFactoryInterface::class)->createToolbar('toolbar');
+```
+However, this currently won't work. The problem is that all the other Joomla code uses `getInstance('toolbar')` to access the Toolbar class, including the code in administrator/modules/mod_toolbar/mod_toolbar.php which renders the toolbar. The `getInstance` method keeps track of the Toolbar instances in a local static variable `$instances`, and returns the same Toolbar instance on repeated invocations.
+
+So if you use the second approach above you will get a Toolbar instance, but it won't be the same Toolbar instance as is stored in the `$instances` variable. It won't then be picked up by the Toolbar module, and so won't be rendered on the form. 
+
+## Table::getInstance()
+Usually a Table instance is created by the MVCFactory class by calling `getTable()` in your Model. However, there are other cases where you may want one:
+- in your Table class code you may want another instance of your own component table to verify if an `alias` field entered by a user already exists
+- you may wish to access the Table class of another component - eg of com_categories.
+
+Neither of these is possible via your component's MVCFactory class as 
+- it creates Table classes for your component alone, and,
+- in your Table code by default you've no pointer back to MVCFactory class instance
+
+However, you can obtain instances by a more convoluted route, eg for com_content 
+```php
+Factory::getApplication()->bootComponent('content')->getMVCFactory()->createTable($name, $prefix, $config);
+```
+You can also use this method to boot your own component, to get another instance of your own Table.
+
+## Categories::getInstance()
+If you use Categories in your component then you may want to use the Categories API, for example in a custom router, or in a site CategoryModel. The old method of calling
+```php
+$categories = Categories::getInstance(...); 
+```
+is deprecated.
+
+You can get a CategoryFactory from your child DIC when you instantiate your Extension, but unfortunately it's not passed down via the MVCFactory class to your Model. One possible solution is to store the CategoryFactory reference as a static variable of your Extension class, as described in [Implementing Categories in your Component](../../using-core-functions/categories/implementing-categories-in-components.md).

docs/general-concept/dependency-injection/_assets/dic.jpg

@@ -0,0 +1,67 @@
+---
+title: Extensions and Child Containers
+sidebar_position: 4
+---
+# Extensions and Child Containers
+Whenever Joomla boots an extension it creates a child DIC, solely for use of that extension. It's shown diagrammatically below.
+
+![Child DIC](_assets/child-dic.jpg "Child DIC")
+
+The child DIC has a `parent` pointer to the main DIC, and acts similarly to the main DIC, but not exactly:
+- Whenever `set()` is called on this child DIC the key-value pair is inserted into the child container.
+- Whenever `get()` is called on it, the resource is obtained from the child container, but if it's not found there then the parent container is searched also. 
+
+From Joomla version 4 the Joomla developers are requesting that extension developers use dependency injection for their extensions by defining a services/provider.php file. The loading of an extension is then a two-step process, handled within the services/provider.php file::
+1. The extension class is entered into child DIC
+2. The extension class is retrieved from the child DIC, creating an instance of the class
+
+Let's look at a minimal example of this for com_example, with namespace Mycompany\Component\Example.
+```php
+use Joomla\CMS\Extension\ComponentInterface;
+use Joomla\DI\Container;
+use Joomla\DI\ServiceProviderInterface;
+use Mycompany\Component\Example\Administrator\Extension\ExampleComponent;
+
+return new class implements ServiceProviderInterface {
+    public function register(Container $container): void 
+    {
+        $container->set(
+            ComponentInterface::class,
+            function (Container $container) {
+                $component = new ExampleComponent();
+                return $component;
+            }
+        );
+    }
+};
+```
+We can see that when Joomla does a `require` of this php file, then it will return a class instance:
+```php
+$provider = require $path;  // $path points to the relevant services/provider.php file
+```
+The variable `$provider` then points to an object which is an instance of this anonymous class. Also the class implements `Joomla\DI\ServiceProviderInterface`, which basically means that it has a method called `register` with the above signature.
+
+When next Joomla does 
+```php
+if ($provider instanceof ServiceProviderInterface) {
+    $provider->register($container);
+```
+the `register` function will be called, which will put into the child DIC an entry with
+- key =  ComponentInterface::class – this is just a PHP shorthand way of specifying the string 'Joomla\CMS\Extension\ComponentInterface'
+- value = a function which returns a new instance of ExampleComponent, which is the [Extension class](../extension-and-dispatcher/extension-component.md) of `com_example`
+
+Then when  Joomla executes the code:
+```php
+$extension = $container->get($type);
+```
+the function above will run and will return a new instance of `ExampleComponent`. 
+
+You can follow through the Joomla code yourself in libraries/src/Extension/ExtensionManagerTrait.php, and confirm that the above pattern also applies to modules and plugins. 
+
+Notice also the following line in that file:
+```php
+if ($extension instanceof BootableExtensionInterface) {
+            $extension->boot($container);
+        }
+``` 
+So if the Extension class implements `BootableExtensionInterface` then Joomla will immediately call the `boot` function of the Extension instance, as described in the [Extension documentation](../extension-and-dispatcher/extension-component.md).

docs/general-concept/dependency-injection/basic-concept.md

@@ -0,0 +1,7 @@
+---
+title: Dependency Injection
+sidebar_position: 3
+---
+Dependency Injection was introduced in Joomla 4 to try to enable better testing of the Joomla code. If you're not familiar with the concepts of dependency injection then you may find the following videos useful: [Dependency Injection in PHP](https://www.youtube.com/watch?v=igx3bIl1T_c) and [DI Container](https://www.youtube.com/watch?v=78Vpg97rQwE). The videos are not related to Joomla, but do present good background information.
+
+There are also a couple of Joomla-related videos, covering [Joomla 4 Dependency Injection](https://youtu.be/Y2oe73C1Q54) and [services/provider.php](https://youtu.be/n2fdf2szI_A).