diff --git a/docs/apis/core/hooks/index.md b/docs/apis/core/hooks/index.md index ad587356f8..aaa2a4b677 100644 --- a/docs/apis/core/hooks/index.md +++ b/docs/apis/core/hooks/index.md @@ -256,8 +256,10 @@ final class before_standard_footer_html_callbacks { $callbacks = [ [ 'hook' => \core\hook\output\before_standard_footer_html::class, - 'callback' => \test_fixtures\core_renderer\before_standard_footer_html_callbacks::class - . '::before_standard_footer_html', + 'callback' => [ + \test_fixtures\core_renderer\before_standard_footer_html_callbacks::class, + 'before_standard_footer_html', + ], ], ]; ``` @@ -278,12 +280,23 @@ This approach is harder to test in situ. Any plugin is free to register callbacks for all core and plugin hooks. The registration is done by adding a `db/hooks.php` file to plugin. -Callbacks **must** be provided as PHP callable strings in the form of "some\class\name::static_method". +Callbacks may be be provided as a PHP callable in either: + +- string notation, in the form of `some\class\name::static_method`; or +- array notation, in the form of `[\some\class\name::class, 'static_method']`. + +:::danger Use of array notation + + + +Support for Array notated callbacks was introduced in Moodle 4.4. If you are writing a callback for a Moodle 4.3 site, you _must_ use the string notation. + +::: Hook callbacks are executed in the order of their priority from highest to lowest. Any guidelines for callback priority should be described in hook descriptions if necessary. -:::important +:::caution Callbacks _are executed during system installation and all upgrades_, the callback methods must verify the plugin is in correct state. Often the easies way is to @@ -314,14 +327,14 @@ class hook_callbacks { } ``` -Then developer has to register this new method as the hook callback by adding it to the db/hooks.php file. +Then the developer has to register this new method as the hook callback by adding it to the `db/hooks.php` file. ```php title="/local/stuff/db/hooks.php" mod_activity\hook\installation_finished::class, - 'callback' => local_stuff\local\hook_callbacks::class . '::activity_installation_finished', + 'callback' => [\local_stuff\local\hook_callbacks::class, 'activity_installation_finished'], 'priority' => 500, ], ]; diff --git a/docs/devupdate.md b/docs/devupdate.md index a8be5a8baf..f3b11bcfdd 100644 --- a/docs/devupdate.md +++ b/docs/devupdate.md @@ -67,6 +67,8 @@ Other variations of the above are also possible. ### Hooks +#### Hook interfaces + Attribute-based alternatives to the `\core\hook\described_hook`, and `\core\hook\deprecated_callback_replacement` interfaces are now supported. @@ -99,6 +101,62 @@ It is still possible to use the `\core\hook\described_hook` and `\core\hook\depr ::: +#### Callable notation + + + +When specifying the callback for a hook, you can now do so using the callable array notation, for example: + + + + + +```php +$callbacks = [ + [ + 'hook' => 'test_plugin\\hook\\hook', + // Array notation: + 'callback' => [\test_plugin\callbacks::class, 'test1'], + ], +]; +``` + + + + + +```php +$callbacks = [ + [ + 'hook' => 'test_plugin\\hook\\hook', + // String notation: + 'callback' => \test_plugin\callbacks::class . '::test1', + ], +]; +``` + + + + + +```php +$callbacks = [ + [ + 'hook' => 'test_plugin\\hook\\hook', + // Strongly discouraged: + 'callback' => '\\test_plugin\\callbacks::test1', + ], +]; +``` + + + + + +:::danger Callbacks in earlier versions of Moodle + +If writing a callback for Moodle 4.3, you **must** use the string notation. + ### String formatting #### Deprecation of format_* parameters @@ -323,7 +381,7 @@ See more information in [Bootstrap 5 migration](./guides/bs5migration/index.md). -The new course/section.php page is designed exclusively for displaying individual section content. It only requires `sectionid`, eliminating the need for the legacy sectionnumber. +The new course/section.php page is designed exclusively for displaying individual section content. It only requires `sectionid`, eliminating the need for the legacy `sectionnumber`. Enhancements to this page: