Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:124367
Message-ID: <a6436000-86e4-46e4-94e8-6f17186ccc2c@bastelstu.be>
Date: Wed, 10 Jul 2024 20:44:17 +0200
Precedence: bulk
MIME-Version: 1.0
Subject: Re: [PHP-DEV] Re: [RFC] [Vote] #[\Deprecated] attribute
To: Nicolas Grekas <nicolas.grekas+php@gmail.com>,
 =?UTF-8?Q?Benjamin_Au=C3=9Fenhofer?= <kontakt@beberlei.de>
Cc: PHP Internals <internals@lists.php.net>
References: <CAEPJdu=ZTyPQ3yabhOx=rxnv5niuA+9O4BP6EsvAdkZRSS5Q2g@mail.gmail.com>
 <CAEPJdu=Qum4-HygCbs8xgpiNhm+gdeP6rG6Ua8jApz7pZTKfvA@mail.gmail.com>
 <CAOWwgp=TXMJC2+mgnCGJH0jXLo8WiY2uMb8i5LVZJSdoodVH3w@mail.gmail.com>
Content-Language: en-US
In-Reply-To: <CAOWwgp=TXMJC2+mgnCGJH0jXLo8WiY2uMb8i5LVZJSdoodVH3w@mail.gmail.com>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 8bit
From: tim@bastelstu.be (=?UTF-8?Q?Tim_D=C3=BCsterhus?=)

Hi

I'm specifically replying to Nicolas, but this email is directed to the 
general public, so please feel free to reply even if you are not called 
Nicolas :-)

On 6/24/24 17:06, Nicolas Grekas wrote:
> 2/ About  the "since" parameter, we're going to standardize around a
> package+version string, e.g.
> #[Deprecated(since: "symfony/yaml v7.2"]
> 
> I'm sharing this hoping this can spread outside of Symfony's boundary
> because I think this would be a very useful practice that'd allow building
> nice reporting tools.
> 

I have merged the follow-up PR to apply the attribute earlier today:

https://github.com/php/php-src/commit/29f98e748568ebd66aaae061c0dcefbba92ca058

For now I've filled in the `$since` attribute with a bare version 
number, since this most closely matches what was described in the RFC.

I'm happy to do another follow-up on the format of the `$since` property 
for internal functions if we can reach a simple consensus here on the 
list. I think it should also be acceptable to do some basic processing 
of the `$since` property for the display in the human readable error 
message, making it easier to consume it programmatically without looking 
ugly to the human reader.

For PHP internal attributes the obvious choice would be:

     #[\Deprecated(since: 'PHP 8.4')]
     function foo() { }

which would result in an error message similar to:

     Deprecated: Function foo() is deprecated since PHP 8.4

The space probably is easy enough to understand for programmatic 
consumption in frameworks / error tracking libraries and the 'PHP' 
matches how the PHP requirements are defined in composer dependencies 
(once lowercased). I don't like the 'v' prefix for the version number, 
because to the best of my knowledge nothing else uses that (except for 
git tags).

You can find the discussion about the `$since` property in the first PR 
at https://github.com/php/php-src/pull/11293#discussion_r1647339607, if 
you want additional context.

Best regards
Tim Düsterhus