From 3a7da99f4553aaaaff452d5d1268eeec8b351e62 Mon Sep 17 00:00:00 2001 From: Andrew Nicols Date: Thu, 18 Jan 2024 15:09:41 +0800 Subject: [PATCH] [docs] Add notes about deprecation API --- docs/apis/core/deprecation/index.md | 113 ++++++++++++++++++++++++++++ docs/devupdate.md | 59 +++++++++++++++ 2 files changed, 172 insertions(+) create mode 100644 docs/apis/core/deprecation/index.md diff --git a/docs/apis/core/deprecation/index.md b/docs/apis/core/deprecation/index.md new file mode 100644 index 0000000000..3b3926a9e1 --- /dev/null +++ b/docs/apis/core/deprecation/index.md @@ -0,0 +1,113 @@ +--- +title: Deprecation API +tags: +- deprecation +--- + + + +import { Since } from '@site/src/components'; + + + +When deprecating a code feature, it is often desirable to include a reasonable amount of information, and to provide a consistent deprecation message. + +In some cases it is also desirable to check if a called class, or method, has been marked as deprecated. + +One way to simplify this is through use of the `\core\deprecated` PHP attribute, which can be used in conjunction with the `\core\deprecation` class. + +:::note + +Please note that the attribute does _not_ replace the `@deprecated` phpdoc annotation. They serve slightly different purposes. + +::: + +The attribute can be used to specify information including: + +- the replacement for that feature +- the version that the feature was deprecated in +- the relevant MDL +- the reason for deprecation +- whether the deprecation is final + +## The `deprecated` attribute + +The attribute is a Moodle PHP Attribute and can be applied to: + +- classes, traits, interfaces, and enums +- enum cases +- global functions +- class constants, properties, and methods + +```php title="Example attribute usage" +// On a global function: +#[\core\deprecated('random_bytes', since: '4.3')] +function random_bytes_emulate($length) { + // Replaced by random_bytes since Moodle 4.3. +} + +// On a class: +#[\core\deprecated(replacement: null, since: '4.4', reason: 'This functionality has been removed.')] +class example { + #[\core\deprecated( + replacement: '\core\example::do_something', + since: '4.3', + reason: 'No longer required', + mdl: 'MDL-12345', + )] + public function do_something(): void {} +} + +// On an enum case: +enum example { + #[\core\deprecated('example::OPTION', since: '4.4', final: true)] + case OPTION; +} +``` + +## Inspecting the attribute + +The `\core\deprecation` class contains helper methods to inspect for use of the deprecated attribute and allows usage including: + +- checking if a feature is deprecated +- emitting a deprecation notice if a feature is deprecated +- fetching an instance of the attribute to query further + +```php title="Examples of usage" +// A method which has been initially deprecated, and replaced by 'random_bytes'. It should show debugging. +/** @deprecated since 4.3 */ +#[\core\deprecated('random_bytes', since: '4.3')] +function random_bytes_emulate($length) { + \core\deprecation::emit_deprecation_if_present(__FUNCTION__); + return random_bytes($length); +} + +// A method which has been finally deprecated and should throw an exception. +/** @deprecated since 2.7 */ +#[\core\deprecated(replacement: 'Events API', since: '2.3', final: true)] +function add_to_log() { + \core\deprecation::emit_deprecation_if_present(__FUNCTION__); +} + +// Checking when an enum case is deprecated: +\core\deprecation::is_deprecated(\core\param::RAW); // Returns false. +\core\deprecation::is_deprecated(\core\param::INTEGER); // Returns true. + +// On an collection of items. +foreach ($values as $value) { + \core\deprecation::emit_deprecation_if_present($value); + $value->do_things(); +} + +// Checking if a class is deprecated: +\core\deprecation::is_deprecated(\core\task\manager::class); // Returns false. + +// Checking if an instantiated class is deprecated: +\core\deprecation::is_deprecated(new \moodle_url('/example/')); + +// Checking if a class method is deprecated: +\core\deprecation::is_deprecated([\moodle_url::class, 'out']); +\core\deprecation::is_deprecated([new \moodle_url('/example/'), 'out']); +``` + +This functionality is intended to simplify deprecation of features such as constants, enums, and related items which are called from centralised APIs and difficult to detect as deprecated. diff --git a/docs/devupdate.md b/docs/devupdate.md index 9ea49c6cbd..db4fd085f7 100644 --- a/docs/devupdate.md +++ b/docs/devupdate.md @@ -231,6 +231,65 @@ A number of deprecated parameter types have been deprecated, these include: These param types have all been deprecated since Moodle 2.0. +## Introduction of `deprecated` attribute + +A new `\core\deprecated` attribute, and related `\core\deprecation` class have been introduced to provide a standardised way to emit deprecation notices. + +The attribute can be applied to: + +- classes, traits, interfaces, and enums +- enum cases +- global functions +- class constants, properties, and methods + +The attribute can be used to specify information including: + +- the version that a feature was deprecated +- the relevant MDL +- the reason for deprecation +- any replacement +- whether the deprecation is final + +The `\core\deprecation` class contains helper methods to inspect for use of the deprecated attribute and allows usage including: + +- checking if a feature is deprecated +- emitting a deprecation notice if a feature is deprecated + +```php title="Examples of usage" +// A method which has been initially deprecated and should show debugging. +/** @deprecated since 4.3 */ +#[\core\deprecated(replacement: 'random_bytes', since: '4.3')] +function random_bytes_emulate($length) { + \core\deprecation::emit_deprecation_if_present(__FUNCTION__); + return random_bytes($length); +} + +// A method which has been finally deprecated and should throw an exception. +/** @deprecated since 2.7 */ +#[\core\deprecated(replacement: 'Events API', since: '2.3', final: true)] +function add_to_log() { + \core\deprecation::emit_deprecation_if_present(__FUNCTION__); +} + +// Checking when an enum case is deprecated: +\core\deprecation::is_deprecated(\core\param::RAW); // Returns false. +\core\deprecation::is_deprecated(\core\param::INTEGER); // Returns true. + +// Checking if a class is deprecated: +\core\deprecation::is_deprecated(\core\task\manager::class); // Returns false. + +// Checking if an instantiated class is deprecated: +\core\deprecation::is_deprecated(new \moodle_url('/example/')); + +// Checking if a class method is deprecated: +\core\deprecation::is_deprecated([\moodle_url::class, 'out']); +\core\deprecation::is_deprecated([new \moodle_url('/example/'), 'out']); +``` + +This functionality is intended to simplify deprecation of features such as constants, enums, and related items which are called from centralised APIs and difficult to detect as deprecated. + +This functionality does not replace the phpdoc `@deprecated` docblock. + ## Enrolment ### Support for multiple instances in csv course upload