Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:124693
Message-ID: <2244a37f-8c51-448d-8a56-329ff32e6470@bastelstu.be>
Date: Tue, 30 Jul 2024 22:26:19 +0200
Precedence: bulk
MIME-Version: 1.0
Subject: Re: [PHP-DEV] [RFC] [VOTE] Deprecations for PHP 8.4
To: Rob Landers <rob@bottled.codes>, 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>
 <c03eb187-bd21-4a4b-9faf-8d0243eaa994@varteg.nz>
 <aa6bc7aa-28d9-40ca-974f-65075adb6199@rwec.co.uk>
 <3563cf9b-8eab-4c82-b525-a5d2f9a767bb@varteg.nz>
 <38920A4B-790D-48C7-B2F6-C49D3F506232@rwec.co.uk>
 <0824789d-0e36-4628-85c1-4b8d9b7f86af@varteg.nz>
 <ab8c974a-c31c-4ff6-974d-0a8c962d5e22@app.fastmail.com>
Content-Language: en-US
In-Reply-To: <ab8c974a-c31c-4ff6-974d-0a8c962d5e22@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/28/24 00:25, Rob Landers wrote:
> I'd love to see a "hashing" namespace and all of these given their own functions with docblocks and manual pages instead of the current generic "god of hash" page which doesn't even list the hash functions available; you have to click on hash_algos and then look at the var_dump of hash algorithms. From there, you can google each one and try to understand what each one is good at and why you would use murmur3a over murmer3f, then try to figure out which one is the version that is compatible with javascript but not compatible with c# or maybe the other way around... (I recently got to go on that ride).

The problem with adding standalone functions for every algorithm is that 
it would result in a combinatorial explosion of available functions.

Unless we want to make some of them "second class citizens" with reduced 
functionality or generally want to remove everything except for 
incremental hashing, we would need the following for each of them (with 
hash standing for the algorithm):

- hash()
- hash_hmac()
- hash_file()
- hash_init()
- hash_hmac_init()
- hash_update() (could also be a method)
- hash_update_file() (could also be a method)
- hash_update_stream() (could also be a method)
- hash_final() (could also be a method)
- hash_hkdf()
- hash_pbkdf2()

That clearly does not scale. See also my previous reply to Rowan 
regarding the documentation.

It's clearly a topic for the farer future, but if / When tagged unions 
[1] make it in the language, I plan to propose an update allowing to 
pass an algorithm enum, including all the necessary options to the hash 
functions. This would make the algorithms more discoverable, easier to 
independently document and remove the footgun of needing to provide a 
matching untyped options array (which incidentally is also listed in the 
deprecation RFC as a footgun).

[1] https://wiki.php.net/rfc/tagged_unions

I'd also like to note that providing the hash algorithms by a generic 
interface is not particularly unusual. Here's two examples:

- node.js: https://nodejs.org/api/crypto.html#class-hash
- Python: https://docs.python.org/3/library/hashlib.html (which also 
takes a named constructor, which would be reasonably similar to my 
tagged-union proposal above).

Other languages, such as Ruby or Golang, appear to use a Hash interface 
with appropriate methods, but I am not sure if this is a good fit for 
PHP given the way the documentation is structured, with a dedicated page 
for each and every function or method, and the fact that PHP does not 
provide for extension methods, which would require implementing the 
convenience functionality for each algorithm separately - or as 
standalone functions.

Best regards
Tim Düsterhus