Doc #77218 [Opn]: password_hash returns null on failure instead of false as of PHP 7.4

Edit report at https://bugs.php.net/bug.php?id=77218&edit=1 ID: 77218 Updated by: cmb@php.net Reported by: magnar at myrtveit dot com -Summary: password_hash returns null on failure instead of false as of PHP 7.3 +Summary: password_hash returns null on failure instead of false as of PHP 7.4 Status: Open Type: Documentation Problem Package: *Encryption and hash functions PHP Version: 7.3.0 Block user comment: N Private report: N New Comment: Correction: the behavioral change does not affect PHP 7.3, but master only. The cases which return NULL in PHP 7.3 and before, are according to the general note regarding return values for invalid/unsuitable parameters[1]. In my opinion, password_hash() should *throw* on failure for the same reasons random_bytes() does. [1] <http://php.net/manual/en/functions.internal.php> Previous Comments: ------------------------------------------------------------------------ [2019-01-24 18:45:48] cmb@php.net I think that might need discussion on internals@. Anyhow, the status “feedback” is for requesting feedback from the reporter – if no feedback is given after a week, the ticket will automatically be closed with status “no feedback”. ------------------------------------------------------------------------ [2019-01-24 18:10:59] girgias@php.net Is this going to be reverted or should I write a documentation patch? ------------------------------------------------------------------------ [2019-01-02 14:32:38] cmb@php.net @nikic This is true for master, but the code has recently been changed[1], and apparently older versions would have returned FALSE if the underlying hash function failed[2][3]][4]]. So basically, for PHP ≤ 7.3, the function returned FALSE for a failing implementation, and NULL for invalid parameters in combination with a warning (the latter likely according to the general convention to return NULL on ZPP failures). This behavioral change looks rather dangerous to me, since formerly developers who had carefully made sure that they pass valid arguments might have checked for a FALSE return to signal failure. Now they'd get a NULL, which might pass their check. [1] <https://github.com/php/php-src/commit/534df87c9e3c28001986e70844e0ad04e5708d3d> [2] <https://github.com/php/php-src/blob/php-7.3.0/ext/standard/password.c#L492> [3] <https://github.com/php/php-src/blob/php-7.3.0/ext/standard/password.c#L497> [4] <https://github.com/php/php-src/blob/php-7.3.0/ext/standard/password.c#L585> ------------------------------------------------------------------------ [2019-01-02 13:55:02] nikic@php.net password_hash() does indeed consistently use null for errors, so this should be adjusted in the docs, not implementation. ------------------------------------------------------------------------ [2018-12-08 06:47:43] yohgaki@php.net Briefly checked how RETURN_NULL() is used. Most of them, but password_hash(), return NULL when "empty" result is appropriate, not for errors. RETURN_NULL() for invalid algo seems actually a bug. ------------------------------------------------------------------------ The remainder of the comments for this report are too long. To view the rest of the comments, please view the bug report online at https://bugs.php.net/bug.php?id=77218 -- Edit this bug report at https://bugs.php.net/bug.php?id=77218&edit=1