On Tue, Apr 23, 2024 at 7:27 PM Levi Morrison <levi.morri...@datadoghq.com> wrote:
> On Tue, Apr 23, 2024 at 7:30 AM Benjamin Außenhofer <kont...@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 > 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. > [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 >
