Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:123190
Precedence: bulk
MIME-Version: 1.0
References: <CAEPJdumvJNQ+JZ3wkLP-Q2O0y57g=W_hHFkuvOKMVJqqraKCzw@mail.gmail.com>
In-Reply-To: <CAEPJdumvJNQ+JZ3wkLP-Q2O0y57g=W_hHFkuvOKMVJqqraKCzw@mail.gmail.com>
Date: Tue, 23 Apr 2024 11:27:27 -0600
Message-ID: <CAAKU0uk6UYs_0sJr28gkmN_iwPcaF=z9Cr=dqOLTMHji7UNxHg@mail.gmail.com>
Subject: Re: [PHP-DEV] [RFC] [Discussion] #[\Deprecated] attribute again v1.3
To: =?UTF-8?Q?Benjamin_Au=C3=9Fenhofer?= <kontakt@beberlei.de>
Cc: PHP Internals <internals@lists.php.net>, 
	"tim@tideways-gmbh.com" <tim@tideways-gmbh.com>
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
From: levi.morrison@datadoghq.com (Levi Morrison)

On Tue, Apr 23, 2024 at 7:30=E2=80=AFAM Benjamin Au=C3=9Fenhofer <kontakt@b=
eberlei.de> wrote:
>
> Hi internals,
>
> My PR for #[\Deprecated] attribute was in hibernation for a long while no=
w and after some off-list discussion a few weeks ago I have decided to revi=
sit 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 featu=
res 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 =3D null,
        public readonly ?string $since =3D 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

  [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