moodle-hooks-api

Moodle Hooks API

Overview

Moodle 4.4 introduced a typed Hooks API (core\hook\manager) replacing the unmaintainable jungle of magic callback functions like <plugin>_extend_navigation, <plugin>_before_http_headers, <plugin>_extend_settings_navigation, etc. Hooks are real classes with typed payloads, dispatched through \core\di::get(\core\hook\manager::class). Plugins register interest via db/hooks.php.

When to Use

• Adding cross-cutting behavior triggered by core (navigation, page output, user login, course events) without monkey-patching
• Migrating a plugin off legacy magic callbacks (deprecated 4.4+, will be removed)
• Authoring a hook class in core or in a plugin that other plugins can listen to
• Writing tests for hook listeners

Skip when: the event you care about is a \core\event\* (Events 2 API — different system, used for audit/logging). Hooks are for modifying behavior; Events are for reacting to facts.

Core concepts

Concept	Where it lives	Purpose
Hook class	classes/hook/<name>.php	Typed payload, optional setters for listeners to mutate
Listener registration	db/hooks.php	Maps hook class -> callback (Class::method) + priority
Dispatcher call	Core or plugin code	\core\di::get(\core\hook\manager::class)->dispatch(new \plugin\hook\thing(...));
Listener method	Any class	Static or instance method taking the hook instance

Listening to a core hook

db/hooks.php:

<?php
defined('MOODLE_INTERNAL') || die();

$callbacks = [
    [
        'hook'     => \core\hook\output\before_standard_top_of_body_html_generation::class,
        'callback' => \local_example\hook_listener::class . '::inject_banner',
        'priority' => 100, // higher runs first
    ],
];

classes/hook_listener.php:

<?php
namespace local_example;

use core\hook\output\before_standard_top_of_body_html_generation as hook;

class hook_listener {
    public static function inject_banner(hook $hook): void {
        global $USER;
        if (isguestuser() || !isloggedin()) {
            return;
        }
        $hook->add_html('<div class="alert alert-info">Hello, ' . s($USER->firstname) . '</div>');
    }
}