Fix bug #80056: SPL directory iterators lose entries on 9p filesystems

[denkfabrik-li]

Summary

FilesystemIterator, RecursiveDirectoryIterator and DirectoryIterator silently
lose directory entries on filesystems that cannot rewind a directory handle after a
partial read — most notably 9p mounts, which is what WSL2 and Docker Desktop on
Windows use to expose the Windows drive to Linux. An entire libc getdents buffer
vanishes from the iteration: ~21 entries with musl (2 KiB buffer), ~343 with glibc
(32 KiB buffer). scandir(), glob() and a plain readdir() loop over the same
directory return the complete listing.

The cause is PHP-specific behaviour, not just the kernel bug: the iterator
constructors eagerly read the first directory entry, and the implicit rewind() at
the start of the first foreach then calls rewinddir() on a stream whose position
is already past that first entry. On a healthy filesystem this seek is redundant (it
re-reads the entry the constructor already had); on 9p the seek is silently ignored
server-side while the C library discards its read buffer — everything that was in
that buffer is skipped.

This PR makes the rewind a no-op while the stream is still positioned at its first
entry, so the standard construct-then-foreach pattern never seeks at all.

History

• https://bugs.php.net/bug.php?id=80056 (Sep 2020, RecursiveDirectoryIterator misses
  files under Docker/WSL2) — closed "Not a bug": "this is unlikely to be a PHP issue".
• https://bugs.php.net/bug.php?id=80227 (Oct 2020, same on Alpine/Docker/WSL2) —
  closed "Not a bug": "it's a WSL bug", pointing to WSL2: Seek of directory entry by lseek does not work on v9fs microsoft/WSL#5074.
• WSL2: Seek of directory entry by lseek does not work on v9fs microsoft/WSL#5074 — closed by the bot without a fix;
  still reproducible today (measurements below, Windows 11, current WSL2/Docker
  Desktop).

Both reports were closed on the grounds that the underlying seek failure lives below
PHP — which is true. But no code change was ever proposed back then, and the seek
itself is avoidable: it is issued by PHP at a moment where it has nothing to do.
Every other PHP directory API (scandir(), glob(), opendir()/readdir())
works on these mounts precisely because none of them seeks a partially-read handle.

The failure mode is nasty in practice because it is silent, size-dependent (only
directories with more entries than one libc buffer are affected) and
environment-dependent (works on ext4, breaks on the very same code under Docker
Desktop on Windows). Real-world sightings include Composer autoload scans, Laravel
migration discovery and PHPStan/Larastan file collection:
laravel/framework#61336, larastan/larastan#2538, projectsend/projectsend#1680.

The mechanism

new FilesystemIterator($dir)          # constructor opens the dir
  -> readdir()                        #   ...and eagerly reads entry #1
                                      #   libc fills its getdents buffer
foreach ($it as $f)                   # foreach starts with rewind()
  -> rewinddir()                      #   seek to offset 0
                                      #   9p: seek silently ignored,
                                      #   libc buffer discarded anyway
  -> readdir(), readdir(), ...        #   continues AFTER the discarded buffer

With musl's 2 KiB buffer the first ~21 entries disappear; with glibc's 32 KiB
buffer the first ~343. Directories at or below one buffer appear complete, which is
why small test cases pass and production directories fail.

The fix

Track in spl_filesystem_object.u.dir whether the stream is still positioned at its
first (non-skipped) entry (at_initial_entry). All four rewind paths
(DirectoryIterator::rewind(), FilesystemIterator::rewind(), and the two internal
zend_object_iterator rewind handlers) are consolidated into one helper,
spl_filesystem_dir_rewind(), which skips the rewinddir() + re-read when nothing
has been consumed yet. Any actual read (next(), internal move_forward, the
clone catch-up loop, seek()) clears the flag, so a rewind after real consumption
still performs a real rewinddir() exactly as before.

Behaviour / BC analysis

Unchanged:

• The constructor still opens the directory eagerly — an invalid path still throws
  UnexpectedValueException from the constructor.
• The constructor still pre-reads the first entry: $it->current(),
  getFilename(), key(), hasChildren() etc. right after construction behave
  exactly as before (and now also work on 9p, since the pre-read is sequential).
• rewind() after any entry has been consumed performs a real rewinddir() +
  re-read, as before (re-iterating an iterator, seek() backwards, clone).
• Result sets, ordering, keys, flags handling (SKIP_DOTS, …) on healthy
  filesystems: byte-for-byte identical output; the full test suite passes.

Observable differences (deliberate):

• While the stream is still on its first entry, rewind() no longer issues
  rewinddir() + readdir(). For userland stream wrappers this means
  dir_rewinddir() is no longer invoked at the start of the first iteration (one
  callback less; a wrapper that relied on being rewound before the first read was
  already broken, since the constructor pre-read has always happened before any
  rewind). One redundant syscall pair per iteration start is saved everywhere.
• POSIX allows rewinddir() to pick up directory modifications made after
  opendir(). A file created between construction and the first foreach was
  previously sometimes visible (filesystem-dependent, POSIX explicitly leaves it
  unspecified); with the no-op rewind the iteration keeps the view the constructor
  started with. Code relying on that was already unreliable across filesystems.

Known limitation (unchanged, inherent to broken seeks): re-iterating the same
iterator object (second foreach, explicit rewind() after next()) still
requires a real rewinddir() and therefore still misbehaves on 9p — same as a
userland rewinddir() call. This patch fixes the overwhelmingly common
construct-then-iterate-once pattern, which is what Composer/Laravel/PHPStan & co.
use.

Tests

• ext/spl/tests/bug80056.phpt — simulates the broken filesystem with a userland
  stream wrapper whose dir_rewinddir() pretends to succeed without resetting the
  position (exactly the observable 9p behaviour). Fails on current master (each
  iterator loses its first entry), passes with the fix. Covers DirectoryIterator,
  FilesystemIterator, RecursiveDirectoryIterator + RecursiveIteratorIterator, and
  the "entry accessed before iteration" pattern.
• ext/spl/tests/spl_dir_iterator_rewind_noop.phpt — pins the new seek semantics
  with a counting wrapper: no dir_rewinddir() on first iteration, exactly one on
  re-iteration, exactly one for rewind() after next(), none for repeated
  rewind() without reads.
• Existing SPL suite: green (see verification below).

Verification

Two-stage, with unpatched and patched CLI binaries built from the same master
checkout (ext/spl/spl_directory.* diff applied incrementally in the same
container build):

(a) Test suite (ext4 inside the build containers):

Full ext/spl suite with the patched CLI — identical results on
Debian bookworm (glibc) and Alpine 3.22 (musl):

Number of tests :   810               799
Tests skipped   :    11 (  1.4%)
Tests failed    :     0 (  0.0%)
Expected fail   :     1 (  0.1%)   (pre-existing XFAIL, unrelated)
Tests passed    :   798 ( 98.5%)

A second build with --enable-phar --enable-zend-test additionally runs the
SPL-over-phar and stack-limit tests (gh14687, gh17225, gh15911, gh15672 — all
pass; 802 SPL tests passed total) plus the full ext/phar suite: 382 runnable
tests, 0 failures. Relevant because Phar extends RecursiveDirectoryIterator
and embeds spl_filesystem_object; its in-memory directory stream keeps a
working seek, so behaviour is unchanged there.

Both new tests FAIL on unpatched master, each iterator losing its first entry
(array(4) instead of array(5), a.txt missing) — i.e. the regression tests
demonstrably catch the bug.

(b) Live 9p mount (Docker Desktop on Windows 11, WSL2 backend; a Windows
directory with 500 .php files — plus 1 in a subdirectory for the recursive
case — mounted into the container; stat -f -c %T reports v9fs):

API	musl unpatched	musl patched	glibc unpatched	glibc patched
scandir()	500	500	500	500
glob()	500	500	500	500
readdir() loop	500	500	500	500
FilesystemIterator	479	500	157	500
RecursiveDirectoryIterator	480	501	158	501
DirectoryIterator	479	500	157	500

The losses match the libc buffer sizes exactly: musl drops its first 2 KiB
getdents buffer (21 entries), glibc its first 32 KiB buffer (343 entries).

One-liner reproducer for anyone with Docker Desktop on Windows (stock image,
directory with a few hundred files):

> docker run --rm -v C:\some\big\dir:/mnt/d php:8.4-cli php -r \
    "echo count(scandir('/mnt/d'))-2, ' vs ', iterator_count(new FilesystemIterator('/mnt/d'));"
501 vs 158        # PHP 8.4.24, verified 2026-08-25