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 @@ Predefined Attributes - + PHP provides some predefined attributes that can be used. - + &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..13e3099900b7 --- /dev/null +++ b/language/predefined/attributes/delayedtargetvalidation.xml @@ -0,0 +1,133 @@ + + + The DelayedTargetValidation attribute + DelayedTargetValidation + + + +
+ &reftitle.intro; + + This attribute delays target validation errors for internal attributes + from compile time to when the attribute is instantiated 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 accessed via + the Reflection API. + + + 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. + +
+ +
+ &reftitle.classsynopsis; + + + + #[\Attribute] + final + DelayedTargetValidation + + + +
+ +
+ &reftitle.examples; + + + Delaying validation of an invalid target + + + + On PHP versions where Override is not allowed on + class constants, this does not produce a compile time error. + + + + + Validation occurs during reflection + getAttributes() as $attribute) { + $attribute->newInstance(); // May throw if invalid +} +]]> + + + When the attribute is instantiated via reflection using + ReflectionAttribute::newInstance(), + target validation is performed and an exception may be thrown if the attribute + is used on an unsupported target. + + + +
+ +
+ &reftitle.notes; + + This attribute only affects target validation of internal attributes. + + + It does not suppress functional validation performed by those attributes. + For example, Override will still emit an error if a + method does not actually override a parent method. + +
+ +
+ &reftitle.seealso; + + Attributes overview + Override + +
+ +
+ +
+ diff --git a/language/predefined/versions.xml b/language/predefined/versions.xml index 3a821aaa8e37..93435c7a55ba 100644 --- a/language/predefined/versions.xml +++ b/language/predefined/versions.xml @@ -183,6 +183,7 @@ +