Skip to content

Document DelayedTargetValidation attribute (PHP 8.5) #5457

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jordikroon wants to merge 3 commits into
base: master
Choose a base branch
from
+137 −2
Open

Document DelayedTargetValidation attribute (PHP 8.5) #5457

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c10586c
add DelayedTargetValidation attribute documentation
jordikroon Apr 2, 2026
b611289
clarify reflection example
jordikroon Apr 2, 2026
90c85dc
apply suggestions for DelayedTargetValidation
jordikroon Apr 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions language/predefined/attributes.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
132 changes: 132 additions & 0 deletions language/predefined/attributes/delayedtargetvalidation.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Comment thread
jordikroon marked this conversation as resolved.
Outdated
</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.
Comment on lines +15 to +18
Copy link
Copy Markdown
Member

@lacatoire lacatoire Apr 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.
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 instantiated
via <link linkend="reflectionattribute.newinstance">ReflectionAttribute::newInstance()</link>.

Copy link
Copy Markdown
Member

@lacatoire lacatoire Apr 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ReflectionClass::getAttributes() alone does not trigger validation: the deferred check only fires on ReflectionAttribute::newInstance() (see Zend/zend_compile.c:7874-7930, where the error is stored on attr->validation_error and only rethrown by newInstance()).

</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>
Comment thread
jordikroon marked this conversation as resolved.
Outdated
&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]
Comment thread
jordikroon marked this conversation as resolved.
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
Comment thread
jordikroon marked this conversation as resolved.
Outdated
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>
Comment thread
jordikroon marked this conversation as resolved.
</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
-->
1 change: 1 addition & 0 deletions language/predefined/versions.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"/>
Comment thread
jordikroon marked this conversation as resolved.
Outdated
<function name="NoDiscard" from="PHP 8 &gt;= 8.5.0"/>
Expand Down