MDL-81144 core: Convert standard_after_main_region_html to hook

lib/classes/hook/output/after_standard_main_region_html_generation.php

@@ -0,0 +1,81 @@
+<?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\output;
+
+/**
+ * Hook to allow subscribers to add HTML content after the main region content has been generated.
+ *
+ * @package    core
+ * @copyright  2024 Andrew Lyons <andrew@nicols.co.uk>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @property-read \renderer_base $renderer The page renderer object
+ */
+#[\core\attribute\tags('output')]
+#[\core\attribute\label('Allows plugins to add any elements to the footer before JS is finalized')]
+#[\core\attribute\hook\replaces_callbacks('standard_after_main_region_html')]
+final class after_standard_main_region_html_generation {
+    /**
+     * Hook to allow subscribers to add HTML content after the main region content has been generated.
+     *
+     * @param renderer_base $renderer
+     * @param string $output Initial output
+     */
+    public function __construct(
+        /** @var \renderer_base The page renderer object */
+        public readonly \renderer_base $renderer,
+        /** @var string The collected output */
+        private string $output = '',
+    ) {
+    }
+
+    /**
+     * Plugins implementing callback can add any HTML to the top of the body.
+     *
+     * Must be a string containing valid html head content.
+     *
+     * @param null|string $output
+     */
+    public function add_html(?string $output): void {
+        if ($output) {
+            $this->output .= $output;
+        }
+    }
+
+    /**
+     * Returns all HTML added by the plugins
+     *
+     * @return string
+     */
+    public function get_output(): string {
+        return $this->output;
+    }
+
+    /**
+     * Process legacy callbacks.
+     */
+    public function process_legacy_callbacks(): void {
+        $pluginswithfunction = get_plugins_with_function(function: 'standard_after_main_region_html', migratedtohook: true);
+        foreach ($pluginswithfunction as $plugins) {
+            foreach ($plugins as $function) {
+                $extrafooter = $function();
+                if (is_string($extrafooter)) {
+                    $this->add_html($extrafooter);
+                }
+            }
+        }
+    }
+}

lib/db/hooks.php

@@ -97,4 +97,9 @@ $callbacks = [
         'hook' => \core\hook\output\before_standard_footer_html_generation::class,
         'callback' => \core_userfeedback::class . '::before_standard_footer_html_generation',
     ],
+    [
+        'hook' => \core\hook\output\after_standard_main_region_html_generation::class,
+        'callback' => \core_message\hook_callbacks::class . '::add_messaging_widget',
+        'priority' => 0,
+    ],
 ];

lib/outputrenderers.php

@@ -37,6 +37,8 @@
 
 use core\di;
 use core\hook\manager as hook_manager;
+use core\hook\output\after_standard_main_region_html_generation;
+use core\hook\output\before_html_attributes;
 use core\hook\output\before_standard_footer_html_generation;
 use core\hook\output\before_standard_top_of_body_html_generation;
 use core\output\named_templatable;
@@ -1105,29 +1107,23 @@ class core_renderer extends renderer_base {
      */
     public function standard_after_main_region_html() {
         global $CFG;
-        $output = '';
+
+        // Ensure that the callback exists prior to cache purge.
+        // This is a critical page path.
+        // TODO MDL-81134 Remove after LTS+1.
+        require_once(__DIR__ . '/classes/hook/output/after_standard_main_region_html_generation.php');
+
+        $hook = new after_standard_main_region_html_generation($this);
+
         if ($this->page->pagelayout !== 'embedded' && !empty($CFG->additionalhtmlbottomofbody)) {
-            $output .= "\n".$CFG->additionalhtmlbottomofbody;
+            $hook->add_html("\n");
+            $hook->add_html($CFG->additionalhtmlbottomofbody);
         }
 
-        // Give subsystems an opportunity to inject extra html content. The callback
-        // must always return a string containing valid html.
-        foreach (\core_component::get_core_subsystems() as $name => $path) {
-            if ($path) {
-                $output .= component_callback($name, 'standard_after_main_region_html', [], '');
-            }
-        }
+        di::get(hook_manager::class)->dispatch($hook);
+        $hook->process_legacy_callbacks();
 
-        // Give plugins an opportunity to inject extra html content. The callback
-        // must always return a string containing valid html.
-        $pluginswithfunction = get_plugins_with_function('standard_after_main_region_html', 'lib.php');
-        foreach ($pluginswithfunction as $plugins) {
-            foreach ($plugins as $function) {
-                $output .= $function();
-            }
-        }
-
-        return $output;
+        return $hook->get_output();
     }
 
     /**

lib/tests/core_renderer_test.php

@@ -95,6 +95,39 @@ final class core_renderer_test extends \advanced_testcase {
         $this->assertStringContainsString('A heading can be added', $html);
     }
 
+    /**
+     * @covers \core\hook\after_standard_main_region_html_generation
+     */
+    public function test_after_standard_main_region_html_generation(): void {
+        $page = new moodle_page();
+        $renderer = new core_renderer($page, RENDERER_TARGET_GENERAL);
+
+        $html = $renderer->standard_after_main_region_html();
+        $this->assertIsString($html);
+        $this->assertStringNotContainsString('A heading can be added', $html);
+    }
+
+    /**
+     * @covers \core\hook\after_standard_main_region_html_generation
+     */
+    public function test_after_standard_main_region_html_generation_hooked(): void {
+        require_once(__DIR__ . '/fixtures/core_renderer/after_standard_main_region_html_generation_callbacks.php');
+
+        \core\di::set(
+            \core\hook\manager::class,
+            \core\hook\manager::phpunit_get_instance([
+                'test_plugin1' => __DIR__ . '/fixtures/core_renderer/after_standard_main_region_html_generation_hooks.php',
+            ]),
+        );
+
+        $page = new moodle_page();
+        $renderer = new core_renderer($page, RENDERER_TARGET_GENERAL);
+
+        $html = $renderer->standard_after_main_region_html();
+        $this->assertIsString($html);
+        $this->assertStringContainsString('A heading can be added', $html);
+    }
+
     /**
      * @covers \core\hook\before_html_attributes
      */

lib/tests/fixtures/core_renderer/after_standard_main_region_html_generation_callbacks.php

@@ -0,0 +1,39 @@
+<?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 test_fixtures\core_renderer;
+
+/**
+ * Hook fixture for \core_renderer::after_standard_main_region_html_generation.
+ *
+ * @package   core
+ * @category  test
+ * @copyright 2024 Andrew Lyons <andrew@nicols.co.uk>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+final class after_standard_main_region_html_generation_callbacks {
+    /**
+     * Fixture for adding a heading after the standard main region HTML generation.
+     *
+     * @param \core\hook\output\after_standard_main_region_html_generation $hook
+     */
+    public static function after_standard_main_region_html_generation(
+        \core\hook\output\after_standard_main_region_html_generation $hook,
+    ): void {
+        $hook->add_html("<h1>A heading can be added</h1>");
+    }
+}

lib/tests/fixtures/core_renderer/after_standard_main_region_html_generation_hooks.php

@@ -0,0 +1,34 @@
+<?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/>.
+
+/**
+ * Hook fixture for \core_renderer::after_standard_main_region_html_generation.
+ *
+ * @package   core
+ * @category  test
+ * @copyright 2024 Andrew Lyons <andrew@nicols.co.uk>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+defined('MOODLE_INTERNAL') || die();
+
+$callbacks = [
+    [
+        'hook' => \core\hook\output\after_standard_main_region_html_generation::class,
+        'callback' => \test_fixtures\core_renderer\after_standard_main_region_html_generation_callbacks::class
+            . '::after_standard_main_region_html_generation',
+    ],
+];

lib/upgrade.txt

@@ -40,6 +40,7 @@ information provided here is intended especially for developers.
   - before_standard_html_head() -> core\hook\output\before_standard_head_html_generation
   - bulk_user_actions() -> core_user\hook\extend_bulk_user_actions
   - before_standard_top_of_body_html() -> core\hook\output\before_standard_top_of_body_html_generation
+  - standard_after_main_region_html() -> core\hook\output\after_standard_main_region_html_generation
   - standard_footer_html() -> core\hook\output\before_standard_footer_html_generation
   - add_htmlattributes() -> core\hook\output\before_html_attributes
 * Deprecated PARAM_ types with the exception of PARAM_CLEAN now emit a deprecation exception. These were all deprecated in Moodle 2.0.

message/classes/hook_callbacks.php

@@ -0,0 +1,39 @@
+<?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_message;
+
+/**
+ * Class hook_callbacks
+ *
+ * @package    core_message
+ * @copyright  2024 Andrew Lyons <andrew@nicols.co.uk>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class hook_callbacks {
+    /**
+     * Add messaging widgets after the main region content.
+     *
+     * @param \core\hook\output\after_standard_main_region_html_generation $hook
+     */
+    public static function add_messaging_widget(
+        \core\hook\output\after_standard_main_region_html_generation $hook,
+    ): void {
+        $hook->add_html(\core_message\helper::render_messaging_widget(
+            isdrawer: true,
+        ));
+    }
+}

message/lib.php

@@ -798,12 +798,3 @@ function core_message_user_preferences() {
         });
     return $preferences;
 }
-
-/**
- * Render the message drawer to be included in the top of the body of each page.
- *
- * @return string HTML
- */
-function core_message_standard_after_main_region_html() {
-    return \core_message\helper::render_messaging_widget(true, null, null);
-}