Newsgroups: php.internals Path: news.php.net Xref: news.php.net php.internals:123214 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 2AEEE1A009C for ; Fri, 26 Apr 2024 08:00:29 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=php.net; s=mail; t=1714118470; bh=JLkYGyUKNaHn6ucaAG4vfj6GbDH5nB9Wi7mOil1by4g=; h=References:In-Reply-To:From:Date:Subject:To:Cc:From; b=kgNoSmjPbKM8OGUkhDLMrCVCCDDrN3XRNPpTb37aE+QMehYwdoB6TT9fODockjjGC B7rpL4dv9gaES8i7qFHujLPVpAivOkF7q3xsG/PkL9eExoHmIKrGUT2HZIyg6+gKv4 8yxIcWdeB8+Drq1p00AcKDRf1orX0PgGqniLi5wYU7gAwEUGJO3SmKe2cP3KaWtukk 1IaQd39wqx1nd1wkoDL3PyHa2ruHkOFhJ1ox3xxl97PyWQ7Wv+wSmgGg56ayuCniDN 4ksZ9kP6xTGfIQUi4KoqHmbPWqJYANjBQUaUlvFWd39bogXyy3WcDmCTb5wRzJ7OqQ 8QPNuNsm3LTtQ== Received: from php-smtp4.php.net (localhost [127.0.0.1]) by php-smtp4.php.net (Postfix) with ESMTP id 52E7718007E for ; Fri, 26 Apr 2024 08:01:09 +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,DKIM_SIGNED, DKIM_VALID,DMARC_MISSING,HTML_MESSAGE,RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H2,SPF_HELO_NONE,SPF_NONE,T_SCC_BODY_TEXT_LINE autolearn=no autolearn_force=no version=4.0.0 X-Spam-Virus: No X-Envelope-From: Received: from mail-ua1-f54.google.com (mail-ua1-f54.google.com [209.85.222.54]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by php-smtp4.php.net (Postfix) with ESMTPS for ; Fri, 26 Apr 2024 08:01:08 +0000 (UTC) Received: by mail-ua1-f54.google.com with SMTP id a1e0cc1a2514c-7ef180ad3b5so694617241.1 for ; Fri, 26 Apr 2024 01:00:27 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=beberlei-de.20230601.gappssmtp.com; s=20230601; t=1714118426; x=1714723226; darn=lists.php.net; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:from:to:cc:subject:date:message-id:reply-to; bh=vA84VWp/JeFlhdgGeEtBqJXflPQeD+EgkOBgbKcrFgQ=; b=12JxSVGOxDauYvgjDX5FGSwEM67O3xI4VV9u14Y1vm66PaR6xWvDcTEDiEbIW561br z84BHZXA2qHgN+YB4192yRkcq27ay52ksfFPd/7+EYnhYg4a5D0uVCViOsUebLSH/0+b roHXJj8gowjz4+ui5ZCd9eJCLm7rsU3A1Slnrr6SwPJpQ5KTRv7OTYgteLnzT9Sh9BIR qg503Vr8btC/ztoEEU2YaarsijIU/lSbUsidjDLC0vk267sVtY9pSoNzqXVxPZK4bYZr p1MOQwTuagC0iyW94VJHwY6Xv8bhxgU3UtfPcECt2dxT5yre+PtrzjlJCsn3AIB5l63o StHQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1714118426; x=1714723226; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=vA84VWp/JeFlhdgGeEtBqJXflPQeD+EgkOBgbKcrFgQ=; b=KbSM0RaPqrqYMn71bjXrSRLBDvcXo0GMMDwyNCitWeZig+U8WiuTaT0BPezbx6LiBP 7dSAGuRll7UaGydg5EYa1XKt9R8I5Xjf5hfgVzhZIXxe04oX2Of9WYeCpuGKzNto1ZPv X9yoHMsui7krVBh+mQUpzsJhUUSkduFTFNOdE7OMn2fhXrmAzpgRmxqt2Wyzl5X/djem IrOKSjMCKuFxaBZZBvN9I2mu0YpwEuy1A0uXGxKjn6EQE2xSTNHh68eInIsplw+Q9Szl LquUO05MxupcR+WD5NSm0DHPJRbEyQNWWK1KK89rfU7grS6wA6X4GkNhqCPlFCANkTES xmjQ== X-Gm-Message-State: AOJu0YxMv1oa5WxWkqzeuGaTHarIbDmEm5ZNbXpR1TxgBdl9P/pJglKp LrPjHEMryeh+3O1WSY+6xqasYtSLd+Y4Y0/pysnlB3Ed4qQBLEO/QNJwcYVTXYPEF8PAMjvs2im gfY62AnIWLTIzOeS3LRqP3+VBpQHltgU1ELeffw== X-Google-Smtp-Source: AGHT+IGp/kKQZ6rHTJsXiwbY/+CEpZ4eZlBPWj0eEpqFO6Ix7ALoFKiajEH0O5XCSXbT6fC09x/1qRz1DD33OB+wBeI= X-Received: by 2002:a05:6102:b11:b0:47c:2a61:ec9 with SMTP id b17-20020a0561020b1100b0047c2a610ec9mr154555vst.25.1714118424826; Fri, 26 Apr 2024 01:00:24 -0700 (PDT) Precedence: bulk list-help: list-post: List-Id: internals.lists.php.net MIME-Version: 1.0 References: In-Reply-To: Date: Fri, 26 Apr 2024 10:00:13 +0200 Message-ID: Subject: Re: [PHP-DEV] [RFC] [Discussion] #[\Deprecated] attribute again v1.3 To: Levi Morrison Cc: PHP Internals , "tim@tideways-gmbh.com" Content-Type: multipart/alternative; boundary="000000000000d0b0920616fb4bb1" From: kontakt@beberlei.de (=?UTF-8?Q?Benjamin_Au=C3=9Fenhofer?=) --000000000000d0b0920616fb4bb1 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable On Tue, Apr 23, 2024 at 7:27=E2=80=AFPM Levi Morrison wrote: > On Tue, Apr 23, 2024 at 7:30=E2=80=AFAM Benjamin Au=C3=9Fenhofer > 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 restar= t > 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 > After discussing with Mate shortly one reason for adding $since from a PHP project POV is that we do show the $since information in the generated documentation output. Integrating with the work in progress to auto generate parts of the function docs based on the stub files, having the $since attribute on the stubs would allow to use this as the central information in code. Therefore we would reconsider and add the $since argument to the Deprecated class. I am still partly on the side on Rowan ( https://externals.io/message/123184#123206) that i don't find the arguments for this parameter very convincing but at least there is a use-case internally now that warrants adding it. > > [1]: > https://doc.rust-lang.org/reference/attributes/diagnostics.html#the-depre= cated-attribute > [2]: > https://github.com/rust-lang/rfcs/blob/master/text/1270-deprecation.md#in= tended-use > --000000000000d0b0920616fb4bb1 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable


=
On Tue, Apr 23, 2024 at 7:27=E2=80=AF= PM Levi Morrison <levi.mo= rrison@datadoghq.com> wrote:
On Tue, Apr 2= 3, 2024 at 7:30=E2=80=AFAM Benjamin Au=C3=9Fenhofer <kontakt@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 r= evisit 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 fe= atures such as #[Deprecated] support in stub generation.
>
> While there are still some small todos, at this point we want to resta= rt 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#1= 12554
>
> 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
{
=C2=A0 =C2=A0 public function __construct(
=C2=A0 =C2=A0 =C2=A0 =C2=A0 public readonly ?string $note =3D null,
=C2=A0 =C2=A0 =C2=A0 =C2=A0 public readonly ?string $since =3D null
=C2=A0 =C2=A0 ) {
=C2=A0 =C2=A0 }
}

#[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 ins= tead")
function oops_dont_use() {}

function good_pls_use() {}
```

In Rust, you get a message for each of ["since" and "note&qu= ot;][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

After discussing with M= ate shortly one reason for adding $since from a PHP project POV is that we = do show the $since information in the generated documentation output.
=

Integrating with the work in progress to auto generate = parts of the function docs based on the stub files, having the $since attri= bute on the stubs would allow to use this as the central information in cod= e. Therefore we would reconsider and add the $since argument to the Depreca= ted class.

I am still partly on the side on Rowan = (https://externals.i= o/message/123184#123206) that i don't find the arguments for this p= arameter very convincing but at least there is a use-case internally now th= at warrants adding it.
=C2=A0

=C2=A0 [1]: = https://doc.rust-lang.org/reference/attributes/diagnostics.html#the-depreca= ted-attribute
=C2=A0 [2]: https= ://github.com/rust-lang/rfcs/blob/master/text/1270-deprecation.md#intended-= use
--000000000000d0b0920616fb4bb1--