PHP RFC: #[\Deprecated] Attribute

• Version: 1.3-dev
• Date: 2024-04-15
• Author: Benjamin Eberlei, Tim Düsterhus
• Status: Under Discussion
• First Published at: http://wiki.php.net/rfc/deprecated_attribute

PHP’s internal functions can be marked as deprecated, making this information available to Reflection and emitting deprecation errors, but there is equivalent functionality for functions defined in userland.

While the functionality can be emulated using trigger_error() to emit a E_USER_DEPRECATED error when calling a method and either parsing a doc comment for the @deprecated annotation or attaching a custom-defined attribute and reading either one with Reflection, it requires special handling for internal and userland functions respectively: ReflectionFunctionAbstract::isDeprecated() always returns false for userland functions.

Developers can put an attribute #[Deprecated] on the following elements (targets):

• Functions
• Methods

For now is not possible to target classes, constants, properties or arguments with this attribute, and it is left for future RFC(s) to address this.

When this attribute is present, during the compile step the existing “ZEND_ACC_DEPERACTED” function flag is added to the op_array (userland function), which will lead to a deprecation warning when the function is called at runtime, with only minimal changes in the VM.

The ZEND_ACC_DEPRECATED flag and behavior is present for internal functions already. The presence of a Deprecated attribute allows to expose this feature to userland functions/methods and closes a capability gap between internal and userland functions.

For userland functions the E_USER_DEPRECATED level is used, instead of the E_DEPRECATED that is raised for internal functions.

<?php
 
use Deprecated;
 
#[Deprecated]
function test() {}
// Deprecated: Function test() is deprecated
 
#[Deprecated("use test3() instead")]
function test2() {}
// Deprecated: Function test2() is deprecated, use test3() instead
 
class Foo {
    #[Deprecated]
    public function test() {}
    // Deprecated: Method Foo::test() is deprecated in %s
}

The deprecated class is final and cannot be extended. The reason for this is that the engine internally cannot autoload attributes, so checking for a subclass that extends the Deprecated class is not technically possible. Marking the class as final prevents that users extend the class and expect their children exhibit the same behavior.

Using the deprecated attribute on a function or method behaves the same as putting a call to trigger_error using E_DEPRECATED level as the first line of the same function/method.

While other languages have deprecation attributes, they usually generate compile time warnings instead of runtime warnings. However as PHP's current deprecation model is based on runtime warnings, the Deprecation attribute builds on that existing model. The benefit of a declarative approach with an attribute over the current approach with a function call to trigger_error is that is that it abstracts the implementation details of how deprecations work, with the potential for better integration with future changes to the runtime warning stack of PHP.

This feature adds a small bitmask check in the VM for every function call.

Changes to the runtime warning stack of PHP are out of the scope of this RFC.

Deprecated can no longer be used as a class name in the global namespace. A GitHub search for “class Override ” language:php symbol:override revealed a total of 318 matches in source code. Many of them appear within a comment. The actual class definition all appear to be defined within a namespace.

Next minor (PHP 8.4).

None.

None.

None.

None.

None.

A few things tracked in https://github.com/php/php-src/pull/11293

• Allowing #[\Deprecated] on classes or other targets of attributes
• Adding further metadata to the Deprecated attribute beyond a custom message, such as hints for replacements that IDEs could use.

https://github.com/php/php-src/pull/11293

n/a

• Implementation: https://github.com/php/php-src/pull/11293
• Early Mailing List Discussion: https://externals.io/message/112554#112554

n/a