From a9047f7ca3b1746c7d0976819f2910b29796541b Mon Sep 17 00:00:00 2001
From: Andrew Nicols <andrew@nicols.co.uk>
Date: Mon, 12 Aug 2024 12:19:07 +0800
Subject: [PATCH] docs: Update filter docs for MDL-82427

---
 .../plugintypes/filter/_examples/filter.php   |  4 +++-
 docs/apis/plugintypes/filter/index.md         | 16 +++++++++------
 docs/devupdate.md                             | 20 +++++++++++++++++++
 3 files changed, 33 insertions(+), 7 deletions(-)

diff --git a/docs/apis/plugintypes/filter/_examples/filter.php b/docs/apis/plugintypes/filter/_examples/filter.php
index b812f5f644..39c3961eb7 100644
--- a/docs/apis/plugintypes/filter/_examples/filter.php
+++ b/docs/apis/plugintypes/filter/_examples/filter.php
@@ -1,4 +1,6 @@
-class filter_pluginname extends moodle_text_filter {
+namespace filter_pluginname;
+
+class text_filter extends \core_filters\text_filter {
     function filter(string $text, array $options = []) {
         // Return the modified text.
         return $text;
diff --git a/docs/apis/plugintypes/filter/index.md b/docs/apis/plugintypes/filter/index.md
index d5a80fdfc1..0d57a06bcc 100644
--- a/docs/apis/plugintypes/filter/index.md
+++ b/docs/apis/plugintypes/filter/index.md
@@ -45,7 +45,8 @@ Each plugin is in a separate subdirectory and consists of a number of _mandatory
  |-- lang
  |   `-- en
  |       `-- filter_pluginname.php
- |-- filter.php
+ |-- classes
+ |   `-- text_filter.php
  `-- version.php
 ```
 
@@ -59,12 +60,12 @@ import Filter from '!!raw-loader!./_examples/filter.php';
 
 <ComponentFileSummary
     required
-    filepath="/filter.php"
+    filepath="/classes/text_filter.php"
     summary="Filter main class"
     plugintype="filter"
     pluginname="pluginname"
     example={Filter}
-    description="The filter file contains the code for the main filter class. Unlike more complex plugins like activities or repositories, filters only have one mandatory class extending the core moodle_text_filter class."
+    description="The filter file contains the code for the main filter class. Unlike more complex plugins like activities or repositories, filters only have one mandatory class extending the core `\core_filters\text_filter` class."
 />
 
 ### version.php
@@ -137,7 +138,7 @@ To support this behaviour, a filter plugin must provide a `filterlocalsettings.p
   <div>
 
 ```php title="filterlocalsettings.php"
-class pluginfile_filter_local_settings_form extends filter_local_settings_form {
+class pluginfile_filter_local_settings_form extends \core_filters\form\local_settings_form {
     protected function definition_inner(\MoodleQuickForm $mform) {
         $mform->addElement(
             'text',
@@ -159,11 +160,14 @@ All the local configurations can be accessed in the main filter class in the `$t
   <summary>View example</summary>
   <div>
 
-```php title="filter.php"
+```php title="filter/pluginname/classes/text_filter.php"
 <?php
-class filter_helloworld extends moodle_text_filter {
+namespace filter_pluginname;
+
+class text_filter extends \core_filters\text_filter {
     public function filter(string $text, array $options = []) {
         global $CFG;
+
         $search = $this->localconfig['word'] ?? 'default';
         return str_replace($search, "Hello $search!", $text);
     }
diff --git a/docs/devupdate.md b/docs/devupdate.md
index 443ba32db3..e3d581c0d4 100644
--- a/docs/devupdate.md
+++ b/docs/devupdate.md
@@ -94,6 +94,26 @@ Check changes in any of the core plugins that implement the reset course method.
 
 :::
 
+## Filter Plugins
+
+<Since version="4.5" issueNumber="MDL-82427" />
+
+Filter plugins and the Filter API have been updated to use the standard Moodle Class Autoloading infrastructure.
+
+To ensure that your plugin continues to work in Moodle 4.5, you should move the `filter_[pluginname]` class located in `filter/[pluginname]/filter.php` to `filter/[pluginname]/classes/text_filter.php`, setting the namespace to `filter_[pluginname]` and renaming the class to `text_filter`.
+
+:::tip Codebases supporting multiple versions of Moodle
+
+If your codebase also supports Moodle 4.4 and earlier then you will also need to create a file in the 'old' location (`filter/[pluginname]/filter.php`) with the following content:
+
+```php title="filter/[pluginname]/filter.php"
+class_alias(\filter_[pluginname]\text_filter::class, \filter_[pluginname]::class);
+```
+
+This will ensure that the plugin class is available at both the old and new locations.
+
+:::
+
 ## TinyMCE plugins
 
 The `helplinktext` language string is no longer required by editor plugins, instead the `pluginname` will be used in the help dialogue