PHP: rfc:deprecated_attribute

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== PHP RFC: #[\Deprecated] Attribute ======

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

===== Introduction =====

PHP’s internal functions can be marked as deprecated, making this information available to Reflection and emitting deprecation errors (<php>E_DEPRECATED</php>), but there is no //equivalent// functionality for functions defined in userland.

While the functionality can be //emulated// using <php>trigger_error()</php> to emit a <php>E_USER_DEPRECATED</php> error when calling a deprecated function, combined with either parsing a doc comment for the <php>/** @deprecated */</php> annotation or attaching a custom-defined attribute and reading it with Reflection, it requires special handling depending on whether the function in question is an internal or a userland function. <php>ReflectionFunctionAbstract::isDeprecated()</php> always returns <php>false</php> for userland functions - and doc comments / custom attributes are unavailable for internal functions.

===== Proposal =====

A new attribute <php>#[\Deprecated]</php> shall be added:


<PHP>
#[Attribute(Attribute::TARGET_METHOD|Attribute::TARGET_FUNCTION)]
final class Deprecated
{
    public readonly ?string $message;

    public function __construct(?string $message = null) {}
}
</PHP>

Applying this attribute to a userland function or method will add the internal ''ZEND_ACC_DEPRECATED'' flag to the function, resulting in a behavior that is consistent with the existing deprecation functionality for internal functions. This means:

  * <php>ReflectionFunctionAbstract::isDeprecated()</php> will return <php>true</php>.
  * Calling the function will emit a <php>E_USER_DEPRECATED</php> error (internal functions emit <php>E_DEPRECATED</php>, but this error code is reserved for internal functions).

The <php>$message</php> given within the attribute definition will be included in the error message when calling the function. It goes without saying that it will also be available to static analysis tools, just like the parameters of any other attribute.

==== Examples ====

<PHP>
<?php

#[\Deprecated]
function test() {
}

#[\Deprecated("use test() instead")]
function test2() {
}

class Clazz {
    #[\Deprecated]
    function test() {
    }

    #[\Deprecated("use test() instead")]
    function test2() {
    }
}

test(); // Deprecated: Function test() is deprecated in test.php on line 21
test2(); // Deprecated: Function test2() is deprecated, use test() instead in test.php on line 22
call_user_func("test"); // Deprecated: Function test() is deprecated in test.php on line 23

$cls = new Clazz();
$cls->test(); // Deprecated: Method Clazz::test() is deprecated in test.php on line 26
$cls->test2(); // Deprecated: Method Clazz::test2() is deprecated, use test() instead in test.php on line 27

call_user_func([$cls, "test"]); // Deprecated: Method Clazz::test() is deprecated in test.php on line 29

?>
</PHP>

<PHP>
<?php

#[\Deprecated]
function test() {
}

$r = new ReflectionFunction('test');

var_dump($r->isDeprecated()); // bool(true)

?>
</PHP>

<PHP>
<?php

#[\Deprecated]
function test1() {
}

#[\Deprecated()]
function test2() {
}

#[\Deprecated("use test() instead")]
function test3() {
}

$reflection = new ReflectionFunction('test1');
var_dump($reflection->getAttributes()[0]->newInstance());
/*
object(Deprecated)#3 (1) {
  ["message"]=>
  NULL
}
*/

$reflection = new ReflectionFunction('test2');
var_dump($reflection->getAttributes()[0]->newInstance());
/*
object(Deprecated)#2 (1) {
  ["message"]=>
  NULL
}
*/

$reflection = new ReflectionFunction('test3');
var_dump($reflection->getAttributes()[0]->newInstance());
/*
object(Deprecated)#1 (1) {
  ["message"]=>
  string(18) "use test() instead"
}
*/

?>
</PHP>

Further examples are given by [[https://github.com/php/php-src/pull/11293/files?file-filters%5B%5D=.phpt&show-viewed-files=true|the newly added tests within the PR for this RFC]].

===== Backward Incompatible Changes =====

<php>Deprecated</php> can no longer be used as a class name in the global namespace. A GitHub search for ''"class Deprecated " language:php symbol:deprecated'' revealed a total of 173 matches in source code. The vast majority of them appear to be defined within a namespace.

===== Proposed PHP Version(s) =====

Next minor (PHP 8.4).

===== RFC Impact =====

==== To SAPIs ====

None.

==== To Existing Extensions ====

The <php>#[\Deprecated]</php> attribute will also be available to internal functions. Within a stub file it will have the same effect as adding a <php>/** @deprecated */</php> doc comment. The attribute will //not// be automatically applied to existing functions having the doc comment, but extension authors are encouraged to apply the attribute for consistency reasons.

For extensions that are part of php-src the attribute will replace the existing doc comment as part of this RFC.

==== To Opcache ====

None.

==== New Constants ====

None.

==== php.ini Defaults ====

None.

===== Open Issues =====

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

===== Future Scope =====

  * Supporting <php>#[\Deprecated]</php> on classes or other targets of attributes.
  * Adding further metadata to the <php>#[\Deprecated]</php> attribute beyond a custom message (e.g. hints for replacements that IDEs could use).

===== Proposed Voting Choices =====

<doodle title="Implement the #[\Deprecated] attribute as described?" auth="timwolla" voteType="single" closed="false" closeon="2022-01-01T00:00:00Z">
   * Yes
   * No
</doodle>

===== Patches and Tests =====

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

===== Implementation =====

n/a

===== References =====

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

===== Rejected Features =====

  * Changes to the runtime behavior of deprecated functions are out of scope of this RFC (i.e. not emitting the <php>E_DEPRECATED</php> error for internal functions).
  * Making the <php>Deprecated</php> attribute class non-final: Child classes of attributes are not understood by the engine for technical reasons and the semantics of a child class would be less clear for static analysis tools.
Page Tools
