|
| 1 | +--- |
| 2 | +title: Dependency Injection |
| 3 | +tags: |
| 4 | + - DI |
| 5 | + - Container |
| 6 | + - PSR-11 |
| 7 | + - PSR |
| 8 | +description: The use of PSR-11 compatible Dependency Injection in Moodle |
| 9 | +--- |
| 10 | + |
| 11 | +import { |
| 12 | + Since, |
| 13 | + ValidExample, |
| 14 | + InvalidExample, |
| 15 | + Tabs, |
| 16 | + TabItem, |
| 17 | +} from '@site/src/components'; |
| 18 | + |
| 19 | +<Since version="4.4" issueNumber="MDL-80072" /> |
| 20 | + |
| 21 | +Moodle supports the use of [PSR-11](https://www.php-fig.org/psr/psr-11/) compatible Dependency Injection, accessed using the `\core\di` class, which internally makes use of [PHP-DI](https://php-di.org). All usage should be through the `\core\di` class. |
| 22 | + |
| 23 | +Most class instances can be fetched using their class name without any manual configuration. Support for configuration of constructor arguments is also possible, but is generally discouraged. |
| 24 | + |
| 25 | +Dependencies are stored using a string id attribute, which is typically the class or interface name of the dependency. Use of other arbitrary id values is strongly discouraged. |
| 26 | + |
| 27 | +## Fetching dependencies |
| 28 | + |
| 29 | +Moodle provides a wrapper around the PSR-11 Container implementation which should be used to fetch dependencies: |
| 30 | + |
| 31 | +```php title="Fetching an instance of the \core\http_client class" |
| 32 | +$client = \core\di::get(\core\http_client::class); |
| 33 | +``` |
| 34 | + |
| 35 | +## Configuring dependencies |
| 36 | + |
| 37 | +In some rare cases you may need to supply additional configuration for a dependency to work properly. This is usually in the case of legacy code, and can be achieved with the `\core\hook\di_configuration` hook. |
| 38 | + |
| 39 | +<Tabs> |
| 40 | + |
| 41 | +<TabItem value="config" label="Hook configuration"> |
| 42 | + |
| 43 | +The callback must be linked to the hook by specifying a callback in the plugin's `hooks.php` file: |
| 44 | + |
| 45 | +```php title="mod/example/db/hooks.php" |
| 46 | +<?php |
| 47 | +$callbacks = [ |
| 48 | + [ |
| 49 | + 'hook' => \core\hook\di_configuration::class, |
| 50 | + 'callback' => \mod_example\hook_listener::class . '::inject_dependenices', |
| 51 | + ], |
| 52 | +]; |
| 53 | +``` |
| 54 | + |
| 55 | +</TabItem> |
| 56 | + |
| 57 | +<TabItem value="hook" label="Hook listener"> |
| 58 | + |
| 59 | +The hook listener consists of a static method on a class. |
| 60 | + |
| 61 | +```php title="mod/example/classes/hook_listener.php" |
| 62 | +<?php |
| 63 | + |
| 64 | +namespace mod_example; |
| 65 | + |
| 66 | +use core\hook\di_configuration; |
| 67 | + |
| 68 | +class hook_listener { |
| 69 | + public static function inject_dependencies(di_configuration $hook): void { |
| 70 | + $hook->add_definition( |
| 71 | + id: complex_client::class, |
| 72 | + definition: function ( |
| 73 | + \moodle_database $db, |
| 74 | + ): complex_client { |
| 75 | + global $CFG; |
| 76 | + |
| 77 | + return new complex_client( |
| 78 | + db: $db, |
| 79 | + name: $CFG->some_value, |
| 80 | + ); |
| 81 | + } |
| 82 | + ) |
| 83 | + } |
| 84 | +} |
| 85 | +``` |
| 86 | + |
| 87 | +</TabItem> |
| 88 | + |
| 89 | +</Tabs> |
| 90 | + |
| 91 | +## Mocking dependencies in Unit Tests |
| 92 | + |
| 93 | +One of the most convenient features of Dependency Injection is the ability to provide a mocked version of the dependency during unit testing. |
| 94 | + |
| 95 | +Moodle resets the Dependency Injection Container between each unit test, which means that little-to-no cleanup is required. |
| 96 | + |
| 97 | +```php title="Injecting a Mocked dependency" |
| 98 | +<?php |
| 99 | +namespace mod_example; |
| 100 | + |
| 101 | +use GuzzleHttp\Handler\MockHandler; |
| 102 | +use GuzzleHttp\HandlerStack; |
| 103 | +use GuzzleHttp\Middleware; |
| 104 | +use GuzzleHttp\Psr7\Response; |
| 105 | + |
| 106 | +class example_test extends \advanced_testcase { |
| 107 | + public function test_the_thing(): void { |
| 108 | + // Mock our responses to the http_client. |
| 109 | + $handlerstack = HandlerStack::create(new MockHandler([ |
| 110 | + new Response(200, [], json_encode(['name' => 'Colin'])), |
| 111 | + ])); |
| 112 | + |
| 113 | + // Inject the mock. |
| 114 | + \core\di::set( |
| 115 | + \core\http_client::class, |
| 116 | + new http_client(['handler' => $handlerstack]), |
| 117 | + ); |
| 118 | + |
| 119 | + // Call a method on the example class. |
| 120 | + // This method uses \core\di to fetch the client and use it to fetch data. |
| 121 | + $example \core\di::get(example::class); |
| 122 | + $result = $example->do_the_thing(); |
| 123 | + |
| 124 | + // The result will be based on the mock response. |
| 125 | + $this->assertEquals('Colin', $result->get_name()); |
| 126 | + } |
| 127 | +} |
| 128 | +``` |
| 129 | + |
| 130 | +## Injecting the container into classes |
| 131 | + |
| 132 | +In more advanced cases you may wish to make use of dependency injection within an object. One way that you can do so is to inject the dependency into the class via its constructor, for example: |
| 133 | + |
| 134 | +```php title="Injecting the ContainerInterface" |
| 135 | +<?php |
| 136 | + |
| 137 | +namespace mod_example; |
| 138 | + |
| 139 | +use Psr\Container\ContainerInterface; |
| 140 | + |
| 141 | +class example { |
| 142 | + /** |
| 143 | + * @param ContainerInterface $container |
| 144 | + */ |
| 145 | + public function __construct( |
| 146 | + protected ContainerInterface $container, |
| 147 | + ) { |
| 148 | + } |
| 149 | + |
| 150 | + public function do_something(string $value): string { |
| 151 | + return $this->get(\core\formatting::class)->format_string($value); |
| 152 | + } |
| 153 | +} |
| 154 | +``` |
| 155 | + |
| 156 | +The `example` class can also be fetched using DI: |
| 157 | + |
| 158 | +```php title="Consuming the example class" |
| 159 | +use mod_example\example; |
| 160 | + |
| 161 | +// ... |
| 162 | +$example = \core\di::get(example::class); |
| 163 | +$value = $example->do_something("with this string"); |
| 164 | +``` |
| 165 | + |
| 166 | +## Advanced usage |
| 167 | + |
| 168 | +All usage of the Container _should_ be via `\core\di`, which is a wrapper around the currently-active Container implementation. In normal circumstances it is not necessary to access the underlying Container implementation directly and such usage is generally discouraged. |
| 169 | + |
| 170 | +:::danger |
| 171 | + |
| 172 | +Moodle currently makes use of PHP-DI as its Container implementation. |
| 173 | + |
| 174 | +Please note that the underlying Dependency Injection system _may_ change at any time. |
| 175 | + |
| 176 | +Care should be taken to only make use of methods which are defined in the [PSR-11 Container Interface](https://www.php-fig.org/psr/psr-11/). |
| 177 | + |
| 178 | +::: |
| 179 | + |
| 180 | +### Resetting the Container |
| 181 | + |
| 182 | +The Container is normally instantiated during the bootstrap phase of a script. In normal use it is not reset and there should be no need to reset it, however it is _possible_ to reset it if required. This usage is intended to be used for situations such as Unit Testing. |
| 183 | + |
| 184 | +:::danger |
| 185 | + |
| 186 | +Resetting an actively-used container can lead to unintended consequences. |
| 187 | + |
| 188 | +::: |
| 189 | + |
| 190 | +```php title="Resetting the Container" |
| 191 | +\core\di::reset_container(): |
| 192 | +``` |
| 193 | + |
| 194 | +### Accessing the Container Interface |
| 195 | + |
| 196 | +In some rare circumstances you may need to perform certain advanced tasks such as accessing the `ContainerInterface` implementation directly. |
| 197 | + |
| 198 | +The `\core\di` wrapper provides a method to fetch the `\Psr\Container\ContainerInterface` implementation. |
| 199 | + |
| 200 | +```php title="Fetch the ContainerInterface" |
| 201 | +$container = \core\di::get_container(); |
| 202 | +``` |
0 commit comments