delayedtargetvalidation.xml

<?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
-->