<?php
    $t0 = hrtime(true);
    for ($i = 0; $i < 1000; $i++) {
        is_dir(__DIR__);
    }
    $t1 = hrtime(true);
    for ($i = 0; $i < 1000; $i++) {
        file_exists(__DIR__);
    }
    $t2 = hrtime(true);
    printf("is_dir      took %f ms\n", ($t1 - $t0)/10e6);
    printf("file_exists took %f ms\n", ($t2 - $t1)/10e6);

outputs for me something like:

    is_dir      took 0.051130 ms
    file_exists took 3.395850 ms

Actually, it is to be expected that file_exists() is much slower
than is_dir() (when the realpath cache is enabled), because the
former checks whether the file may be accessed, and since this
information is not cached, it is done for each and every call.

Changing to doc problem, since this behavior is not described in
the manual.

Maybe we could somehow produce a overview which sorts the often used (and similar) io functions from faster to more expensive ones.

I can think of

is_file
is_dir
file_exists
filemtime
filectime
fileatime
filesize

Etc.

why does `is_file()` contain is_readable() functionality?
Separation of concerns

If I want to determine "is file" without regard to file permissions:.

file_exists($file) && !is_dir($file);    // file is a file!
is_file($file);  // file is a file I have permission to access

additionally, the fact that file_exists() returns false when it can see that the file clearly exists, but isn't readable, is a god-damn bug. if people want to know if a file is readable, we have is_readable() for that. i realize that due to BC-breaking, this can only be fixed in a major release like PHP8 or PHP9, though..

> additionally, the fact that file_exists() returns false when it
> can see that the file clearly exists, but isn't readable, is a
> god-damn bug.

Debatable.  It is done that way, so the the stat and realpath
caches are not affected by file_exists().  Of course, the
implementation could be changed, but that would at least require
discussion on the internals mailing list.