Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:124621
Feedback-ID: id5114917:Fastmail
User-Agent: Cyrus-JMAP/3.11.0-alpha0-582-g5a02f8850-fm-20240719.002-g5a02f885
Precedence: bulk
MIME-Version: 1.0
Message-ID: <3beb3488-94fc-484e-ac6c-ce7a7a0facd2@app.fastmail.com>
In-Reply-To: <d54b99fd-64ea-40f2-9fee-c904f1305893@app.fastmail.com>
References: 
 <USzt7tZZlO1DmAbSTLhD-bqa23FqZn0zk2aah8Ndxgk9c7RY5PefQ8MjbYPUYAzr2_m4Cf-5AI4PuNBTS84rim_FNS6RaT-cWSv714HEvvU=@gpb.moe>
 <1a88918e-e808-d778-45e1-53797660e093@php.net>
 <CAPrKfG5Cw_nU7g7FR+t4C1-YZ8CDsDO_-sRs=yEsHO5kCTZL+A@mail.gmail.com>
 <95147d9d-d6e8-4396-bf0b-409c33679f90@bastelstu.be>
 <CAPrKfG4TijmZ_N9512_Fk9MBUNg=E6PjNTy-bCbV8CAj9_wX8A@mail.gmail.com>
 <CAPrKfG7Hi0SGbLA31V-9KjHM50QaX+Q=PptuO4+VMOrz7d9eBA@mail.gmail.com>
 <G9IiDe18a2ZhrXPA-zljNZsawKCZxlTn2ACfJpM32scdRkRflZ2rM6Ra8z88ZYDczomex4pffxZMpVhEjdB74YQXXNyqJkd7rQdDGA14HC0=@gpb.moe>
 <89096756-9f50-4b10-9630-d3b18e4b9c29@gmx.de>
 <d54b99fd-64ea-40f2-9fee-c904f1305893@app.fastmail.com>
Date: Fri, 26 Jul 2024 18:33:20 +0100
To: internals@lists.php.net
Subject: Re: [PHP-DEV] [RFC] [VOTE] Deprecations for PHP 8.4
Content-Type: text/plain
From: imsop.php@rwec.co.uk ("Rowan Tommins [IMSoP]")

On Fri, 26 Jul 2024, at 15:20, Larry Garfield wrote:
> One thing to remind people about, the deprecations for md5(), sha1(), 
> and uniqid() explicitly say they cannot be outright removed before PHP 
> 10.  That's at least 6 years away.  That gives a loooooong time for 
> documentation, tutorials, instructions, and code to be updated.

It also gives a loooooong time for us to update that documentation *before* we start raising deprecation notices, so that there's a chance for someone to actually know what they're supposed to do about it.

When I formally proposed deprecation of utf8_encode and utf8_decode, I didn't even post the RFC for discussion before I had written two documentation PRs, one to improve documentation even if the RFC failed; and another proposing the wording if it passed. 


In contrast, I voted against the deprecation of strftime() because no effort had been made to explain how users should replace it. Surprise surprise, nobody has spent any more effort in the 3.5 years since the deprecation passed, and the only advice in the documentation remains:

> Instead use the IntlDateFormatter::format() method.


On Fri, 26 Jul 2024, at 15:27, Christoph M. Becker wrote:
> Well, you are supposed to also check the hash_hmac() documentation...

Why would I, if I'm not using that function? For that matter, when should I be using that function? I'm not even being facetious here, I am genuinely lacking in relevant expertise, and the summary for hash_hmac() is meaningless unless you already know what it does:

> Generate a keyed hash value using the HMAC method


If the problem is that the web is full of bad documentation, find or write some GOOD documentation. Then, work out how best to signpost users to that documentation. Deprecating md5() and sha1() does neither.

 Regards,
-- 
Rowan Tommins
[IMSoP]