UPGRADING

Author: DanielEScherzer

UPGRADING

@@ -53,6 +53,8 @@ PHP 8.5 UPGRADE NOTES
   . Applying #[\Attribute] to an abstract class, enum, interface, or trait triggers
     an error during compilation. Previously, the attribute could be added, but when
     ReflectionAttribute::newInstance() was called an error would be thrown.
+    The error can be delayed from compilation to runtime using the new
+    #[\DelayedTargetValidation] attribute.
 
 - DOM:
   . Cloning a DOMNamedNodeMap, DOMNodeList, Dom\NamedNodeMap, Dom\NodeList,
@@ -180,6 +182,11 @@ PHP 8.5 UPGRADE NOTES
     RFC: https://wiki.php.net/rfc/final_promotion
   . #[\Override] can now be applied to properties.
     RFC: https://wiki.php.net/rfc/override_properties
+  . The #[\DelayedTargetValidation] attribute can be used to suppress
+    compile-time errors from core (or extension) attributes that are used on
+    invalid targets. These errors are instead reported at runtime if and when
+    ReflectionAttribute::newInstance() is called.
+    RFC: https://wiki.php.net/rfc/delayedtargetvalidation_attribute
 
 - Curl:
   . Added support for share handles that are persisted across multiple PHP
@@ -506,6 +513,11 @@ PHP 8.5 UPGRADE NOTES
     hooks are final, and whether the property is virtual. This also affects
     the output of ReflectionClass::__toString() when a class contains hooked
     properties.
+  . ReflectionAttribute::newInstance() can now throw errors for internal
+    attributes if the attribute was applied on an invalid target and the
+    error was delayed from compile-time to runtime via the
+    #[\DelayedTargetValidation] attribute.
+    RFC: https://wiki.php.net/rfc/delayedtargetvalidation_attribute
 
 - Session:
   . session_start is stricter in regard to the option argument.
@@ -623,6 +635,12 @@ PHP 8.5 UPGRADE NOTES
 7. New Classes and Interfaces
 ========================================
 
+- Core:
+  . DelayedTargetValidation is an attribute that, when added, delays any errors
+    from *other* internal attributes about being applied to invalid targets from
+    compile-time to runtime.
+    RFC: https://wiki.php.net/rfc/delayedtargetvalidation_attribute
+
 - Curl:
   . CurlSharePersistentHandle representing a share handle that is persisted
     across multiple PHP requests.

UPGRADING.INTERNALS

@@ -28,6 +28,18 @@ PHP 8.5 INTERNALS UPGRADE NOTES
     extra layer of indirection can be removed. In other cases a zval can
     be heap-allocated and stored in the pointer as a minimal change to keep
     compatibility.
+  . The `target` parameter for validator callbacks for internal attributes
+    can now include in the bitmask the new flags
+    ZEND_ATTRIBUTE_NO_TARGET_VALIDATION and
+    ZEND_ATTRIBUTE_DELAYED_TARGET_VALIDATION. The first indicates that, if the
+    attribute is being applied to an invalid target, no error should be thrown
+    at compile time. The second indicates that validation is being performed
+    at runtime and that if an attribute is being applied to an invalid target,
+    a catchable error should be thrown. Target validation is different from
+    the actual functionality of the attribute; e.g. the #[\Override] attribute
+    will trigger an error if the function does not override a method from the
+    parent class or from an interface; that error does not get delayed.
+    RFC: https://wiki.php.net/rfc/delayedtargetvalidation_attribute
 
 - Hash
   . Hash functions now use proper hash_spec_result enum for return values