diff --git a/.upgradenotes/MDL-85897-2025070109410496.yml b/.upgradenotes/MDL-85897-2025070109410496.yml new file mode 100644 index 00000000000..c98a44d56b3 --- /dev/null +++ b/.upgradenotes/MDL-85897-2025070109410496.yml @@ -0,0 +1,14 @@ +issueNumber: MDL-85897 +notes: + core: + - message: > + Added a new `\core\deprecation::emit_deprecation()` method which should be used in places where a deprecation is known to occur. This method will throw debugging if no deprecation notice was found, for example: + + ```php + + public function deprecated_method(): void { + \core\deprecation::emit_deprecation([self::class, __FUNCTION__]); + } + + ``` + type: changed diff --git a/public/lib/classes/deprecation.php b/public/lib/classes/deprecation.php index e11b12058ac..310408716bb 100644 --- a/public/lib/classes/deprecation.php +++ b/public/lib/classes/deprecation.php @@ -137,6 +137,27 @@ class deprecation { } } + /** + * Emit a deprecation notice for a reference. + * + * This will emit a deprecation notice if the reference is deprecated. + * If the reference is not deprecated, the function will emit debugging information. + * + * @param array|string|object $reference + */ + public static function emit_deprecation(array|string|object $reference): void { + if ($attribute = self::from($reference)) { + self::emit_deprecation_notice($attribute); + } else { + // If the reference is not deprecated, we should not emit a notice. + // This is to prevent false positives in tests. + debugging( + "Deprecation notice requested but object is not deprecated.", + DEBUG_DEVELOPER, + ); + } + } + /** * Fetch a referenced deprecation attribute from a reflected object. * diff --git a/public/lib/tests/deprecation_test.php b/public/lib/tests/deprecation_test.php index 6e4268b6a48..a80ab08cc89 100644 --- a/public/lib/tests/deprecation_test.php +++ b/public/lib/tests/deprecation_test.php @@ -205,11 +205,17 @@ final class deprecation_test extends \advanced_testcase { deprecation::emit_deprecation_if_present($reference); $this->assertDebuggingCalled(deprecation::get_deprecation_string($attribute)); + + deprecation::emit_deprecation($reference); + $this->assertDebuggingCalled(deprecation::get_deprecation_string($attribute)); } else { $this->assertNull($attribute); $this->assertFalse(deprecation::is_deprecated($reference)); deprecation::emit_deprecation_if_present($reference); $this->assertDebuggingNotCalled(); + + deprecation::emit_deprecation($reference); + $this->assertDebuggingCalled("Deprecation notice requested but object is not deprecated."); } }