Re: #[Deprecated] Attribute

From: Date: Mon, 02 Jun 2025 00:25:40 +0000
Subject: Re: #[Deprecated] Attribute
References: 1 2 3 4 5 6 7  Groups: php.internals 
Request: Send a blank email to internals+get-127527@lists.php.net to get a copy of this message 
On 6/1/25 17:31, fennic log wrote:

I have needed this as well at work for a shared library and i'm sure many
library authors would use it too.
Current IDE's like jetbrains has support for #[Deprecated($reason,
$replacement)] which will throw warning in the IDE,
see their implementation here:
https://github.com/JetBrains/phpstorm-attributes?tab=readme-ov-file#deprecated

If this could be supported at a language level, package authors, frameworks
and internal company libraries would benefit from it.
I see no reason why anyone would be against the idea, other than pure chaos
evil.




I don't think the issue is that anyone is against the idea. I think the issue is that it's unclear what the behavior should be.

Following from Benjamin Außenhofer's post:


- Deprecated classes
  - mark the following elements deprecated:

    - constructor method (what if it doesnt have one?)
    - public static methods
    - public static properties
    - public constants

  - not public properties or methods, because the message is already

    generated on new DeprecatedClass

  - during generating the message see if its classed based and

    slightly change message to indicate its a class based deprecation



I hadn't gotten very far along in thinking about it. What led me to resurrect this old thread was this:

I wanted to mark a class a deprecated because I'll be removing it in the next major version of ramsey/uuid. When anyone tries to "use" the class, I'd like them to see a deprecation message.

"Use" is doing a lot of heavy-lifting here.

When I annotate the class with @deprecated, that helps in several ways:

* JetBrains IDEs show the class name with a strike-through line
* PHPStan and Psalm complain about its use
* PHP_CodeSniffer can be configured to complain about it
* Other tooling I might not be aware of does stuff

The goal is to make sure users are aware of the deprecation.

If we don't change to the language to support #[\Deprecated] at the class level, what is the common practice library authors should follow that will allow all the tooling (and PHP's deprecation messages) to make users aware?

* Add the attribute to the constructor?
* Add it to all public static properties, methods, constants?

If all the tooling will appropriately warn the user when the attribute is on the constructor, then I don't think there's a need to make a change to the language.

I guess I'll need to do a little investigation now to see how all the tools respond when using the attribute on various elements.

Cheers,
Ben



Attachment: [application/pgp-signature] OpenPGP digital signature OpenPGP_signature.asc

Thread (16 messages)

« previous php.internals (#127527) next »