MDL-80072 core: Add \core\di wrapper to php-di

The \core\di class is a Moodle wrapper to php-di which is intended to
allow Moodle to switch to an alternate DI solution in the future if
required. All interaction with the container uses the PSR-11 Container
interfaces, which allows for normalisation of configuration, setting,
and retrieving of DI container-identified classes.

lib/behat/classes/util.php

@@ -429,6 +429,9 @@ public static function reset_all_data() {
         core_courseformat\base::reset_course_cache(0);
         get_fast_modinfo(0, 0, true);
 
+        // Reset the DI container.
+        \core\di::reset_container();
+
         // Inform data generator.
         self::get_data_generator()->reset();
 

lib/classes/di.php

@@ -0,0 +1,128 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace core;
+
+use Psr\Container\ContainerInterface;
+
+/**
+ * DI Container Helper.
+ *
+ * @package    core
+ * @copyright  2023 Andrew Lyons <andrew@nicols.co.uk>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class di {
+    /** @var ContainerInterface The stored container */
+    protected static ?ContainerInterface $container;
+
+    /**
+     * Get the DI Container.
+     *
+     * @return ContainerInterface
+     */
+    public static function get_container(): ContainerInterface {
+        if (!isset(self::$container)) {
+            self::$container = self::create_container();
+        }
+        return self::$container;
+    }
+
+    /**
+     * Reset the DI Container.
+     *
+     * This is primarily intended for Unit Testing, and for use in Scheduled tasks.
+     */
+    public static function reset_container(): void {
+        self::$container = null;
+    }
+
+    /**
+     * Finds an entry of the container by its identifier and returns it.
+     *
+     * This is a shortcut helper for \core\di::get_container()->get($id).
+     *
+     * @param string $id Identifier of the entry to look for.
+     * @return mixed Entry.
+     */
+    public static function get(string $id): mixed {
+        return self::get_container()->get($id);
+    }
+
+    /**
+     * Set an entry in the container by its identifier.
+     *
+     * @param string $id Identifier of the entry to set
+     * @param mixed $value The value to set
+     */
+    public static function set(string $id, mixed $value): void {
+        // Please note that the `set` method is not a part of the PSR-11 standard.
+        // We currently make use of PHP-DI which does have this method, but its use is not guaranteed.
+        // If Moodle switches to alternative DI resolution, this method _must_ be updated to work with it.
+
+        /** @var \DI\Container */
+        $container = self::get_container();
+        $container->set($id, $value);
+    }
+
+    /**
+     * Create a new Container Instance.
+     *
+     * @return ContainerInterface
+     */
+    protected static function create_container(): ContainerInterface {
+        global $CFG, $DB;
+
+        // PHP Does not support function autoloading. We must manually include the file.
+        require_once("{$CFG->libdir}/php-di/php-di/src/functions.php");
+
+        // Configure the Container builder.
+        $builder = new \DI\ContainerBuilder();
+
+        // At the moment we are using autowiring, but not automatic attribute injection.
+        // Automatic attribute injection is a php-di specific feature.
+        $builder->useAutowiring(true);
+
+        if (!$CFG->debugdeveloper) {
+            // Enable compilation of the container and write proxies to disk in production.
+            // See https://php-di.org/doc/performances.html for information.
+            $cachedir = make_localcache_directory('di');
+            $builder->enableCompilation($cachedir);
+            $builder->writeProxiesToFile(true, $cachedir);
+        }
+
+        // Get the hook manager.
+        $hookmanager = \core\hook\manager::get_instance();
+
+        // Configure some basic definitions.
+        $builder->addDefinitions([
+            // The hook manager should be in the container.
+            \core\hook\manager::class => $hookmanager,
+
+            // The database.
+            \moodle_database::class => $DB,
+
+            // The string manager.
+            \core_string_manager::class => fn() => get_string_manager(),
+        ]);
+
+        // Add any additional definitions using hooks.
+        $hookmanager->dispatch(new \core\hook\di_configuration($builder));
+
+        // Build the container and return.
+        return $builder->build();
+    }
+}

lib/classes/hook/di_configuration.php

@@ -0,0 +1,89 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace core\hook;
+
+use DI\ContainerBuilder;
+
+/**
+ * Allow for init-time configuration of the Dependency Injection container.
+ *
+ * @package    core
+ * @copyright  2023 Andrew Lyons <andrew@nicols.co.uk>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class di_configuration implements described_hook {
+    /**
+     * Create the Dependency Injection configuration hook instance.
+     *
+     * @param ContainerBuilder $builder
+     */
+    public function __construct(
+        protected ContainerBuilder $builder,
+    ) {
+    }
+
+    /**
+     * Add a definition to the Dependency Injection container.
+     *
+     * A definition is a callable that returns an instance of the service.
+     *
+     * The callable can take arguments which are resolved using the DI container, for example a definition for the
+     * following example service requires \moodle_database, and \core\formatting which will be resolved using the DI
+     * container.
+     *
+     * <code>
+     * $hook->add_definition(
+     *     id: \mod\example\service::class,
+     *     definition: function (
+     *         \moodle_database $db,
+     *         \core\formatting $formatter,
+     *     ): \mod\example\service {
+     *         return new \mod\example\service(
+     *             $database,
+     *             $formatter,
+     *             $some,
+     *             $other,
+     *             $args,
+     *         )'
+     *     },
+     *  );
+     * </code>
+     *
+     * @param string $id The identifier of the container entry
+     * @param callable $definition The definition of the container entry
+     * @return self
+     * @example
+     */
+    public function add_definition(
+        string $id,
+        callable $definition,
+    ): self {
+        $this->builder->addDefinitions([
+            $id => $definition,
+        ]);
+
+        return $this;
+    }
+
+    public static function get_hook_description(): string {
+        return 'The DI container, which allows plugins to register any service requiring configuration or initialisation.';
+    }
+
+    public static function get_hook_tags(): array {
+        return [];
+    }
+}

lib/phpunit/classes/util.php

@@ -300,6 +300,9 @@ public static function reset_all_data($detectchanges = false) {
         // Reset user agent.
         core_useragent::instance(true, null);
 
+        // Reset the DI container.
+        \core\di::reset_container();
+
         // verify db writes just in case something goes wrong in reset
         if (self::$lastdbwrites != $DB->perf_get_writes()) {
             error_log('Unexpected DB writes in phpunit_util::reset_all_data()');