Merge pull request #162 from robbiejackson/dependency-injection

Dependency Injection done

Author: HLeithner

docs/general-concept/dependency-injection/DIC.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 class name or interface name 
+- a function which returns an instance of the class (or the value can be just an instance of the class, without the enveloping function) 
+- 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)
+- 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/_assets/child-dic.jpg

@@ -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/dic.jpg

@@ -0,0 +1,43 @@
+---
+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. However, not all `getInstance()` calls are deprecated; examples which are not deprecated include `Uri::getInstance()` and `Filter\InputFilter::getInstance()`. 
+
+## 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/basic-concept.md

@@ -0,0 +1,66 @@
+---
+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/di-issues.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).

docs/general-concept/dependency-injection/extension-child-containers.md

@@ -0,0 +1,71 @@
+---
+title: JConfig Example
+sidebar_position: 3
+---
+# JConfig Example
+Early in its initialisation phase Joomla initialises the dependency injection container (DIC) by calling `createContainer()` which is in library/src/Factory.php. This results in the `register()` function being called in each of the class files in libraries/src/Service/Provider. By looking through those files you can see what gets put into the DIC upon initialisation. 
+
+Let's look at library/src/Service/Provider/Config.php, which sets up the configuration class `JConfig`. Here's what gets executed when the `register()` function is called:
+```php
+$container->alias('config', 'JConfig')
+    ->share(
+        'JConfig',
+        function (Container $container) {
+            if (!is_file(JPATH_CONFIGURATION . '/configuration.php')) {
+                return new Registry();
+            }
+
+            \JLoader::register('JConfig', JPATH_CONFIGURATION . '/configuration.php');
+
+            if (!class_exists('JConfig')) {
+                throw new \RuntimeException('Configuration class does not exist.');
+            }
+
+            return new Registry(new \JConfig());
+        },
+        true
+    );
+```
+Here's an explanation of the code:
+```php
+$container->alias('config', 'JConfig')
+```
+This sets up an alias in the DIC so that you can call `$container->get('config')` as well as `$container->get('JConfig')`. Notice that the return value of this function is again the `$container` so that you can chain function calls. 
+
+Next there's a call to `share()` passing 3 parameters:
+1. the string 'JConfig'
+2. a function which returns something, which will look at shortly
+3. `true` – for the `protected` parameter, which means that if another call is made to try and put an entry with key 'JConfig' into the DIC then it will be rejected (rather than overwriting this entry).
+
+Remember that `share()` is the same as `set()` with the `shared` parameter set to `true`, so that the same class instance is going to be returned for each `get('JConfig')` call.
+
+When some part of the Joomla code calls 
+```php
+$container->get('JConfig')
+```
+then the function passed as parameter 2 above will be executed. 
+
+The Joomla global configuration is held in the `JConfig` class in configuration.php in the top level folder of your Joomla instance, so that function does the following:
+1. Checks if configuration.php exists, and if it doesn't just return an empty set of configuration data
+2. Registers the 'JConfig' class in configuration.php, so that the autoloader knows where to find it
+3. Checks if the class exist – this will force PHP to call the Joomla autoloader function, which will then do a `require` of configuration.php. If the `JConfig` class still doesn't exist, then an exception will be raised.
+4. The `JConfig` class is instantiated, and passed into a Registry object which is then returned.
+
+As this DIC entry is shared, the Registry instance will be stored in the DIC and will be returned on subsequent calls to `get('JConfig')`.
+
+So you can obtain the global configuration parameters by 
+```php
+use Joomla\CMS\Factory;
+$container = Factory::getContainer();
+$container->get('JConfig');   // or ...
+$container->get('config');
+```
+These calls go directly to the DIC to obtain the shared JConfig instance.
+
+Or you can obtain them via the Application instance, which has already got them from the DIC:
+```php
+use Joomla\CMS\Factory;
+$application = Factory::getApplication();
+$application->getConfig();   // or, to get a particular parameter:
+$application->get($paramName, $defaultValue);
+```

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

@@ -0,0 +1,52 @@
+---
+title: Modules and Plugins
+sidebar_position: 6
+---
+# Modules and Plugins
+The service provider files for modules and plugins are considerably more straightforward than those for components. If you look through your Joomla instance modules and plugins folders then you'll find several examples of services/provider.php files.
+
+## Modules
+For example, for mod_breadcrumbs in Joomla 5 we have:
+```php
+use Joomla\CMS\Extension\Service\Provider\Module;
+
+public function register(Container $container): void
+{
+    $container->registerServiceProvider(new ModuleDispatcherFactory('\\Joomla\\Module\\Breadcrumbs'));
+    $container->registerServiceProvider(new HelperFactory('\\Joomla\\Module\\Breadcrumbs\\Site\\Helper'));
+
+    $container->registerServiceProvider(new Module());
+}
+```
+This module uses the standard Joomla\CMS\Extension\Service\Provider\Module class to generate its extension class \Joomla\CMS\Extension\Module. 
+
+It has 2 dependencies:
+1. It uses a ModuleDispatcherFactory class to instantiate its own Dispatcher.php in src/Dispatcher/Dispatcher.php
+2. It uses a HelperFactory to find its helper file in src/Helper/BreadcrumbsHelper.php
+
+## Plugins
+For example for the custom field color plugin in plugins/fields/color
+```php
+use Joomla\Plugin\Fields\Color\Extension\Color;
+
+public function register(Container $container)
+{
+    $container->set(
+        PluginInterface::class,
+        function (Container $container) {
+            $plugin     = new Color(
+                $container->get(DispatcherInterface::class),
+                (array) PluginHelper::getPlugin('fields', 'color')
+            );
+            $plugin->setApplication(Factory::getApplication());
+
+            return $plugin;
+        }
+    );
+}
+```
+The plugin's Extension class is Color, which gets instantiated with 2 parameters being passed into its constructor:
+- the EventDispatcher class – this is obtained from the parent DIC, having been originally put into it from libraries/src/Service/Provider/Dispatcher.php when Joomla initialised
+- the plugin stdClass object which Joomla has used to store plugin data (id, name, type and params).
+
+This is a standard pattern that you can use for your own plugins. You can obviously get the Application instance by calling `Factory::getApplication` either in the services/provider.php file or in your standard plugin code.