====== PHP RFC: #[\Deprecated] for traits ======
  * Version: 0.1
  * Date: 2025-07-05
  * Author: Daniel Scherzer, daniel.e.scherzer@gmail.com
  * Status: Under discussion
  * Implementation: https://github.com/php/php-src/pull/19045

===== Introduction =====

The <php>#[\Deprecated]</php> attribute was introduced in PHP 8.4 ([[rfc:deprecated_attribute]]) and could be used to emit deprecation warnings when calling a function (or class method), or when accessing a class constant (or enum case). Starting in 8.5, deprecation warnings could also be emitted when accessing a global constant ([[rfc:attributes-on-constants]]). This RFC proposes to add support for emitting deprecation warnings when a trait gets <php>use</php>d.

<PHP>
<?php

#[\Deprecated]
trait DemoTrait {}

class DemoClass {
	use DemoTrait;
}

// Reports:
// Deprecated: Trait DemoTrait used by DemoClass is deprecated in %s on line %d
?>
</PHP>

===== Proposal =====
The <php>#[\Deprecated]</php> attribute will be allowed on traits. Since <php>Attribute::TARGET_CLASS</php> includes traits as well as classes, interfaces, and enums, a validator will be used to ensure that when applied to a "class" (zend_class_entry), it must correspond to a trait.

When the traits that a class uses are loaded, any deprecated traits emit a deprecation message; these can be converted to an exception via a user error handler, and an uncaught exception will be treated the same as trying to use a non-trait as a trait in terms of registration behavior.

Traits only emit deprecation warnings when //directly// <php>use</php>d, the children of a class using a deprecated trait do not emit any extra errors unless they also use the trait directly.

==== Examples ====

Simple example:
<PHP>
<?php

#[\Deprecated]
trait DemoTrait {}

class DemoClass {
	use DemoTrait;
}

// Reports:
// Deprecated: Trait DemoTrait used by DemoClass is deprecated in %s on line %d
?>
</PHP>

With an exception:
<PHP>
<?php

function my_error_handler(int $errno, string $errstr, ?string $errfile = null, ?int $errline = null) {
	throw new \ErrorException($errstr, 0, $errno, $errfile, $errline);
}

set_error_handler('my_error_handler');

#[\Deprecated]
trait DemoTrait {}

class DemoClass {
	use DemoTrait;
}

// Reports:
// Fatal error: Uncaught ErrorException: Trait DemoTrait used by DemoClass is deprecated in %s:%d

?>
</PHP>

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

===== Proposed PHP Version(s) =====
Next PHP (8.5)

===== RFC Impact =====
==== To the Ecosystem ====
IDEs and static analyzers will likely want to update to surface deprecation messages when a trait is used without waiting for PHP to emit the errors.

==== To Existing Extensions ====
PHP core and the bundled extensions do not provide any traits, so there is no impact there.

==== To SAPIs ====
No impact other than deprecations being emitted when a deprecated trait is used.

===== Open Issues =====
Make sure there are no open issues when the vote starts!

===== Future Scope =====
Other places that <php>#[\Deprecated]</php> could eventually be supported include

  * extending a class
  * implementing an interface
  * overriding a method
  * accessing a property

But the support for deprecating the use of a trait is pretty straightforward and there isn't room for future improvements within the context of deprecating traits.


===== Voting Choices =====
<doodle title="Add support for #[\Deprecated] on traits?" voteType="single" closed="true" closeon="2025-01-01T15:30:00Z">
   * Yes
   * No
</doodle>

===== Patches and Tests =====
https://github.com/php/php-src/pull/19045

===== Implementation =====
After the RFC is implemented, this section should contain:
  - the version(s) it was merged into
  - a link to the git commit(s)
  - a link to the PHP manual entry for the feature

===== References =====

  * [[rfc:deprecated_attribute]]
  * [[rfc:attributes-on-constants]]

===== Rejected Features =====
Keep this updated with features that were discussed on the mail lists.

===== Changelog =====
If there are major changes to the initial proposal, please include a short summary with a date or a link to the mailing list announcement here, as not everyone has access to the wikis' version history.