From c10586c4abd4f899ec993dede80dca406a6aa6aa Mon Sep 17 00:00:00 2001
From: Jordi Kroon <jkroon@onyourmarks.agency>
Date: Thu, 2 Apr 2026 20:29:05 +0200
Subject: [PATCH 1/3] add DelayedTargetValidation attribute documentation

---
 language/predefined/attributes.xml            |   5 +-
 .../attributes/delayedtargetvalidation.xml    | 132 ++++++++++++++++++
 language/predefined/versions.xml              |   1 +
 3 files changed, 136 insertions(+), 2 deletions(-)
 create mode 100644 language/predefined/attributes/delayedtargetvalidation.xml

diff --git a/language/predefined/attributes.xml b/language/predefined/attributes.xml
index 3e97de7913c9..c8da10e32d2e 100644
--- a/language/predefined/attributes.xml
+++ b/language/predefined/attributes.xml
@@ -3,13 +3,14 @@
  <title>Predefined Attributes</title>
 
  <partintro>
-  <para>
+  <simpara>
    PHP provides some predefined attributes that can be used.
-  </para>
+  </simpara>
  </partintro>
 
  &language.predefined.attributes.attribute;
  &language.predefined.attributes.allowdynamicproperties;
+ &language.predefined.attributes.delayedtargetvalidation;
  &language.predefined.attributes.deprecated;
  &language.predefined.attributes.nodiscard;
  &language.predefined.attributes.override;
diff --git a/language/predefined/attributes/delayedtargetvalidation.xml b/language/predefined/attributes/delayedtargetvalidation.xml
new file mode 100644
index 000000000000..4fa100a75f43
--- /dev/null
+++ b/language/predefined/attributes/delayedtargetvalidation.xml
@@ -0,0 +1,132 @@
+<?xml version="1.0" encoding="utf-8"?>
+<reference xml:id="class.delayedtargetvalidation" role="class" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
+ <title>The DelayedTargetValidation attribute</title>
+ <titleabbrev>DelayedTargetValidation</titleabbrev>
+
+ <partintro>
+
+  <section xml:id="delayedtargetvalidation.intro">
+   &reftitle.intro;
+   <simpara>
+    This attribute delays target validation errors for internal attributes
+    from compile time to runtime.
+   </simpara>
+   <simpara>
+    When applied to a declaration, any invalid usage of internal attributes
+    on the same target will not trigger a compile time error. Instead, the
+    validation is deferred and performed when the attribute is accessed via
+    the Reflection API.
+   </simpara>
+   <simpara>
+    This is primarily intended for forward compatibility, allowing code to
+    use attributes that may gain additional valid targets in future PHP
+    versions without breaking on older versions.
+   </simpara>
+  </section>
+
+  <section xml:id="delayedtargetvalidation.synopsis">
+   &reftitle.classsynopsis;
+
+   <classsynopsis class="class">
+    <ooclass>
+     <modifier role="attribute">#[\Attribute]</modifier>
+     <modifier>final</modifier>
+     <classname>DelayedTargetValidation</classname>
+    </ooclass>
+   </classsynopsis>
+
+  </section>
+
+  <section>
+   &reftitle.examples;
+
+   <example>
+    <title>Delaying validation of an invalid target</title>
+    <programlisting role="php"><![CDATA[
+<?php
+
+class Base {
+    protected function foo(): void {}
+}
+
+class Child extends Base {
+
+    #[\DelayedTargetValidation]
+    #[\Override]
+    public const NAME = 'child';
+
+    #[\Override]
+    protected function foo(): void {}
+}
+]]></programlisting>
+
+    <simpara>
+     On PHP versions where <classname>Override</classname> is not allowed on
+     class constants, this does not produce a compile time error.
+    </simpara>
+   </example>
+
+   <example>
+    <title>Validation occurs during reflection</title>
+    <programlisting role="php"><![CDATA[
+<?php
+
+$reflection = new ReflectionClassConstant(Child::class, 'NAME');
+
+foreach ($reflection->getAttributes() as $attribute) {
+    $attribute->newInstance(); // May throw if invalid
+}
+]]></programlisting>
+
+    <simpara>
+     When the attribute is instantiated via reflection, target validation is
+     performed and an error may be thrown if the attribute is used on an
+     unsupported target.
+    </simpara>
+   </example>
+
+  </section>
+
+  <section xml:id="delayedtargetvalidation.notes">
+   &reftitle.notes;
+   <simpara>
+    This attribute only affects target validation of internal attributes.
+   </simpara>
+   <simpara>
+    It does not suppress functional validation performed by those attributes.
+    For example, <classname>Override</classname> will still emit an error if a
+    method does not actually override a parent method.
+   </simpara>
+  </section>
+
+  <section xml:id="delayedtargetvalidation.seealso">
+   &reftitle.seealso;
+   <simplelist>
+    <member><link linkend="language.attributes">Attributes overview</link></member>
+    <member><link linkend="class.override">Override</link></member>
+   </simplelist>
+  </section>
+
+ </partintro>
+
+</reference>
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->
diff --git a/language/predefined/versions.xml b/language/predefined/versions.xml
index 3a821aaa8e37..0386fef4b1a2 100644
--- a/language/predefined/versions.xml
+++ b/language/predefined/versions.xml
@@ -181,6 +181,7 @@
  <function name="SensitiveParameterValue::getValue" from="PHP 8 &gt;= 8.2.0"/>
  <function name="Override" from="PHP 8 &gt;= 8.3.0"/>
  <function name="Override::__construct" from="PHP 8 &gt;= 8.3.0"/>
+ <function name="DelayedTargetValidation" from="PHP 8 &gt;= 8.5.0"/>
  <function name="Deprecated" from="PHP 8 &gt;= 8.4.0"/>
  <function name="Deprecated::__construct" from="PHP 8 &gt;= 8.4.0"/>
  <function name="NoDiscard" from="PHP 8 &gt;= 8.5.0"/>

From b6112892dc91b217cfff94194710fc0287548e0f Mon Sep 17 00:00:00 2001
From: Jordi Kroon <jkroon@onyourmarks.agency>
Date: Thu, 2 Apr 2026 21:58:15 +0200
Subject: [PATCH 2/3] clarify reflection example

---
 language/predefined/attributes/delayedtargetvalidation.xml | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/language/predefined/attributes/delayedtargetvalidation.xml b/language/predefined/attributes/delayedtargetvalidation.xml
index 4fa100a75f43..fcad07213809 100644
--- a/language/predefined/attributes/delayedtargetvalidation.xml
+++ b/language/predefined/attributes/delayedtargetvalidation.xml
@@ -79,9 +79,10 @@ foreach ($reflection->getAttributes() as $attribute) {
 ]]></programlisting>
 
     <simpara>
-     When the attribute is instantiated via reflection, target validation is
-     performed and an error may be thrown if the attribute is used on an
-     unsupported target.
+     When the attribute is instantiated via reflection using
+     <link linkend="reflectionattribute.newinstance">ReflectionAttribute::newInstance()</link>,
+     target validation is performed and an exception may be thrown if the attribute
+     is used on an unsupported target.
     </simpara>
    </example>
 

From 90c85dc8cf55ff078ecff8e0e2b2859de30a94a0 Mon Sep 17 00:00:00 2001
From: Jordi Kroon <jordi@jordikroon.nl>
Date: Mon, 6 Apr 2026 19:39:43 +0200
Subject: [PATCH 3/3] apply suggestions for DelayedTargetValidation

Co-authored-by: Louis-Arnaud <la.catoire@gmail.com>
---
 language/predefined/attributes/delayedtargetvalidation.xml | 4 ++--
 language/predefined/versions.xml                           | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/language/predefined/attributes/delayedtargetvalidation.xml b/language/predefined/attributes/delayedtargetvalidation.xml
index fcad07213809..13e3099900b7 100644
--- a/language/predefined/attributes/delayedtargetvalidation.xml
+++ b/language/predefined/attributes/delayedtargetvalidation.xml
@@ -9,7 +9,7 @@
    &reftitle.intro;
    <simpara>
     This attribute delays target validation errors for internal attributes
-    from compile time to runtime.
+    from compile time to when the attribute is instantiated via the Reflection API.
    </simpara>
    <simpara>
     When applied to a declaration, any invalid usage of internal attributes
@@ -37,7 +37,7 @@
 
   </section>
 
-  <section>
+  <section xml:id="delayedtargetvalidation.examples">
    &reftitle.examples;
 
    <example>
diff --git a/language/predefined/versions.xml b/language/predefined/versions.xml
index 0386fef4b1a2..93435c7a55ba 100644
--- a/language/predefined/versions.xml
+++ b/language/predefined/versions.xml
@@ -181,9 +181,9 @@
  <function name="SensitiveParameterValue::getValue" from="PHP 8 &gt;= 8.2.0"/>
  <function name="Override" from="PHP 8 &gt;= 8.3.0"/>
  <function name="Override::__construct" from="PHP 8 &gt;= 8.3.0"/>
- <function name="DelayedTargetValidation" from="PHP 8 &gt;= 8.5.0"/>
  <function name="Deprecated" from="PHP 8 &gt;= 8.4.0"/>
  <function name="Deprecated::__construct" from="PHP 8 &gt;= 8.4.0"/>
+ <function name="DelayedTargetValidation" from="PHP 8 &gt;= 8.5.0"/>
  <function name="NoDiscard" from="PHP 8 &gt;= 8.5.0"/>
  <function name="NoDiscard::__construct" from="PHP 8 &gt;= 8.5.0"/>
  <function name="__PHP_Incomplete_Class" from="PHP 4 &gt;=4.0.1, PHP 5, PHP 7, PHP 8"/>