From 7ce60e241428f14a6a6fcb2b6c1a26d999395d39 Mon Sep 17 00:00:00 2001 From: Mikhail Alferov Date: Mon, 15 Jun 2026 15:45:57 +0300 Subject: [PATCH 1/8] returntypewillchange.xml Update ReturnTypeWillChange intro for clarity I know I'm revisiting this topic so soon, but the clarity of the current phrasing leaves a lot to be desired. What if we structure and present the page the way this PR suggests? --- .../attributes/returntypewillchange.xml | 43 +++++++++++++------ 1 file changed, 30 insertions(+), 13 deletions(-) diff --git a/language/predefined/attributes/returntypewillchange.xml b/language/predefined/attributes/returntypewillchange.xml index f5f54acea897..f0891463b0de 100644 --- a/language/predefined/attributes/returntypewillchange.xml +++ b/language/predefined/attributes/returntypewillchange.xml @@ -7,28 +7,45 @@
&reftitle.intro; + + As of PHP 8.1.0, a tentative phase of transitioning to return type declarations + for internal class methods began. + + Most non-final internal methods now require overriding methods to declare - a compatible return type, otherwise a deprecated notice is emitted during - 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. + a compatible return type. Otherwise, a deprecation notice is emitted during + inheritance validation, warning that the signature violates covariance rules. + + + + Return type compatibility checks for internal class extensions remain in a soft mode + until a future PHP version enforces strict checking. + At that point, mismatches will cause a fatal error instead of a deprecation notice. + + + In case the return type cannot be declared for an overriding method due to - PHP cross-version compatibility concerns, - a #[\ReturnTypeWillChange] attribute can be added to silence - the deprecation notice. + PHP cross-version compatibility concerns, or the overriding method declares + an incompatible return type, a #[\ReturnTypeWillChange] attribute + can be added to silence the deprecation notice. - The ReturnTypeWillChange attribute suppresses - deprecation warnings during the tentative return type phase only. - 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. + When overriding methods defined in user-defined classes, return types are checked + strictly. A fatal error is emitted on mismatch, even if the overriding method + is marked with the attribute. - + + The ReturnTypeWillChange attribute suppresses deprecation + warnings only during the tentative return type phase. + After strict type checking is enforced, the attribute will stop working, + and a mismatch in an overriding method signature of an internal class + will cause a fatal error. + +
From c63c2f7fd3ef9fbefd7760c1576105be9c185247 Mon Sep 17 00:00:00 2001 From: Mikhail Alferov Date: Mon, 15 Jun 2026 15:48:47 +0300 Subject: [PATCH 2/8] hastentativereturntype.xml Add a link to the tentative phase desc --- .../reflectionfunctionabstract/hastentativereturntype.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/reflection/reflectionfunctionabstract/hastentativereturntype.xml b/reference/reflection/reflectionfunctionabstract/hastentativereturntype.xml index 01cbc5e6fe57..4dcb488d9960 100644 --- a/reference/reflection/reflectionfunctionabstract/hastentativereturntype.xml +++ b/reference/reflection/reflectionfunctionabstract/hastentativereturntype.xml @@ -12,7 +12,7 @@ - Returns whether the function has a tentative return type. + Returns whether the function has a tentative return type. From 49f7874a8b6b8676e5905e9dcceb05353246ffb2 Mon Sep 17 00:00:00 2001 From: Mikhail Alferov Date: Mon, 15 Jun 2026 15:49:35 +0300 Subject: [PATCH 3/8] gettentativereturntype.xml Add a link to the tentative phase desc --- .../reflectionfunctionabstract/gettentativereturntype.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/reflection/reflectionfunctionabstract/gettentativereturntype.xml b/reference/reflection/reflectionfunctionabstract/gettentativereturntype.xml index 850b2ed6477d..f48b38c8f3b7 100644 --- a/reference/reflection/reflectionfunctionabstract/gettentativereturntype.xml +++ b/reference/reflection/reflectionfunctionabstract/gettentativereturntype.xml @@ -12,7 +12,7 @@ - Returns the tentative return type associated with the function. + Returns the tentative return type associated with the function. From 16a1cfcf9ff785af1b294ce04ff6b8b9c95637fa Mon Sep 17 00:00:00 2001 From: Mikhail Alferov Date: Mon, 15 Jun 2026 15:50:05 +0300 Subject: [PATCH 4/8] hastentativereturntype.xml Amend the link text --- .../reflectionfunctionabstract/hastentativereturntype.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/reflection/reflectionfunctionabstract/hastentativereturntype.xml b/reference/reflection/reflectionfunctionabstract/hastentativereturntype.xml index 4dcb488d9960..2ef1cf0ba35e 100644 --- a/reference/reflection/reflectionfunctionabstract/hastentativereturntype.xml +++ b/reference/reflection/reflectionfunctionabstract/hastentativereturntype.xml @@ -12,7 +12,7 @@ - Returns whether the function has a tentative return type. + Returns whether the function has a tentative return type. From 0038708af310d39e6d6d01e720415ce39f6f2fad Mon Sep 17 00:00:00 2001 From: Mikhail Alferov Date: Mon, 15 Jun 2026 15:53:31 +0300 Subject: [PATCH 5/8] Update gettentativereturntype.xml Fix attr --- .../reflectionfunctionabstract/gettentativereturntype.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/reflection/reflectionfunctionabstract/gettentativereturntype.xml b/reference/reflection/reflectionfunctionabstract/gettentativereturntype.xml index f48b38c8f3b7..9f529576b7a9 100644 --- a/reference/reflection/reflectionfunctionabstract/gettentativereturntype.xml +++ b/reference/reflection/reflectionfunctionabstract/gettentativereturntype.xml @@ -12,7 +12,7 @@ - Returns the tentative return type associated with the function. + Returns the tentative return type associated with the function. From b520b53f5f1bcaa1aeedb5724b59f31c6573f06e Mon Sep 17 00:00:00 2001 From: Mikhail Alferov Date: Mon, 15 Jun 2026 15:53:39 +0300 Subject: [PATCH 6/8] Update hastentativereturntype.xml Fix attr --- .../reflectionfunctionabstract/hastentativereturntype.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/reflection/reflectionfunctionabstract/hastentativereturntype.xml b/reference/reflection/reflectionfunctionabstract/hastentativereturntype.xml index 2ef1cf0ba35e..8282d9453869 100644 --- a/reference/reflection/reflectionfunctionabstract/hastentativereturntype.xml +++ b/reference/reflection/reflectionfunctionabstract/hastentativereturntype.xml @@ -12,7 +12,7 @@ - Returns whether the function has a tentative return type. + Returns whether the function has a tentative return type. From 5bd097142d27338012cf0355770725483b8a3c99 Mon Sep 17 00:00:00 2001 From: Mikhail Alferov Date: Mon, 15 Jun 2026 15:58:37 +0300 Subject: [PATCH 7/8] =?UTF-8?q?Update=20hastentativereturntype.xml=20para?= =?UTF-8?q?=20=E2=86=92=20simpara?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../reflectionfunctionabstract/hastentativereturntype.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/reference/reflection/reflectionfunctionabstract/hastentativereturntype.xml b/reference/reflection/reflectionfunctionabstract/hastentativereturntype.xml index 8282d9453869..676403af9ce4 100644 --- a/reference/reflection/reflectionfunctionabstract/hastentativereturntype.xml +++ b/reference/reflection/reflectionfunctionabstract/hastentativereturntype.xml @@ -11,9 +11,9 @@ public boolReflectionFunctionAbstract::hasTentativeReturnType - + Returns whether the function has a tentative return type. - + From d129a5ba84f481b1402239e9179886ac01aac876 Mon Sep 17 00:00:00 2001 From: Mikhail Alferov Date: Mon, 15 Jun 2026 15:58:44 +0300 Subject: [PATCH 8/8] =?UTF-8?q?Update=20gettentativereturntype.xml=20para?= =?UTF-8?q?=20=E2=86=92=20simpara?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../reflectionfunctionabstract/gettentativereturntype.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/reference/reflection/reflectionfunctionabstract/gettentativereturntype.xml b/reference/reflection/reflectionfunctionabstract/gettentativereturntype.xml index 9f529576b7a9..68b7a9f58d34 100644 --- a/reference/reflection/reflectionfunctionabstract/gettentativereturntype.xml +++ b/reference/reflection/reflectionfunctionabstract/gettentativereturntype.xml @@ -11,9 +11,9 @@ public ReflectionTypenullReflectionFunctionAbstract::getTentativeReturnType - + Returns the tentative return type associated with the function. - +