[DOC-CVS] [doc-en] master: ReturnTypeWillChange: Add warning about future strict return type (#5613)

Author: Mikhail Alferov (mmalferov)
Committer: GitHub (web-flow)
Pusher: jordikroon
Date: 2026-06-14T19:18:18+02:00

Commit: https://github.com/php/doc-en/commit/0019a7e201442447fd746c2852d28ba839ed15ae
Raw diff: https://github.com/php/doc-en/commit/0019a7e201442447fd746c2852d28ba839ed15ae.diff

ReturnTypeWillChange: Add warning about future strict return type (#5613)

Changed paths:
  M  language/predefined/attributes/returntypewillchange.xml


Diff:

diff --git a/language/predefined/attributes/returntypewillchange.xml b/language/predefined/attributes/returntypewillchange.xml
index 12f7f83961c6..f5f54acea897 100644
--- a/language/predefined/attributes/returntypewillchange.xml
+++ b/language/predefined/attributes/returntypewillchange.xml
@@ -7,15 +7,28 @@
 
   <section xml:id="returntypewillchange.intro">
    &reftitle.intro;
-   <para>
+   <simpara>
     Most non-final internal methods now require overriding methods to declare
     a compatible return type, otherwise a deprecated notice is emitted during
-    inheritance validation.
+    inheritance validation. This introduces a tentative return type phase:
+    the engine emits a deprecation notice instead of a fatal error when return
+    types are incompatible, before they become enforced in a future version.
     In case the return type cannot be declared for an overriding method due to
     PHP cross-version compatibility concerns,
     a <code>#[\ReturnTypeWillChange]</code> attribute can be added to silence
     the deprecation notice.
-   </para>
+   </simpara>
+
+   <warning>
+    <simpara>
+     The <classname>ReturnTypeWillChange</classname> attribute suppresses
+     deprecation warnings during the tentative return type phase <emphasis>only</emphasis>.
+     It has no effect when overriding methods defined in user-defined classes.
+     Once internal methods adopt strict types, mismatches in overriding method
+     signatures will cause a fatal error and this attribute will no longer have any effect.
+    </simpara>
+   </warning>
+
   </section>
 
   <section xml:id="returntypewillchange.synopsis">