MDL-85897 core: Add emit_deprecation() method

This changeset adds a new `\core\deprecation::emit_deprecation` method
with the same signature as the `emit_deprecation_if_found()` method.

It is intended to be used in places where something is guaranteed to
have been deprecated, and will throw appropriate debugging if the
deprecated attribute is not found.

The `emit_deprecation_if_found()` method should still be used where the
item being checked is not known to be deprecated or not, for example in
calling code.

.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

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.
      *

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.");
         }
     }