Merge pull request #1661 from paulholden/customfields-singleton

Document singleton pattern changes in customfields handler.

Author: aanabit

docs/apis/core/customfields/index.md

@@ -27,7 +27,7 @@ New plugin type `customfield` was also added as part of the Custom fields API. A
 
 Component/plugin that uses custom fields must define a **handler class** for each area and a **configuration page**. Handler class must be called `<PLUGINNAME>/customfield/<AREA>_handler` and be placed in autoloaded location  `<PLUGINDIR>/classes/customfield/<AREA>_handler.php`. This class must extend **\core_customfield\handler** . Configuration page may be located anywhere. For course custom fields configuration the admin settings page is used [/course/customfield.php](https://github.com/moodle/moodle/blob/main/course/customfield.php). If the area uses `itemid` this page should take `itemid` as a parameter.
 
-Handler has protected constructor, to get a handler call `create()` method. Some areas may choose to return a singleton here:
+Handler has protected constructor, to get a handler call `create()` method. The base class implementation returns a cached instance (static cache) here:
 
 ```php
 $handler = HANDLERCLASS::create($itemid);

versioned_docs/version-5.2/apis/core/customfields/index.md

@@ -27,7 +27,7 @@ New plugin type `customfield` was also added as part of the Custom fields API. A
 
 Component/plugin that uses custom fields must define a **handler class** for each area and a **configuration page**. Handler class must be called `<PLUGINNAME>/customfield/<AREA>_handler` and be placed in autoloaded location  `<PLUGINDIR>/classes/customfield/<AREA>_handler.php`. This class must extend **\core_customfield\handler** . Configuration page may be located anywhere. For course custom fields configuration the admin settings page is used [/course/customfield.php](https://github.com/moodle/moodle/blob/main/course/customfield.php). If the area uses `itemid` this page should take `itemid` as a parameter.
 
-Handler has protected constructor, to get a handler call `create()` method. Some areas may choose to return a singleton here:
+Handler has protected constructor, to get a handler call `create()` method. The base class implementation returns a cached instance (static cache) here:
 
 ```php
 $handler = HANDLERCLASS::create($itemid);

versioned_docs/version-5.2/devupdate.md

@@ -34,3 +34,12 @@ The help descriptions within the Activity Chooser have been significantly update
 - A new optional string, `modulename_tip`, is available for a supplemental section for best practices, advice, or effective usage tips.
 
 Third-party activity modules and resources can adopt the same structure by adding these language strings (`modulename_summary`, `modulename_help`, and `modulename_tip`) to their plugin's language files. These strings should be placed in the plugin's language file, for example, `mod/pluginname/lang/en/pluginname.php`.
+
+## Custom fields base handler caching {/* #custom-fields-base-handler-caching */}
+
+<Since version="5.2" issueNumber="MDL-88176" />
+
+The base `\core_customfield\handler::create(...)` method now handles static caching and cache reset internally, so any custom caching logic
+in `create()` overrides in extending classes should be removed.
+
+More information about the Custom fields API can be found in the [Custom fields API documentation](./apis/core/customfields/index.md).