What makes you think false is a valid argument for the function?

The documentation actually alerts you that this is a possible return value. Quoting:

Warning
This function may return Boolean FALSE, but may also return a non-Boolean value which evaluates to FALSE. Please read the section on Booleans for more information. Use the === operator for testing the return value of this function.

//What makes you think false is a valid argument for the function?
Nothing we even have a check in our code to pretend it, but when you have a lot of processes there is still a chance that it happens in between. Which may occur with our site yesterday,

if ($dir = opendir($filePath) && is_numeric($noOfDays) > 0) 
        {
            while (false !== ($logFile = readdir($dir)))

// The documentation actually alerts you that this is a possible return value. Quoting:
Yes, you are absolutely right. Despite the fact, I still don't see any reasons why the function is returning null in this case. 

Also, I would like to add that mentioned code wasn't implemented by me and I suppose an author was encouraged by the example from the documentation.

Also, I personally believe that this is a pretty hard to predict consequences from this warning message.

what makes YOU think NULL is the correct return in case of a invalid param when the doc says it returns boolean flase when not sucessful

anyways, that's why i ported a 250000 LOC codebase in the last year to declare(strict_types=1); which would lead to a exception in the case below

Closing as not a bug for the readdir() page.  Returning NULL is a convention widely used throughout PHP and is not something we document for every individual function.

" Note: If the parameters given to a function are not what
  it expects, such as passing an array where a string is expected, 
  the return value of the function is undefined. In this case it
  will likely return NULL but this is just a convention, and
  cannot be relied upon."

  -- http://php.net/manual/en/functions.internal.php

To add to that,

> I suppose an author was encouraged by the example from the documentation
The author apparently forgot about operator precedence. && has higher precedence than = [1] so the code is effectively
  if ($dir = (opendir($filePath) && is_numeric($noOfDays) > 0))
which means yes, the code never worked correctly to begin with. You can also quickly infer from this that readdir() is being passed true - not false.

Use "and" or parentheses. https://3v4l.org/so2bX

Perhaps the is_numeric() check was just added? Speaking of, the author of that piece apparently forgot that is_numeric returns bool, so comparing >0 is nonsensical although functional.

[1] http://php.net/manual/en/language.operators.precedence.php

Meanwhile the "which evaluates to FALSE" note is a macro which typically means the function can also return 0 or an empty string. Since readdir() does not return integers and it's not possible to have a file/directory named "" (as far as I know) the warning would be alluding to the string "0".

Side comment: opendir/readdir/closedir loops are old. scandir and glob are easier.

Thank you very much for your explanation.