[docs] Add \core\formatting and DI docs for MDL-80072

docs/apis/core/di/index.md

@@ -0,0 +1,202 @@
+---
+title: Dependency Injection
+tags:
+  - DI
+  - Container
+  - PSR-11
+  - PSR
+description: The use of PSR-11 compatible Dependency Injection in Moodle
+---
+
+import {
+    Since,
+    ValidExample,
+    InvalidExample,
+    Tabs,
+    TabItem,
+} from '@site/src/components';
+
+<Since version="4.4" issueNumber="MDL-80072" />
+
+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.
+
+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.
+
+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.
+
+## Fetching dependencies
+
+Moodle provides a wrapper around the PSR-11 Container implementation which should be used to fetch dependencies:
+
+```php title="Fetching an instance of the \core\http_client class"
+$client = \core\di::get(\core\http_client::class);
+```
+
+## Configuring dependencies
+
+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.
+
+<Tabs>
+
+<TabItem value="config" label="Hook configuration">
+
+The callback must be linked to the hook by specifying a callback in the plugin's `hooks.php` file:
+
+```php title="mod/example/db/hooks.php"
+<?php
+$callbacks = [
+    [
+        'hook' => \core\hook\di_configuration::class,
+        'callback' => \mod_example\hook_listener::class . '::inject_dependenices',
+    ],
+];
+```
+
+</TabItem>
+
+<TabItem value="hook" label="Hook listener">
+
+The hook listener consists of a static method on a class.
+
+```php title="mod/example/classes/hook_listener.php"
+<?php
+
+namespace mod_example;
+
+use core\hook\di_configuration;
+
+class hook_listener {
+    public static function inject_dependencies(di_configuration $hook): void {
+        $hook->add_definition(
+            id: complex_client::class,
+            definition: function (
+                \moodle_database $db,
+            ): complex_client {
+                global $CFG;
+
+                return new complex_client(
+                    db: $db,
+                    name: $CFG->some_value,
+                );
+            }
+        )
+    }
+}
+```
+
+</TabItem>
+
+</Tabs>
+
+## Mocking dependencies in Unit Tests
+
+One of the most convenient features of Dependency Injection is the ability to provide a mocked version of the dependency during unit testing.
+
+Moodle resets the Dependency Injection Container between each unit test, which means that little-to-no cleanup is required.
+
+```php title="Injecting a Mocked dependency"
+<?php
+namespace mod_example;
+
+use GuzzleHttp\Handler\MockHandler;
+use GuzzleHttp\HandlerStack;
+use GuzzleHttp\Middleware;
+use GuzzleHttp\Psr7\Response;
+
+class example_test extends \advanced_testcase {
+    public function test_the_thing(): void {
+        // Mock our responses to the http_client.
+        $handlerstack = HandlerStack::create(new MockHandler([
+            new Response(200, [], json_encode(['name' => 'Colin'])),
+        ]));
+
+        // Inject the mock.
+        \core\di::set(
+            \core\http_client::class,
+            new http_client(['handler' => $handlerstack]),
+        );
+
+        // Call a method on the example class.
+        // This method uses \core\di to fetch the client and use it to fetch data.
+        $example \core\di::get(example::class);
+        $result = $example->do_the_thing();
+
+        // The result will be based on the mock response.
+        $this->assertEquals('Colin', $result->get_name());
+    }
+}
+```
+
+## Injecting the container into classes
+
+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:
+
+```php title="Injecting the ContainerInterface"
+<?php
+
+namespace mod_example;
+
+use Psr\Container\ContainerInterface;
+
+class example {
+    /**
+     * @param ContainerInterface $container
+     */
+    public function __construct(
+        protected ContainerInterface $container,
+    ) {
+    }
+
+    public function do_something(string $value): string {
+        return $this->get(\core\formatting::class)->format_string($value);
+    }
+}
+```
+
+The `example` class can also be fetched using DI:
+
+```php title="Consuming the example class"
+use mod_example\example;
+
+// ...
+$example = \core\di::get(example::class);
+$value = $example->do_something("with this string");
+```
+
+## Advanced usage
+
+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.
+
+:::danger
+
+Moodle currently makes use of PHP-DI as its Container implementation.
+
+Please note that the underlying Dependency Injection system _may_ change at any time.
+
+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/).
+
+:::
+
+### Resetting the Container
+
+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.
+
+:::danger
+
+Resetting an actively-used container can lead to unintended consequences.
+
+:::
+
+```php title="Resetting the Container"
+\core\di::reset_container():
+```
+
+### Accessing the Container Interface
+
+In some rare circumstances you may need to perform certain advanced tasks such as accessing the `ContainerInterface` implementation directly.
+
+The `\core\di` wrapper provides a method to fetch the `\Psr\Container\ContainerInterface` implementation.
+
+```php title="Fetch the ContainerInterface"
+$container = \core\di::get_container();
+```

docs/apis/subsystems/output/index.md

@@ -221,15 +221,11 @@ The key parameter for this function is:
 
 #### format_text()
 
-```php
-function format_text($text, $format = FORMAT_MOODLE, $options = null, $courseid_do_not_use = null)
-```
-
 This function should be used to:
 
 - print **any html/plain/markdown/moodle text**, needing any of the features below. It is mainly used for long strings like posts, answers, glossary items, etc.
 - filter content through Moodle or 3rd party language filters for multi-language support. Not to be confused with [get_string](https://docs.moodle.org/dev/String_API#get_string.28.29) which is used to access localized strings in Moodle and its language packs. Together, these functions enable Moodle multi-language support .
-Note that this function is really **heavy** because it supports **cleaning** of dangerous contents, delegates processing to enabled **content filter**s, supports different **formats** of text (HTML, PLAIN, MARKDOWN, MOODLE) and performs a lot of **automatic conversions** like adding smilies, build links. Also, it includes a strong **cache mechanism** (DB based) that will alleviate the server from a lot of work processing the same texts time and again.
+Note that this function is really **heavy** because it supports **cleaning** of dangerous contents, delegates processing to enabled **content filters**, supports different **formats** of text (HTML, PLAIN, MARKDOWN, MOODLE) and performs a lot of **automatic conversions** like adding smilies, build links. Also, it includes a strong **cache mechanism** (DB based) that will alleviate the server from a lot of work processing the same texts time and again.
 
 Some interesting parameters for this function are:
 
@@ -241,18 +237,12 @@ Some interesting parameters for this function are:
   - `options->context`: If text is filtered (and this happens by default), it is very important to specify context (id or object) for applying filters. If context is not specified it will be taken from `$PAGE->context` and may potentially result in displaying the same text differently on different pages. For example all module-related information should have module context even when it appears in course-level reports, all course-related information such as name and description should have course context even when they are displayed on front page or system pages.
   - `options->param`: To decide if you want every paragraph automatically enclosed between html paragraph tags (`<p>...</p>`) (defaults to true). This option only applies to `FORMAT_MOODLE`.
   - `options->newlines`: To decide if line feeds in text should be converted to html newlines (`<br />`) (defaults to true). This option only applies to `FORMAT_MOODLE`.
-  - `options->nocache`: If true the string will not be cached and will be formatted every call. Default false.
   - `options->overflowdiv`*: If set to true the formatted text will be encased in a div with the class no-overflow before being returned. Default false.
   - `options->allowid` : If true then id attributes will not be removed, even when using HTML Purifier. Default false.
   - `options->blanktarget` : If true all `<a>` tags will have `target="_blank"` added unless target is explicitly specified. Default false.
-- **courseid_do_not_use**: This parameter was earlier used to help applying filters but now is replaced with more precise `$options->context`, see above
 
 #### format_string()
 
-```php
-function format_string ($string, $striplinks = true, $options = null)
-```
-
 This function should be used to:
 
 - print **short non-html strings that need filter processing** (activity titles, post subjects, glossary concepts...). If the string contains HTML, it will be filtered out. If you want the HTML, use `format_text()` instead.
@@ -269,14 +259,12 @@ Some interesting parameters for this function are:
   - `options->escape`: To decide if you want to escape HTML entities. True by default.
   - `options->filter`: To decide if you want to allow filters to process the text (defaults to true). This is ignored by `FORMAT_PLAIN` for which filters are never applied.
 
-:::note
-In earlier versions of Moodle, the third argument was integer `$courseid`. It is still supported for legacy - if the third argument is an integer instead of an array or object, it is considered to be course id and is this course's context is passed to the filters being applied.
-:::
-
 ### Simple elements rendering
 
 :::important
+
 Those methods are designed to replace the old ```html_writer::tag(...)``` methods. Even if many of them are just wrappers around the old methods, they are more semantic and could be overridden by component renderers.
+
 :::
 
 While to render complex elements, you should use [templates](../../../guides/templates/index.md), some simple elements can be rendered using the following functions: