Merge pull request #163 from robbiejackson/di-tidy-up

Some tidy up and previous DI page removed

Author: HLeithner

docs/general-concept/dependencies.md

@@ -12,10 +12,10 @@ It doesn't *really* matter what the key is set to - as long as it's intelligible
 ![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 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. 
 

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

@@ -3,7 +3,9 @@ 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()`. 
+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 

docs/general-concept/dependency-injection/di-issues.md

@@ -21,6 +21,7 @@ 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 
     {

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

@@ -66,6 +66,7 @@ Or you can obtain them via the Application instance, which has already got them
 ```php
 use Joomla\CMS\Factory;
 $application = Factory::getApplication();
-$application->getConfig();   // or, to get a particular parameter:
+$application->getConfig();   
+// or, to get a particular parameter:
 $application->get($paramName, $defaultValue);
 ```

docs/general-concept/dependency-injection/jconfig-example.md

@@ -47,6 +47,6 @@ public function register(Container $container)
 ```
 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).
+- the plugin stdClass object which Joomla has traditionally 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. 

docs/general-concept/dependency-injection/modules-and-plugins.md

@@ -17,6 +17,7 @@ use Joomla\CMS\MVC\Factory\MVCFactoryInterface;
 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 
     {
@@ -61,7 +62,7 @@ Let's look first at the ComponentDispatcherFactory
 ```php
 $component = new MVCComponent($container->get(ComponentDispatcherFactoryInterface::class));
 ```
-The code `$container->get(ComponentDispatcherFactoryInterface::class)` runs the function in the child DIC associated with the ComponentDispatcherFactoryInterface::class key, and the object returned:
+The code `$container->get(ComponentDispatcherFactoryInterface::class)` runs the function in the child DIC associated with the ComponentDispatcherFactoryInterface::class key. This function is found in libraries/src/Extension/Service/Provider/ComponentDispatcherFactory.php, and the object returned:
 ```php
 new \Joomla\CMS\Dispatcher\ComponentDispatcherFactory($this->namespace, $container->get(MVCFactoryInterface::class))
 ```
@@ -83,12 +84,12 @@ Let's take another look at the line when the ComponentDispatcherFactory is insta
 ```php
 new \Joomla\CMS\Dispatcher\ComponentDispatcherFactory($this->namespace, $container->get(MVCFactoryInterface::class))
 ```
-Here the code is also getting the MVCFactory instance out of the child DIC; the ComponentDispatcherFactory has in turn a dependency on the MVCFactory. Why is this? As described in the [Dispatcher document](../extension-and-dispatcher/dispatcher-component.md) whenever the Dispatcher's `dispatch` function is called it analyses the *task* parameter of the URL, to decide which Controller class to instantiate. So it stores the MVCFactory object passed in its constructor so that it can later use it to create the Controller class:
+Here the code is also getting the MVCFactory instance out of the child DIC; the ComponentDispatcherFactory has in turn a dependency on the MVCFactory. Why is this? As described in the [Dispatcher documentation](../extension-and-dispatcher/dispatcher-component.md) whenever the Dispatcher's `dispatch` function is called it analyses the *task* parameter of the URL, to decide which Controller class to instantiate. So it stores the MVCFactory object passed in its constructor so that it can later use it to create the Controller class:
 ```php
 $controller = $this->mvcFactory->createController(...);
 $controller->execute($task);
 ```
-So the ComponentDispatcherFactory gets MVCFactory out of the DIC, stores a reference to it, and then passes it down to the Dispatcher class it instantiates it. Its code is in libraries/src/Dispatcher/ComponentDispatcherFactory.php.
+So the ComponentDispatcherFactory gets MVCFactory out of the DIC, stores a reference to it, and then passes it down to the Dispatcher class when instantiates it. Its code is in libraries/src/Dispatcher/ComponentDispatcherFactory.php.
 
 ## Resolving the MVCFactory Dependency
 This follows a pattern similar to that of the ComponentDispatcherFactory dependency.
@@ -104,13 +105,14 @@ The second step involves instantiating the Extension class and resolving its dep
 $component = new MVCComponent($container->get(ComponentDispatcherFactoryInterface::class));
 $component->setMVCFactory($container->get(MVCFactoryInterface::class));
 ```
-The code `$container->get(MVCFactoryInterface::class` obtains the MVCFactory instance from the child DIC, and then a reference to it is stored locally through it being passed to `setMVCFactory`. This function is available to `MVCComponent` via the trait Joomla\CMS\MVC\Factory\MVCFactoryServiceTrait, which contains the lines:
+In the first line the Extension class (MVCComponent) gets instantiated, with the ComponentDispatchFactory instance being passed into the constructor (as we saw above).
+
+In the second line the code `$container->get(MVCFactoryInterface::class` obtains the MVCFactory instance from the child DIC, and then a reference to it is stored locally through it being passed to `setMVCFactory`. This function is available to `MVCComponent` via the trait Joomla\CMS\MVC\Factory\MVCFactoryServiceTrait, which is used in MVCComponent, and which contains the lines:
 ```php
 public function setMVCFactory(MVCFactoryInterface $mvcFactory)
 {
     $this->mvcFactory = $mvcFactory;
 }
-
 ```
 ## Namespaces parameters
 You will have noticed that the namespace '\Mycompany\Component\Example' gets passed as a parameter into several classes constructors. (By the way, this is exactly the same PHP string as its equivalent with double backslashes instead of single backslashes).