Doc #77218 [Fbk->Opn]: password_hash returns null on failure instead of false as of PHP 7.3

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 -Status: Feedback +Status: Open Type: Documentation Problem Package: *Encryption and hash functions PHP Version: 7.3.0 Block user comment: N Private report: N New Comment: 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”. Previous Comments: ------------------------------------------------------------------------ [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. ------------------------------------------------------------------------ [2018-12-01 13:15:59] petk@php.net Hello, I'm just confirming this issue for now. Yes, the documentation should be probably fixed from false to null in case of failure such as non existing algorithm. Returning string or null is more logical in these more recently added functions. Returning mixed value of boolean is much less logical to expect and understand in such case I think. ------------------------------------------------------------------------ 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