[docs] Add docs for array notated hook callbacks

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
+
+<Since version="4.4" issueNumber="MDL-81180" />
+
+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"
 <?php
 $callbacks = [
     [
         'hook' => 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,
     ],
 ];

docs/devupdate.md

@@ -67,6 +67,8 @@ Other variations of the above are also possible.
 
 ### Hooks
 
+#### Hook interfaces
+
 <Since version="4.4" issueNumber="MDL-81011" />
 
 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
+
+<Since version="4.4" issueNumber="MDL-81180" />
+
+When specifying the callback for a hook, you can now do so using the callable array notation, for example:
+
+<Tabs>
+
+<TabItem value="array-notation" label="Array notation" default>
+
+```php
+$callbacks = [
+    [
+        'hook' => 'test_plugin\\hook\\hook',
+        // Array notation:
+        'callback' => [\test_plugin\callbacks::class, 'test1'],
+    ],
+];
+```
+
+</TabItem>
+
+<TabItem value="string-notation-using-class" label="String notation" default>
+
+```php
+$callbacks = [
+    [
+        'hook' => 'test_plugin\\hook\\hook',
+        // String notation:
+        'callback' => \test_plugin\callbacks::class . '::test1',
+    ],
+];
+```
+
+</TabItem>
+
+<TabItem value="string-notation-using-string" label="Alternate string notation (discouraged)" default>
+
+```php
+$callbacks = [
+    [
+        'hook' => 'test_plugin\\hook\\hook',
+        // Strongly discouraged:
+        'callback' => '\\test_plugin\\callbacks::test1',
+    ],
+];
+```
+
+</TabItem>
+
+</Tabs>
+
+:::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).
 
 <Since version="4.4" issueNumber="MDL-79986" />
 
-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: