Re: [RFC] [Discussion] #[\Deprecated] attribute again v1.3

On Wed, Apr 24, 2024, at 4:01 AM, Benjamin Außenhofer wrote: > On Tue, Apr 23, 2024 at 7:27 PM Levi Morrison > <levi.morrison@datadoghq.com> wrote: >> On Tue, Apr 23, 2024 at 7:30 AM Benjamin Außenhofer <kontakt@beberlei.de> wrote: >> > >> > Hi internals, >> > >> > My PR for #[\Deprecated] attribute was in hibernation for a long while now and after >> > some off-list discussion a few weeks ago I have decided to revisit it and asked Tim to help me out >> > with the work. >> > >> > Tim has cleaned up the PR quite a bit and also worked in additional features such as >> > #[Deprecated] support in stub generation. >> > >> > While there are still some small todos, at this point we want to restart the >> > discussion about the RFC for inclusion in 8.4: >> > >> > RFC: https://wiki.php.net/rfc/deprecated_attribute >> > PR: https://github.com/php/php-src/pull/11293 >> > Old discussion: ÓG >> > ]cè³$":Á‘“u2https://externals.io/message/112554#112554 >> > >> > Let me know about your questions and feedback. >> > >> > greetings >> > Benjamin >> >> I skimmed through the previous discussion and didn't see anything >> about adding a since property. This is occasionally useful, >> at least >> in my limited usage of it in Rust. The names below are modelled after >> the names in [Rust's deprecated attribute][1], but "note" is the same >> as the proposed "message": >> >> ```php >> #[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_FUNCTION)] >> class Deprecated >> { >> public function __construct( >> public readonly ?string $note = null, >> public readonly ?string $since = null >> ) { >> } >> } >> >> #[Deprecated(since: "1.3", note: "this is not good, use good_pls_use")] >> function bad_dont_use() {} >> >> #[Deprecated("this wasn't meant to be public, use good_pls_use instead") >> function oops_dont_use() {} >> >> function good_pls_use() {} >> ``` >> >> In Rust, you get a message for each of ["since" and "note"][2]. In >> PHP, this might look something like: >> >> > Deprecated: Function bad_dont_use() is deprecated since 1.3, >> > this wasn't meant to be public, use good_pls_use instead in %s >> > on line %d > > This request is similar to Roman's question about a replacement > parameter elsewhere. We are unsure about these, because from an engine > POV they do not add value, and from a user messaging perspective they > could be put into the message with #[\Deprecated("since 1.3, this is > not good, use good_pls_use")]. > > The only reason this might make sense is to allow third party tooling > to work on this, but there are no conventions ala php-doc here in place > already. If tools need more infos, they could just introduce their own > attributes. example: > > #[\Deprecated, Since("1.3"), Replacement("good_pls_use()")]. > > It feels arbitrary if we add parameters that the engine does not use > and where no tooling conventions exist on how they are being used, so > we left them out for now. I support this attribute, but would also like to see it fleshed out more.. A since parameter or a separate attribute I'm flexible on and open to discussing; I don't have a strong preference right now. We should definitely see what other languages have found useful here beyond just Rust, which could give us a better idea of what is conventional/helpful. My other question is whether E_USER_DEPRECATED is still the right error to throw, rather than E_DEPRECATED. I'm not saying it isn't, just that I'm unsure and would like to dig into that a bit more. --Larry Garfield