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

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: https://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 > After discussing with Mate shortly one reason for adding $since from a PHP project POV is that we do show the $since information in the generated documentation output. Integrating with the work in progress to auto generate parts of the function docs based on the stub files, having the $since attribute on the stubs would allow to use this as the central information in code. Therefore we would reconsider and add the $since argument to the Deprecated class. I am still partly on the side on Rowan ( https://externals.io/message/123184#123206) that i don't find the arguments for this parameter very convincing but at least there is a use-case internally now that warrants adding it. > > [1]: > > https://doc.rust-lang.org/reference/attributes/diagnostics.html#the-deprecated-attribute > [2]: > > https://github.com/rust-lang/rfcs/blob/master/text/1270-deprecation.md#intended-use >