Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:124689
Message-ID: <70262e95-f0e7-40c0-a731-480f178cbc35@bastelstu.be>
Date: Tue, 30 Jul 2024 21:15:30 +0200
Precedence: bulk
MIME-Version: 1.0
Subject: Re: [PHP-DEV] [RFC] [VOTE] Deprecations for PHP 8.4
To: "Rowan Tommins [IMSoP]" <imsop.php@rwec.co.uk>, internals@lists.php.net
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>
 <3beb3488-94fc-484e-ac6c-ce7a7a0facd2@app.fastmail.com>
Content-Language: en-US
In-Reply-To: <3beb3488-94fc-484e-ac6c-ce7a7a0facd2@app.fastmail.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

On 7/26/24 19:33, Rowan Tommins [IMSoP] wrote:
> 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.

Part of the motivation of the deprecation (and my argument against the 
addition of a standalone sha256() function) is simplifying the 
documentation: Everything needs to be written down in multiple different 
places, any changes to hash_file() will likely also need to be applied 
to md5_file() and sha1_file() - and then it will need to be translated.

Given that the md5(), sha1(), md5_file(), and sha1_file() functions are 
not part of the hash extension, it's also much harder for the user to 
discover the incremental hashing functionality provided by hash_init().

It's much much easier to keep the documentation in a good shape if there 
is a single place.

--------------

I did some updates to the documentation before this RFC went to vote, 
though (and did additional ones in response to this discussion). Here 
are my PRs: 
https://github.com/php/doc-en/pulls?q=is%3Apr+author%3ATimWolla+hash+is%3Aclosed

To summarize the changes:

- I've completely rewritten the documentation of hash_equals().
- I updated the examples for the hash_*() functions to use 'sha256' and 
to be synchronized across the different functions to showcase how the 
different functions all result in the same output, given the same input.
- I cleaned up the "See Also" section to make the references from 
md5()/sha1() to hash() a "one-way street". Once you discovered the 
hash() functions, you shouldn't need md5() and sha1().
- I've removed the broken algorithms from the $algo parameter 
explanation, leaving only 'sha256' as the opinionated example (already 
merged, but not yet deployed).

Best regards
Tim Düsterhus