Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:123198
Feedback-ID: i8414410d:Fastmail
User-Agent: Cyrus-JMAP/3.11.0-alpha0-386-g4cb8e397f9-fm-20240415.001-g4cb8e397
Precedence: bulk
MIME-Version: 1.0
Message-ID: <6a1628bd-ba1a-4f2b-9bd1-9594db9734cc@app.fastmail.com>
In-Reply-To: 
 <CAEPJduk97GYFQuy6AaZP5=vDmaxLOWZOQfxmzg0QV=PLAdk2Aw@mail.gmail.com>
References: 
 <CAEPJdumvJNQ+JZ3wkLP-Q2O0y57g=W_hHFkuvOKMVJqqraKCzw@mail.gmail.com>
 <CAAKU0uk6UYs_0sJr28gkmN_iwPcaF=z9Cr=dqOLTMHji7UNxHg@mail.gmail.com>
 <CAEPJduk97GYFQuy6AaZP5=vDmaxLOWZOQfxmzg0QV=PLAdk2Aw@mail.gmail.com>
Date: Wed, 24 Apr 2024 07:42:20 -0500
To: "php internals" <internals@lists.php.net>
Subject: Re: [PHP-DEV] [RFC] [Discussion] #[\Deprecated] attribute again v1.3
Content-Type: text/plain;charset=utf-8
Content-Transfer-Encoding: quoted-printable
From: larry@garfieldtech.com ("Larry Garfield")

On Wed, Apr 24, 2024, at 4:01 AM, Benjamin Au=C3=9Fenhofer wrote:
> On Tue, Apr 23, 2024 at 7:27=E2=80=AFPM Levi Morrison=20
> <levi.morrison@datadoghq.com> wrote:
>> On Tue, Apr 23, 2024 at 7:30=E2=80=AFAM Benjamin Au=C3=9Fenhofer <kon=
takt@beberlei.de> wrote:
>> >
>> > Hi internals,
>> >
>> > My PR for #[\Deprecated] attribute was in hibernation for a long wh=
ile now and after some off-list discussion a few weeks ago I have decide=
d 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 re=
start 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
>>=20
>> 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":
>>=20
>> ```php
>> #[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_FUNCTION)]
>> class Deprecated
>> {
>>     public function __construct(
>>         public readonly ?string $note =3D null,
>>         public readonly ?string $since =3D null
>>     ) {
>>     }
>> }
>>=20
>> #[Deprecated(since: "1.3", note: "this is not good, use good_pls_use"=
)]
>> function bad_dont_use() {}
>>=20
>> #[Deprecated("this wasn't meant to be public, use good_pls_use instea=
d")
>> function oops_dont_use() {}
>>=20
>> function good_pls_use() {}
>> ```
>>=20
>> In Rust, you get a message for each of ["since" and "note"][2]. In
>> PHP, this might look something like:
>>=20
>> > 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=20
> parameter elsewhere. We are unsure about these, because from an engine=20
> POV they do not add value, and from a user messaging perspective they=20
> could be put into the message with #[\Deprecated("since 1.3, this is=20
> not good, use good_pls_use")].=20
>
> The only reason this might make sense is to allow third party tooling=20
> to work on this, but there are no conventions ala php-doc here in plac=
e=20
> already. If tools need more infos, they could just introduce their own=20
> attributes. example:
>
> #[\Deprecated, Since("1.3"), Replacement("good_pls_use()")].
>
> It feels arbitrary if we add parameters that the engine does not use=20
> and where no tooling conventions exist on how they are being used, so=20
> 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 defi=
nitely 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