Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
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
133 changes: 133 additions & 0 deletions language/predefined/attributes/delayedtargetvalidation.xml
Original file line number Diff line number Diff line change
@@ -0,0 +1,133 @@
<?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 when the attribute is instantiated via the Reflection API.
</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 xml:id="delayedtargetvalidation.examples">
&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 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>

</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
-->
1 change: 1 addition & 0 deletions language/predefined/versions.xml
Original file line number Diff line number Diff line change
Expand Up @@ -183,6 +183,7 @@
<function name="Override::__construct" from="PHP 8 &gt;= 8.3.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"/>
Expand Down