MDL-81144 core: Convert before_standard_top_of_body_html to hook

admin/tool/policy/classes/hook_callbacks.php

@@ -0,0 +1,62 @@
+<?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 tool_policy;
+
+use core\hook\output\before_standard_top_of_body_html_generation;
+
+/**
+ * Allows the plugin to add any elements to the footer.
+ *
+ * @package    tool_policy
+ * @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 the guest consent form to the top of the body.
+     *
+     * @param before_standard_top_of_body_html_generation $hook
+     */
+    public static function before_standard_top_of_body_html_generation(before_standard_top_of_body_html_generation $hook): void {
+        global $CFG, $PAGE, $USER;
+
+        if (empty($CFG->sitepolicyhandler)) {
+            return;
+        }
+
+        if ($CFG->sitepolicyhandler !== 'tool_policy') {
+            return;
+        }
+
+        if (!empty($USER->policyagreed)) {
+            return;
+        }
+
+        if (!isguestuser() && isloggedin()) {
+            return;
+        }
+
+        $output = $PAGE->get_renderer('tool_policy');
+        try {
+            $page = new \tool_policy\output\guestconsent();
+            $hook->add_html($output->render($page));
+        } catch (\dml_read_exception $e) {
+            // During upgrades, the new plugin code with new SQL could be in place but the DB not upgraded yet.
+            return;
+        }
+    }
+}

admin/tool/policy/db/hooks.php

@@ -0,0 +1,33 @@
+<?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 callbacks for Policies
+ *
+ * @package    tool_policy
+ * @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\before_standard_top_of_body_html_generation::class,
+        'callback' => \tool_policy\hook_callbacks::class . '::before_standard_top_of_body_html_generation',
+        'priority' => 0,
+    ],
+];

admin/tool/policy/lib.php

@@ -71,32 +71,6 @@ function tool_policy_myprofile_navigation(tree $tree, $user, $iscurrentuser, $co
     return true;
 }
 
-/**
- * Load policy message for guests.
- *
- * @return string The HTML code to insert before the head.
- */
-function tool_policy_before_standard_top_of_body_html() {
-    global $CFG, $PAGE, $USER;
-
-    $message = null;
-    if (!empty($CFG->sitepolicyhandler)
-            && $CFG->sitepolicyhandler == 'tool_policy'
-            && empty($USER->policyagreed)
-            && (isguestuser() || !isloggedin())) {
-        $output = $PAGE->get_renderer('tool_policy');
-        try {
-            $page = new \tool_policy\output\guestconsent();
-            $message = $output->render($page);
-        } catch (dml_read_exception $e) {
-            // During upgrades, the new plugin code with new SQL could be in place but the DB not upgraded yet.
-            $message = null;
-        }
-    }
-
-    return $message;
-}
-
 /**
  * Callback to add footer elements.
  *
@@ -235,4 +209,4 @@ function tool_policy_output_fragment_accept_on_behalf($args) {
     }
 
     return $mform->render();
-}
+}

lib/classes/hook/output/before_standard_top_of_body_html_generation.php

@@ -0,0 +1,101 @@
+<?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 to the top of the page body.
+ *
+ * @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 page &lt;head&gt; html tag.')]
+#[\core\attribute\hook\replaces_callbacks('before_standard_html_head')]
+final class before_standard_top_of_body_html_generation {
+    /**
+     * Hook to allow subscribers to add HTML content to the top of the page body.
+     *
+     * @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.
+     *
+     * Legacy callback 'before_standard_top_of_body_html' is deprecated since Moodle 4.4
+     */
+    public function process_legacy_callbacks(): void {
+        // 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) {
+                $this->add_html(
+                    component_callback(
+                        component: $name,
+                        function: 'before_standard_top_of_body_html',
+                        default: '',
+                        migratedtohook: true,
+                    ),
+                );
+            }
+        }
+
+        // Give plugins an opportunity to inject extra html content. The callback
+        // must always return a string containing valid html.
+        $pluginswithfunction = get_plugins_with_function(
+            function: 'before_standard_top_of_body_html',
+            migratedtohook: true,
+        );
+        foreach ($pluginswithfunction as $plugins) {
+            foreach ($plugins as $function) {
+                $this->add_html($function() ?? '');
+            }
+        }
+    }
+}

lib/outputrenderers.php

@@ -37,6 +37,7 @@
 
 use core\di;
 use core\hook\manager as hook_manager;
+use core\hook\output\before_standard_top_of_body_html_generation;
 use core\output\named_templatable;
 use core_completion\cm_completion_details;
 use core_course\output\activity_information;
@@ -811,22 +812,16 @@ class core_renderer extends renderer_base {
             $output .= "\n".$CFG->additionalhtmltopofbody;
         }
 
-        // 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, 'before_standard_top_of_body_html', [], '');
-            }
-        }
+        // 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/before_standard_top_of_body_html_generation.php');
 
-        // Give plugins an opportunity to inject extra html content. The callback
-        // must always return a string containing valid html.
-        $pluginswithfunction = get_plugins_with_function('before_standard_top_of_body_html', 'lib.php');
-        foreach ($pluginswithfunction as $plugins) {
-            foreach ($plugins as $function) {
-                $output .= $function();
-            }
-        }
+        // Allow components to add content to the top of the body.
+        $hook = new before_standard_top_of_body_html_generation($this, $output);
+        di::get(hook_manager::class)->dispatch($hook);
+        $hook->process_legacy_callbacks();
+        $output = $hook->get_output();
 
         $output .= $this->maintenance_warning();
 

lib/tests/core_renderer_test.php

@@ -0,0 +1,64 @@
+<?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 core_renderer;
+use moodle_page;
+
+/**
+ * Tests for \core_renderer.
+ *
+ * @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
+ * @covers \core_renderer
+ */
+final class core_renderer_test extends \advanced_testcase {
+    /**
+     * @covers \core\hook\before_standard_top_of_body_html_generation
+     */
+    public function test_standard_top_of_body_html(): void {
+        $page = new moodle_page();
+        $renderer = new core_renderer($page, RENDERER_TARGET_GENERAL);
+
+        $html = $renderer->standard_top_of_body_html();
+        $this->assertIsString($html);
+        $this->assertStringNotContainsString('A heading can be added to the top of the body HTML', $html);
+    }
+
+    /**
+     * @covers \core\hook\before_standard_top_of_body_html_generation
+     */
+    public function test_before_standard_top_of_body_html_generation_hooked(): void {
+        require_once(__DIR__ . '/fixtures/core_renderer/before_standard_top_of_body_html_generation_callbacks.php');
+
+        \core\di::set(
+            \core\hook\manager::class,
+            \core\hook\manager::phpunit_get_instance([
+                'test_plugin1' => __DIR__ . '/fixtures/core_renderer/before_standard_top_of_body_html_generation_hooks.php',
+            ]),
+        );
+
+        $page = new moodle_page();
+        $renderer = new core_renderer($page, RENDERER_TARGET_GENERAL);
+
+        $html = $renderer->standard_top_of_body_html();
+        $this->assertIsString($html);
+        $this->assertStringContainsString('A heading can be added to the top of the body HTML', $html);
+    }
+}

lib/tests/fixtures/core_renderer/before_standard_top_of_body_html_generation_callbacks.php

@@ -0,0 +1,38 @@
+<?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::htmlattributes.
+ *
+ * @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 before_standard_top_of_body_html_generation_callbacks {
+    /**
+     * Fixture for adding a heading to the top of the body HTML.
+     *
+     * @param \core\hook\output\before_standard_top_of_body_html_generation $hook
+     */
+    public static function before_standard_top_of_body_html_generation(
+        \core\hook\output\before_standard_top_of_body_html_generation $hook,
+    ): void {
+        $hook->add_html("<h1>A heading can be added to the top of the body HTML</h1>");
+    }
+}

lib/tests/fixtures/core_renderer/before_standard_top_of_body_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 before_standard_top_of_body_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\before_standard_top_of_body_html_generation::class,
+        'callback' => \test_fixtures\core_renderer\before_standard_top_of_body_html_generation_callbacks::class
+            . '::before_standard_top_of_body_html_generation',
+    ],
+];

lib/upgrade.txt

@@ -39,6 +39,7 @@ information provided here is intended especially for developers.
 * The following callbacks have been migrated to hooks:
   - 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
 * Deprecated PARAM_ types with the exception of PARAM_CLEAN now emit a deprecation exception. These were all deprecated in Moodle 2.0.
 * A new \core\attribute\deprecated attribute can be used to more clearly describe deprecated methods.
 * A new \core\deprecation class can be used to inspect for deprecated attributes: