[php-src] PR #23461: Fix bug #80056: SPL directory iterators lose entries on 9p filesystems

Pull Request: https://github.com/php/php-src/pull/23461 Author: 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 microsoft/WSL#5074. - https://github.com/microsoft/WSL/issues/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 ```text 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): ```text 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): ```text > 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 ```