PHP 8.1: New #[ReturnTypeWillChange] attribute

#[\ReturnTypeWillChange] is a new attribute introduced in PHP 8.1, which signals that a mismatching tentative return type should not emit a deprecation notice.

PHP versions prior to 8.0 parses the attribute syntax as a code comment, and does not cause any syntax errors. Adding #[\ReturnTypeWillChange] attribute to a class method does not cause any issues, but omits the deprecation notice in PHP 8.1.

This is the first built-in attribute added to PHP.

class Foo implements ArrayAccess {
    #[\ReturnTypeWillChange]
    public function offsetGet(mixed $offset) {}
    // ...
}

---

When tentative return types are upgraded to standard return types (causing fatal errors if the signature mismatches are not fixed), this attribute will not any effect anymore.

Backwards Compatibility Impact

Unless there is a user-land class declared with name ReturnTypeWillChange in global namespace, this change should not cause any compatibility issues.

Related Changes

• PHP 8.1: Return types in PHP built-in class methods and deprecation notices
• PHP 8.1: Passing null to non-nullable internal function parameters is deprecated
• PHP 8.0: Fatal errors on incompatible method signatures
• PHP 8.0: Inheritance rules are not applied to private class methods
• PHP 8.0: Class magic method signatures are strictly enforced

---

RFC Discussion Implementation