MDL-81063 tool_usertours: Allow hooks to manage usertour filters

Two new hooks are introduced to allow plugins to add their own user tour
filters.

Separate hooks are identified for both clientside, and serverside
filters.

admin/tool/usertours/amd/src/usertours.js

@@ -43,8 +43,8 @@ const findMatchingTour = (tourDetails, filters) => {
  */
 export const init = async(tourDetails, filters) => {
     const requirements = [];
-    filters.forEach(filter => {
-        requirements.push(import(`tool_usertours/filter_${filter}`));
+    filters.forEach((filter) => {
+        requirements.push(import(filter));
     });
 
     const filterPlugins = await Promise.all(requirements);

admin/tool/usertours/classes/helper.php

@@ -16,6 +16,7 @@
 
 namespace tool_usertours;
 
+use coding_exception;
 use core\output\inplace_editable;
 
 /**
@@ -534,10 +535,7 @@ class helper {
                 ];
             }, $tours);
 
-            $filternames = [];
-            foreach ($filters as $filter) {
-                    $filternames[] = $filter::get_filter_name();
-            }
+            $filternames = self::get_clientside_filter_module_names($filters);
 
             $PAGE->requires->js_call_amd('tool_usertours/usertours', 'init', [
                 $tourdetails,
@@ -546,19 +544,48 @@ class helper {
         }
     }
 
+    /**
+     * Get the JS module names for the filters.
+     *
+     * @param array $filters
+     * @return array
+     * @throws coding_exception
+     */
+    public static function get_clientside_filter_module_names(array $filters): array {
+        $filternames = [];
+        foreach ($filters as $filter) {
+            if ($component = \core_component::get_component_from_classname($filter)) {
+                $filternames[] = sprintf(
+                    "%s/filter_%s",
+                    $component,
+                    $filter::get_filter_name(),
+                );
+            } else {
+                throw new \coding_exception("Could not determine component for filter class {$filter}");
+            }
+        }
+
+        return $filternames;
+    }
+
     /**
      * Get a list of all possible filters.
      *
      * @return  array
      */
     public static function get_all_filters() {
-        $filters = \core_component::get_component_classes_in_namespace('tool_usertours', 'local\filter');
-        $filters = array_keys($filters);
+        $hook = new hook\before_serverside_filter_fetch(array_keys(
+            \core_component::get_component_classes_in_namespace('tool_usertours', 'local\filter')
+        ));
+        \core\di::get(\core\hook\manager::class)->dispatch($hook);
 
-        $filters = array_filter($filters, function ($filterclass) {
-            $rc = new \ReflectionClass($filterclass);
-            return $rc->isInstantiable();
-        });
+        $filters = array_filter(
+            $hook->get_filter_list(),
+            function ($filterclass) {
+                $rc = new \ReflectionClass($filterclass);
+                return $rc->isInstantiable();
+            }
+        );
 
         $filters = array_merge($filters, static::get_all_clientside_filters());
 
@@ -571,13 +598,18 @@ class helper {
      * @return  array
      */
     public static function get_all_clientside_filters() {
-        $filters = \core_component::get_component_classes_in_namespace('tool_usertours', 'local\clientside_filter');
-        $filters = array_keys($filters);
+        $hook = new hook\before_clientside_filter_fetch(array_keys(
+            \core_component::get_component_classes_in_namespace('tool_usertours', 'local\clientside_filter')
+        ));
+        \core\di::get(\core\hook\manager::class)->dispatch($hook);
 
-        $filters = array_filter($filters, function ($filterclass) {
-            $rc = new \ReflectionClass($filterclass);
-            return $rc->isInstantiable();
-        });
+        $filters = array_filter(
+            $hook->get_filter_list(),
+            function ($filterclass) {
+                $rc = new \ReflectionClass($filterclass);
+                return $rc->isInstantiable();
+            }
+        );
 
         return $filters;
     }

admin/tool/usertours/classes/hook/before_clientside_filter_fetch.php

@@ -0,0 +1,74 @@
+<?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_usertours\hook;
+
+/**
+ * Provides the ability to add and remove custom client-side filters to the user tour filter list.
+ *
+ * @package    tool_usertours
+ * @copyright  2024 Andrew Lyons <andrew@nicols.co.uk>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+#[\core\attribute\label('Provides the ability to add and remove custom client-side filters to the user tour filter list.')]
+#[\core\attribute\tags('tool_usertours')]
+class before_clientside_filter_fetch {
+    /**
+     * Create a new instance of the hook.
+     *
+     * @param array $filters
+     */
+    public function __construct(
+        /** @var array The list of filters applied */
+        protected array $filters,
+    ) {
+    }
+
+    /**
+     * Add a filter classname to the list of filters to be processed.
+     *
+     * @param string $classname
+     * @return self
+     */
+    public function add_filter_by_classname(string $classname): self {
+        if (!\is_a($classname, \tool_usertours\local\clientside_filter\clientside_filter::class, true)) {
+            throw new \coding_exception("Invalid clientside filter class {$classname}");
+        }
+        $this->filters[] = $classname;
+
+        return $this;
+    }
+
+    /**
+     * Remove a filter classname from the list of filters to be processed.
+     *
+     * @param string $classname
+     * @return self
+     */
+    public function remove_filter_by_classname(string $classname): self {
+        $this->filters = array_filter($this->filters, fn($filter) => $filter !== $classname);
+        return $this;
+    }
+
+    /**
+     * Get the list of filters to be processed.
+     *
+     * @return array
+     */
+    public function get_filter_list(): array {
+        return $this->filters;
+    }
+}

admin/tool/usertours/classes/hook/before_serverside_filter_fetch.php

@@ -0,0 +1,78 @@
+<?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_usertours\hook;
+
+/**
+ * Provides the ability to add and remove custom server-side filters to the user tour filter list.
+ *
+ * @package    tool_usertours
+ * @copyright  2024 Andrew Lyons <andrew@nicols.co.uk>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+#[\core\attribute\label('Provides the ability to add and remove custom server-side filters to the user tour filter list.')]
+#[\core\attribute\tags('tool_usertours')]
+class before_serverside_filter_fetch {
+    /**
+     * Create a new instance of the hook.
+     *
+     * @param array $filters
+     */
+    public function __construct(
+        /** @var array The list of filters applied */
+        protected array $filters,
+    ) {
+    }
+
+    /**
+     * Add a filter classname to the list of filters to be processed.
+     *
+     * @param string $classname
+     * @return self
+     */
+    public function add_filter_by_classname(string $classname): self {
+        if (!\is_a($classname, \tool_usertours\local\filter\base::class, true)) {
+            throw new \coding_exception("Invalid filter class {$classname}");
+        }
+
+        if (\is_a($classname, \tool_usertours\local\clientside_filter\clientside_filter::class, true)) {
+            throw new \coding_exception("Invalid filter class {$classname} (client-side filter for server-side hook)");
+        }
+
+        $this->filters[] = $classname;
+        return $this;
+    }
+
+    /**
+     * Remove a filter classname from the list of filters to be processed.
+     *
+     * @param string $classname
+     * @return self
+     */
+    public function remove_filter_by_classname(string $classname): self {
+        $this->filters = array_filter($this->filters, fn($filter) => $filter !== $classname);
+        return $this;
+    }
+
+    /**
+     * Get the list of filters to be processed.
+     *
+     * @return array
+     */
+    public function get_filter_list(): array {
+        return $this->filters;
+    }
+}

admin/tool/usertours/tests/fixtures/clientside_filter_for_serverside_hook.php

@@ -0,0 +1,45 @@
+<?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 fixtures for testing of hooks.
+ *
+ * @package    tool_usertours
+ * @copyright  2024 Andrew Lyons <andrew@nicols.co.uk>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+namespace tool_usertours\test\hook\clientside_filter_for_serverside_hook;
+
+defined('MOODLE_INTERNAL') || die();
+
+final class filter_class extends \tool_usertours\local\clientside_filter\clientside_filter {
+}
+
+final class callback {
+    public static function callme(
+        \tool_usertours\hook\before_serverside_filter_fetch $hook
+    ): void {
+        $hook->add_filter_by_classname(filter_class::class);
+    }
+}
+
+$callbacks = [
+    [
+        'hook' => \tool_usertours\hook\before_serverside_filter_fetch::class,
+        'callback' => callback::class . '::callme',
+    ],
+];

admin/tool/usertours/tests/fixtures/hook_fixtures.php

@@ -0,0 +1,61 @@
+<?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 fixtures for testing of hooks.
+ *
+ * @package    tool_usertours
+ * @copyright  2024 Andrew Lyons <andrew@nicols.co.uk>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+namespace tool_usertours\test\hook;
+
+defined('MOODLE_INTERNAL') || die();
+
+final class serverside_filter_fixture extends \tool_usertours\local\filter\base {
+}
+
+final class clientside_filter_fixture extends \tool_usertours\local\clientside_filter\clientside_filter {
+}
+
+final class hook_fixtures {
+    public static function example_serverside_hook(
+        \tool_usertours\hook\before_serverside_filter_fetch $hook
+    ): void {
+        // Add a valid serverside and an invalid clientside filter.
+        $hook->add_filter_by_classname(\tool_usertours\test\hook\serverside_filter_fixture::class);
+        $hook->remove_filter_by_classname(\tool_usertours\local\filter\accessdate::class);
+    }
+
+    public static function example_clientside_hook(
+        \tool_usertours\hook\before_clientside_filter_fetch $hook
+    ): void {
+        $hook->add_filter_by_classname(\tool_usertours\test\hook\clientside_filter_fixture::class);
+        $hook->remove_filter_by_classname(\tool_usertours\local\clientside_filter\cssselector::class);
+    }
+}
+
+$callbacks = [
+    [
+        'hook' => \tool_usertours\hook\before_serverside_filter_fetch::class,
+        'callback' => \tool_usertours\test\hook\hook_fixtures::class . '::example_serverside_hook',
+    ],
+    [
+        'hook' => \tool_usertours\hook\before_clientside_filter_fetch::class,
+        'callback' => \tool_usertours\test\hook\hook_fixtures::class . '::example_clientside_hook',
+    ],
+];

admin/tool/usertours/tests/fixtures/invalid_clientside_hook_fixture.php

@@ -0,0 +1,43 @@
+<?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 fixtures for testing of hooks.
+ *
+ * @package    tool_usertours
+ * @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();
+
+final class nocomponent_clientside_filter_fixture extends \tool_usertours\local\clientside_filter\clientside_filter {
+}
+
+final class nocomponent_clientside_hook_fixtures {
+    public static function example_clientside_hook(
+        \tool_usertours\hook\before_clientside_filter_fetch $hook
+    ): void {
+        $hook->add_filter_by_classname(\nocomponent_clientside_filter_fixture::class);
+    }
+}
+
+$callbacks = [
+    [
+        'hook' => \tool_usertours\hook\before_clientside_filter_fetch::class,
+        'callback' => \nocomponent_clientside_hook_fixtures::class . '::example_clientside_hook',
+    ],
+];

admin/tool/usertours/tests/fixtures/invalid_serverside_hook_fixture.php

@@ -0,0 +1,43 @@
+<?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 fixtures for testing of hooks.
+ *
+ * @package    tool_usertours
+ * @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();
+
+final class nocomponent_serverside_filter_fixture {
+}
+
+final class nocomponent_serverside_hook_fixtures {
+    public static function example_serverside_hook(
+        \tool_usertours\hook\before_serverside_filter_fetch $hook
+    ): void {
+        $hook->add_filter_by_classname(\nocomponent_serverside_filter_fixture::class);
+    }
+}
+
+$callbacks = [
+    [
+        'hook' => \tool_usertours\hook\before_serverside_filter_fetch::class,
+        'callback' => \nocomponent_serverside_hook_fixtures::class . '::example_serverside_hook',
+    ],
+];

admin/tool/usertours/tests/fixtures/serverside_filter_for_clientside_hook.php

@@ -0,0 +1,45 @@
+<?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 fixtures for testing of hooks.
+ *
+ * @package    tool_usertours
+ * @copyright  2024 Andrew Lyons <andrew@nicols.co.uk>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+namespace tool_usertours\test\hook\serverside_filter_for_clientside_hook;
+
+defined('MOODLE_INTERNAL') || die();
+
+final class filter_class extends \tool_usertours\local\filter\base {
+}
+
+final class callback {
+    public static function callme(
+        \tool_usertours\hook\before_clientside_filter_fetch $hook
+    ): void {
+        $hook->add_filter_by_classname(filter_class::class);
+    }
+}
+
+$callbacks = [
+    [
+        'hook' => \tool_usertours\hook\before_clientside_filter_fetch::class,
+        'callback' => callback::class . '::callme',
+    ],
+];

admin/tool/usertours/tests/helper_test.php

@@ -16,17 +16,18 @@
 
 namespace tool_usertours;
 
-use advanced_testcase;
-
 /**
  * Tests for helper.
  *
  * @package    tool_usertours
+ * @category   test
  * @copyright  2022 Huong Nguyen <huongnv13@gmail.com>
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @covers   \tool_usertours\helper
+ * @covers \tool_usertours\helper
+ * @covers \tool_usertours\hook\before_serverside_filter_fetch
+ * @covers \tool_usertours\hook\before_clientside_filter_fetch
  */
-class helper_test extends advanced_testcase {
+final class helper_test extends \advanced_testcase {
     /**
      * Data Provider for get_string_from_input.
      *
@@ -71,4 +72,117 @@ class helper_test extends advanced_testcase {
     public function test_get_string_from_input($string, $expected): void {
         $this->assertEquals($expected, helper::get_string_from_input($string));
     }
+
+    public function test_get_all_filters(): void {
+        $filters = helper::get_all_filters();
+        $this->assertIsArray($filters);
+
+        array_map(
+            function ($filter) {
+                $this->assertIsString($filter);
+                $this->assertTrue(class_exists($filter));
+                $this->assertTrue(is_a($filter, \tool_usertours\local\filter\base::class, true));
+                $rc = new \ReflectionClass($filter);
+                $this->assertTrue($rc->isInstantiable());
+            },
+            $filters,
+        );
+
+        $this->assertNotContains(\tool_usertours\test\hook\serverside_filter_fixture::class, $filters);
+        $this->assertNotContains(\tool_usertours\test\hook\clientside_filter_fixture::class, $filters);
+        $this->assertContains(\tool_usertours\local\filter\accessdate::class, $filters);
+        $this->assertContains(\tool_usertours\local\clientside_filter\cssselector::class, $filters);
+
+        $filters = helper::get_all_clientside_filters();
+        array_map(
+            function ($filter) {
+                $this->assertIsString($filter);
+            },
+            $filters,
+        );
+    }
+
+    public function test_get_invalid_server_filter(): void {
+        \core\di::set(
+            \core\hook\manager::class,
+            \core\hook\manager::phpunit_get_instance([
+                'test_plugin1' => __DIR__ . '/fixtures/invalid_serverside_hook_fixture.php',
+            ]),
+        );
+
+        $this->expectException(\coding_exception::class);
+        helper::get_all_filters();
+    }
+
+    public function test_clientside_filter_for_serverside_hook(): void {
+        \core\di::set(
+            \core\hook\manager::class,
+            \core\hook\manager::phpunit_get_instance([
+                'test_plugin1' => __DIR__ . '/fixtures/clientside_filter_for_serverside_hook.php',
+            ]),
+        );
+
+        $this->expectException(\coding_exception::class);
+        helper::get_all_filters();
+    }
+
+    public function test_serverside_filter_for_clientside_hook(): void {
+        \core\di::set(
+            \core\hook\manager::class,
+            \core\hook\manager::phpunit_get_instance([
+                'test_plugin1' => __DIR__ . '/fixtures/serverside_filter_for_clientside_hook.php',
+            ]),
+        );
+
+        $this->expectException(\coding_exception::class);
+        helper::get_all_clientside_filters();
+    }
+
+    public function test_filter_hooks(): void {
+        \core\di::set(
+            \core\hook\manager::class,
+            \core\hook\manager::phpunit_get_instance([
+                'test_plugin1' => __DIR__ . '/fixtures/hook_fixtures.php',
+            ]),
+        );
+
+        $filters = helper::get_all_filters();
+        $this->assertIsArray($filters);
+
+        // Check the modifications from the serverside hook.
+        $this->assertContains(\tool_usertours\test\hook\serverside_filter_fixture::class, $filters);
+        $this->assertNotContains(\tool_usertours\test\hook\another_clientside_filter_fixture::class, $filters);
+        $this->assertNotContains(\tool_usertours\local\filter\accessdate::class, $filters);
+
+        // Check the modifications from the clientside hook.
+        $this->assertContains(\tool_usertours\test\hook\clientside_filter_fixture::class, $filters);
+        $this->assertNotContains(\tool_usertours\test\hook\another_serverside_filter_fixture::class, $filters);
+        $this->assertNotContains(\tool_usertours\local\clientside_filter\cssselector::class, $filters);
+
+        array_map(
+            function ($filter) {
+                $this->assertIsString($filter);
+                $this->assertTrue(class_exists($filter));
+                $this->assertTrue(is_a($filter, \tool_usertours\local\filter\base::class, true));
+                $rc = new \ReflectionClass($filter);
+                $this->assertTrue($rc->isInstantiable());
+            },
+            $filters,
+        );
+    }
+
+    public function test_get_clientside_filter_module_names(): void {
+        \core\di::set(
+            \core\hook\manager::class,
+            \core\hook\manager::phpunit_get_instance([
+                'test_plugin1' => __DIR__ . '/fixtures/invalid_clientside_hook_fixture.php',
+            ]),
+        );
+
+        $filters = helper::get_all_clientside_filters();
+
+        $this->expectException(\coding_exception::class);
+        $this->expectExceptionMessageMatches('/Could not determine component/');
+        helper::get_clientside_filter_module_names($filters);
+    }
 }

admin/tool/usertours/upgrade.txt

@@ -1,5 +1,12 @@
 This files describes API changes in the tool_usertours code.
 
+=== 4.4 ===
+* New hooks have been provided to allow plugins to define their own server-side, and client-side user tour filters.
+  The new hooks are named:
+  - \tool_usertours\hook\before_serverside_filter_fetch
+  - \tool_usertours\hook\before_clientside_filter_fetch
+  These hooks allow addition, and removal, of filters.
+
 === 4.0 ===
 * The `tourconfig` property returned by the `tool_usertours_fetch_and_start_tour`
   external method has also an `endtourlabel` property that contains the label to be used