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

Sent from my iPhone > On 25 Apr 2024, at 16:26, Rowan Tommins [IMSoP] <imsop.php@rwec.co.uk> wrote: > > On 24 April 2024 18:18:28 BST, Jorg Sowa <jorg.sowa@gmail.com> wrote: >> What about setting this parameter vaguely as the boolean we can pass? >> ... >> #[Deprecated(since: $packageVersion > 5.5)] >> #[Deprecated(since: PHP_VERSION_ID > 80100)] >> #[Deprecated(since: date("Y-m-d") > "2024-01-21")] > > > Even if these expressions were legal, as far as I know, standard reflection doesn't give > any access to the source code or AST of how the attribute was written, so this would just end up > with a meaningless "$since = true", and some source code that might as well be a comment. > > To be honest, I'm not really sure what I'd do with the information in a > "since" field even if it was there. If you were running PHP 7.4, what difference would it > make to know that create_function was deprecated in 7.2, rather than in 7.1 or 7.3? The two relevant > facts are when the suggested replacement was introduced (in case you need to support multiple > versions); and what is the soonest that the deprecated feature will be removed. The second in > particular is something I would like every deprecation message to include, rather than the vague > "may be removed in a future version". > > I found this discussion of "since" in Rust's implementation, but don't find > the arguments in favour particularly compelling: > https://github.com/rust-lang/rfcs/pull/1270#issuecomment-138043714 > > > Of interest, that discussion also linked to a related feature in Java, which could perhaps be > added to a list in the RFC alongside the Rust and JetBrains ones already mentioned: > https://openjdk.org/jeps/277 > > It's interesting to note, for instance, that both Java and Rust designers considered a > specific "replacement" field, but decided that it was unlikely to be useful in practice. > The Java proposal states this nicely: > >> In practice, there is never a drop-in replacement API for >> any deprecated API; there are always tradeoffs and >> design considerations, or choices to be made among >> several possible replacements. All of these topics require >> discussion and are thus better suited for textual >> documentation. > > The JetBrains attribute *does* include a "replacement" argument, but it's > heavily tied into a specific use case: it contains a template used for code transformation in the > IDE. Both it and "since" are explicitly marked "applicable only for PhpStorm > stubs". > > Regards, > Rowan Tommins > [IMSoP] > I think it's worth pointing out that phpdoc has had a @deprecated [version] [description] attribute for a long time - since is, IMO a different name for "version" and indicates the version that element was deprecated. If you're on X.y and it says it was deprecated in X.w you know you don't need to worry about it being removed until at least Y.a. Also, phpdoc *also* has a separate @since attribute, which documents the *introduction or modification* of an element. I think suggestions of a "Since" attribute "beside" the deprecated attribute defeat the purpose of it being an attribute, on top of being confusing when compared to existing phpdoc attributes. #[Deprecated, Since(1.9)] to me, means "currently deprecated; introduced (or significantly changed) in 1.9" To mean what you're suggesting it would need to be #[Deprecated, Since(1.9, 'Deprecated in favour of foo...')] which is just needless duplication. For those who don't see the point of since, I think the obvious answer is: documentation. Rather than needing a separate docblock to detail the deprecation, it can be all in one, just as parameter types and return types are. This reduces duplication, and reduces possibility of mismatched values. If you wanted it to be clearer I'd suggest maybe rename "since" to "version", but that's more to give a hint at intended use than anything.