Request for Comments: Add a deprecated modifier for functions

• Version: 1.0
• Date: 2012-12-25
• Author: Yussuf Khalil dev@pp3345.de
• Status: Inactive
• First Published at: https://wiki.php.net/rfc/deprecated-modifier

This RFC proposes the addition of a “deprecated” modifier for methods and functions giving the ZEND_ACC_DEPRECATED flag to functions, thus throwing an E_DEPRECATED error when they are called.

It is common for large PHP frameworks to deprecate old functions and methods that are still in use (by plugins for example) when releasing new versions. Later, these functions will usually be completely removed. Native functions only need the ZEND_ACC_DEPRECATED flag and Zend will automatically throw an E_DEPRECATED error when they are called. However, a userspace function can only be deprecated by either adding the @deprecated tags to the doc comment or by throwing an E_USER_DEPRECATED error. Why does a userspace developer need to throw an error himself while a native function only needs a flag?

Simply deprecating a function by adding a deprecated modifier to the function declaration is cleaner, faster and more obvious for developers when looking at the function declaration.

Custom E_USER_DEPRECATED errors could rather be used for deprecating whole libraries or specific ways of calling a function.

Also, ReflectionFunction::isDeprecated() is currently useless for userspace functions which would be changed by adding this modifier.

deprecated function myFunction() {
    // ...
}
 
myFunction();

Deprecated: Function myFunction() is deprecated in ... on line 5

class MyClass {
    public deprecated static function myMethod() {
        // ...
    }
}
 
MyClass::myMethod();

Deprecated: Function MyClass::myMethod() is deprecated in ... on line 7

A pull request is available at https://github.com/php/php-src/pull/244.

This patch adds a T_DEPRECATED token and sets the ZEND_ACC_DEPRECATED flag for every function declaration preceded by this token. It properly checks for multiple deprecated modifiers or deprecated properties and throws an E_COMPILE_ERROR in these cases.

1. 2012-12-25 RFC created and published