Newsgroups: php.internals Path: news.php.net Xref: news.php.net php.internals:123207 X-Original-To: internals@lists.php.net Delivered-To: internals@lists.php.net Received: from php-smtp4.php.net (php-smtp4.php.net [45.112.84.5]) by qa.php.net (Postfix) with ESMTPS id 0080B1A009C for ; Thu, 25 Apr 2024 07:40:53 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=php.net; s=mail; t=1714030893; bh=M5SVeYjPQUCX1mUAleY5dDmwXpbPAIeb0kjeOHC4gPQ=; h=From:Subject:Date:References:In-Reply-To:To:From; b=SzafaTTXtNSZW/mdW5dl0kcC5sdtL3IusKACBXliVLeEmsp7hRnqMsK4p3od5eoVs Jzbexs9/e12UfP18hhkyMQ7Pvovqe7GB8Ps1XKcECoIF0NWu4/5d7XDlEwjJMjhwU7 s+PrmP67mG5aJwbcU3cQxSTlm7lNh6zJt1S0id+bfSkRP7TonUmdA9+InW8NdIkG+M fkGYm3n20nfvR5F7tpaxsWIfwkg9edILkhRRoHgLqpr+yFbvAnKBori5wSDVaChAVH c7i/gSIxGyVSdMdHDiMRTDvmJdcs4dB9ZdHd0zj5/Xh5bfoYkhw0Li98BFTFwCzzcW wWoRd6yoiZilQ== Received: from php-smtp4.php.net (localhost [127.0.0.1]) by php-smtp4.php.net (Postfix) with ESMTP id 90AE81805D8 for ; Thu, 25 Apr 2024 07:41:32 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 4.0.0 (2022-12-13) on php-smtp4.php.net X-Spam-Level: X-Spam-Status: No, score=0.8 required=5.0 tests=BAYES_50,DMARC_MISSING, HTML_MESSAGE,MIME_QP_LONG_LINE,SPF_HELO_NONE,SPF_PASS, T_SCC_BODY_TEXT_LINE autolearn=no autolearn_force=no version=4.0.0 X-Spam-Virus: No X-Envelope-From: Received: from mail1.25mail.st (mail1.25mail.st [206.123.115.54]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by php-smtp4.php.net (Postfix) with ESMTPS for ; Thu, 25 Apr 2024 07:41:32 +0000 (UTC) Received: from smtpclient.apple (unknown [1.125.175.75]) by mail1.25mail.st (Postfix) with ESMTPSA id D64AB605DE for ; Thu, 25 Apr 2024 07:40:46 +0000 (UTC) Content-Type: multipart/alternative; boundary=Apple-Mail-32EB5083-ACB8-4864-B4F5-FF1B99B166DF Content-Transfer-Encoding: 7bit Precedence: bulk list-help: list-post: List-Id: internals.lists.php.net Mime-Version: 1.0 (1.0) Subject: Re: [PHP-DEV] [RFC] [Discussion] #[\Deprecated] attribute again v1.3 Date: Thu, 25 Apr 2024 17:10:33 +0930 Message-ID: References: <5814C522-CD23-4194-A344-1B57CC0A2511@rwec.co.uk> In-Reply-To: <5814C522-CD23-4194-A344-1B57CC0A2511@rwec.co.uk> To: internals@lists.php.net X-Mailer: iPhone Mail (21E236) From: php-lists@koalephant.com (Stephen Reay) --Apple-Mail-32EB5083-ACB8-4864-B4F5-FF1B99B166DF Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Sent from my iPhone > On 25 Apr 2024, at 16:26, Rowan Tommins [IMSoP] wro= te: >=20 > =EF=BB=BFOn 24 April 2024 18:18:28 BST, Jorg Sowa wr= ote: >> 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")] >=20 >=20 > Even if these expressions were legal, as far as I know, standard reflectio= n 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 =3D true", an= d some source code that might as well be a comment. >=20 > To be honest, I'm not really sure what I'd do with the information in a "s= ince" field even if it was there. If you were running PHP 7.4, what differen= ce would it make to know that create_function was deprecated in 7.2, rather t= han 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 part= icular is something I would like every deprecation message to include, rathe= r than the vague "may be removed in a future version". >=20 > I found this discussion of "since" in Rust's implementation, but don't fin= d the arguments in favour particularly compelling: https://github.com/rust-l= ang/rfcs/pull/1270#issuecomment-138043714 >=20 >=20 > Of interest, that discussion also linked to a related feature in Java, whi= ch could perhaps be added to a list in the RFC alongside the Rust and JetBra= ins ones already mentioned: https://openjdk.org/jeps/277 >=20 > It's interesting to note, for instance, that both Java and Rust designers c= onsidered a specific "replacement" field, but decided that it was unlikely t= o be useful in practice. The Java proposal states this nicely: >=20 >> 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. >=20 > The JetBrains attribute *does* include a "replacement" argument, but it's h= eavily tied into a specific use case: it contains a template used for code t= ransformation in the IDE. Both it and "since" are explicitly marked "applica= ble only for PhpStorm stubs". >=20 > Regards, > Rowan Tommins > [IMSoP] >=20 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 a= bout it being removed until at least Y.a. Also, phpdoc *also* has a separate @since attribute, which documents the *in= troduction 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=20 #[Deprecated, Since(1.9, 'Deprecated in favour of foo...')] which is just ne= edless duplication.=20 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 deprec= ation, it can be all in one, just as parameter types and return types are. T= his 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.=20 --Apple-Mail-32EB5083-ACB8-4864-B4F5-FF1B99B166DF Content-Type: text/html; charset=utf-8 Content-Transfer-Encoding: quoted-printable
=
Sent from my iPhone

On 25 Apr 2024, at 16:26, Rowan Tommins [IMSoP] <imsop.php@r= wec.co.uk> wrote:

=EF=BB=BFOn 24 April 2024 18:18:28 BST, Jorg Sowa <jo= rg.sowa@gmail.com> wrote:
What a= bout 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 l= egal, as far as I know, standard reflection doesn't give any access to the s= ource code or AST of how the attribute was written, so this would just end u= p with a meaningless "$since =3D true", and some source code that might as w= ell be a comment.

To be honest, I'm not re= ally 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 t= hat create_function was deprecated in 7.2, rather than in 7.1 or 7.3? The tw= o relevant facts are when the suggested replacement was introduced (in case y= ou need to support multiple versions); and what is the soonest that the depr= ecated feature will be removed. The second in particular is something I woul= d like every deprecation message to include, rather than the vague "may be r= emoved in a future version".

I found this d= iscussion of "since" in Rust's implementation, but don't find the arguments i= n favour particularly compelling: https://github.com/rust-lang/rfcs/pull/127= 0#issuecomment-138043714


O= f interest, that discussion also linked to a related feature in Java, which c= ould perhaps be added to a list in the RFC alongside the Rust and JetBrains o= nes already mentioned: https://openjdk.org/jeps/277
<= br>It's interesting to note, for instance, that both Java and Rust des= igners considered a specific "replacement" field, but decided that it was un= likely 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 choi= ces to be made among
= several possible replacements. All of these topics require
discussion and are thus better suited f= or textual
documentat= ion.

The JetBrains attribute *= does* include a "replacement" argument, but it's heavily tied into a specifi= c use case: it contains a template used for code transformation in the IDE. B= oth 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 f= or "version" and indicates the version that element was deprecated. If you'r= e on X.y and it says it was deprecated in X.w you know you don't need to wor= ry about it being removed until at least Y.a.

Also,= phpdoc *also* has a separate @since attribute, which documents the *introdu= ction or modification* of an element.

I think sugge= stions of a "Since" attribute "beside" the deprecated attribute defeat the p= urpose of it being an attribute, on top of being confusing when compared to e= xisting phpdoc attributes.

#[Deprecated, Since(1.9)= ] to me, means "currently deprecated; introduced (or significantly changed) i= n 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: documentatio= n. 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 d= uplication, and reduces possibility of mismatched values.
If you wanted it to be clearer I'd suggest maybe rename "si= nce" to "version", but that's more to give a hint at intended use than anyth= ing. 

= --Apple-Mail-32EB5083-ACB8-4864-B4F5-FF1B99B166DF--