Functions signatures are documented as can return FALSE, but return value documentation disagrees

This is a generalization of the issue https://github.com/php/doc-en/issues/856. Thank you to @cmb69 on that one.

I have gone out to find every instance of a PHP function which is defined as possibly returning a false value but where the return value documentation does not mention the possibility of a false return value.

I created this list of candidates using:

grep --files-with-matches --recursive '<type class="union"><type>\w\+</type><type>false</type></type>' . > ~/Desktop/canoutputfalse

grep --files-with-matches --recursive '&return.falseforfailure;' . > ~/Desktop/falseforfailure

cat ~/Desktop/canoutputfalse ~/Desktop/falseforfailure ~/Desktop/falseforfailure | sort | uniq -u > ~/Desktop/reviewthese

code $(cat ~/Desktop/reviewthese)

And manually reviewing each one.

This is part of my efforts in https://github.com/php/doc-en/pull/858. And please ftlog review and approve that PR first so it can be merged without sitting around!

The list

• https://www.php.net/manual/en/function.sodium-crypto-secretstream-xchacha20poly1305-pull.php
• https://www.php.net/manual/en/simplexmlelement.getdocnamespaces.php
• https://www.php.net/manual/en/function.pspell-suggest.php
• https://www.php.net/manual/en/function.pspell-new-personal.php
• https://www.php.net/manual/en/pdo.lastinsertid.php
• https://www.php.net/manual/en/pdo.exec.php (strictly speaking, it is not said how this will return false)
• https://www.php.net/manual/en/function.opcache-get-configuration.php
• https://www.php.net/manual/en/mysqli.stmt-init.php
• https://www.php.net/manual/en/function.imap-uid.php
• https://www.php.net/manual/en/function.hash.php
• https://www.php.net/manual/en/function.hash-file.php
• https://www.php.net/manual/en/domtext.splittext.php
• https://www.php.net/manual/en/domnodelist.count.php
• https://www.php.net/manual/en/domnode.insertbefore.php
• https://www.php.net/manual/en/domnode.clonenode.php
• https://www.php.net/manual/en/domnode.appendchild.php
• https://www.php.net/manual/en/domnamednodemap.count.php
• https://www.php.net/manual/en/domimplementation.createdocumenttype.php
• https://www.php.net/manual/en/domimplementation.createdocument.php
• https://www.php.net/manual/en/domcharacterdata.substringdata.php
• https://www.php.net/manual/en/function.curl-version.php
• https://www.php.net/manual/en/compersisthelper.getcurfilename.php
• https://www.php.net/manual/en/ziparchive.open.php (strictly speaking again)

My understanding is that this list is comprehensive, I don't think you will find any more that could fit in this category.

Work plan

For each one of these in the list, we should read the implementation and either:

1. If the function CANNOT return false, then remove the false in the definition at top.
2. If the function CAN return false, then explain this in the return value section.

Start with the listed manual-page entries and use the provided grep commands to review candidates whose signatures include false or return.falseforfailure. Compare each function with its implementation, then ensure every checklist item either removes an incorrect false signature or documents the false return; review pull request 858 first as requested.