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

[fulldecent]

This is a generalization of the issue #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 #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.

[fulldecent]

I plan to work on these myself.

Just wanted to socialize the idea here with an issue and share the approach I'm using.

---

I'm not interested to start here until my other PRs are resolved.