This is an old revision of the document!
PHP RFC: #[Deprecated] Attribute
- Version: 1.1
- Date: 2020-05-06
- Author: Benjamin Ebelei
- Status: Under Discussion
- First Published at: http://wiki.php.net/rfc/deprecated_attribute
Introduction
With the Attributes RFC accepted for PHP 8, this is a first proposal for an internal attribute hooking into the engine.
It also serves as a good prototype and first step, as usually all languages with attributes also have a Deprecated attribute in their language core.
Proposal
Developers can put an attribute #[Deprecated] on the following elements:
- Functions
- Methods
It is not possible to target classes, constants, properties or arguments at the moment. This might be added in other RFCs later.
Using attribute will add “ZEND_ACC_DEPERACTED” function flag to the op_array, which will automatically (with only small changes to the VM) lead to a deprecation warning already, since this functionality is present for internal functions already. This attribute exposes a this deprecation feature for functions to userland and close a gap between internal and userland 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.
Runtime Effects
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 PHPs current deprecation model is based on runtime warnings, the existing concept is extended instead of inventing another approach.
Changing deprecation warnings from runtime to a different approach falls out of the scope of this RFC.
Backward Incompatible Changes
A class with the name “Deprecated” is introduced into the global namespace.
Proposed PHP Version(s)
8.1 for function/method deprecations
RFC Impact
To SAPIs
None
To Existing Extensions
None
To Opcache
None
New Constants
None
php.ini Defaults
None
Open Issues
A few things tracked in https://github.com/php/php-src/pull/6521
Proposed Voting Choices
Accept #[Deprecated] attribute into core?
Patches and Tests
https://github.com/php/php-src/pull/6521
No implementation for deprecated class constants, properties and parameters yet.