MDL-84531 core: default deprecated attribute $replacement to null.

.upgradenotes/MDL-84531-2025061213382940.yml

@@ -0,0 +1,7 @@
+issueNumber: MDL-84531
+notes:
+  core:
+    - message: >-
+        The `\core\attribute\deprecated` attribute constructor `$replacement`
+        parameter now defaults to null, and can be omitted
+      type: changed

lib/classes/attribute/deprecated.php

@@ -16,6 +16,8 @@
 
 namespace core\attribute;
 
+use core\exception\coding_exception;
+
 /**
  * Attribute to describe a deprecated item.
  *
@@ -25,10 +27,12 @@ namespace core\attribute;
  */
 #[\Attribute]
 class deprecated {
+
     /**
      * A deprecated item.
      *
-     * This attribute can be applied to any function, class, method, constant, property, enum, etc.
+     * This attribute can be applied to any function, class, method, constant, property, enum, etc. Note that at least one of
+     * $replacement, $since or $reason parameters must be non-null
      *
      * Note: The mere presence of the attribute does not do anything. It must be checked by some part of the code.
      *
@@ -40,7 +44,7 @@ class deprecated {
      * @param bool $emit Whether to emit a deprecation warning
      */
     public function __construct(
-        public readonly ?string $replacement,
+        public readonly ?string $replacement = null,
         public readonly ?string $since = null,
         public readonly ?string $reason = null,
         public readonly ?string $mdl = null,
@@ -48,8 +52,8 @@ class deprecated {
         public readonly bool $emit = true,
     ) {
         if ($replacement === null && $reason === null && $mdl === null) {
-            throw new \coding_exception(
-                'A deprecated item which is not deprecated must provide a reason, or an issue number.',
+            throw new coding_exception(
+                'A deprecated item must provide either a replacement, reason, or an issue number.',
             );
         }
     }

lib/tests/deprecation_test.php

@@ -187,11 +187,10 @@ final class deprecation_test extends \advanced_testcase {
         ];
     }
 
-    public function test_deprecated_without_replacement(): void {
+    public function test_deprecated_missing_constuctor_parameters(): void {
         $this->expectException(\coding_exception::class);
-        new deprecated(
-            replacement: null,
-        );
+        $this->expectExceptionMessage('A deprecated item must provide either a replacement, reason, or an issue number.');
+        new deprecated();
     }
 
     /**