Php File Iterator Laravel Package

Product Decisions This Supports

• A "do nothing" dependency decision. phpunit/php-file-iterator is not a product dependency — it is a low-level utility that PHPUnit uses internally for test discovery (via phpunit/php-code-coverage). It arrives in vendor/ automatically when the team runs tests. The correct PM decision is to not add it explicitly to composer.json and to treat it as an implementation detail of the test toolchain.
• Build vs. buy for internal developer tooling. When the roadmap includes tooling that must enumerate files by suffix/prefix/exclude rules (test sharding across CI runners, coverage source lists, static-analysis baselines, code-generation scaffolds), this is a "buy" (free, already present) rather than a "build." It should never be the choice for runtime, customer-facing code paths.
• Framework alignment. Laravel already ships Symfony Finder. Choosing this package for application-level file operations would introduce a second, inconsistent traversal idiom for zero benefit — so the decision is: Symfony Finder for product code, PHPUnit's iterator only implicitly for tests.
• Platform-upgrade gates. Version 7.0.0 dropped PHP 8.3 support, and 6.0.0 dropped 8.2. Because PHPUnit pins a compatible major, this package effectively encodes when the team can raise the project's minimum PHP version. That is a real roadmap constraint worth tracking alongside the PHPUnit upgrade, not a separate line item.
• Risk posture. BSD-3-Clause, 7.4k stars (largely a reflection of PHPUnit's own footprint), single-maintainer governance, and a history of correctness fixes in edge-case traversal (#84 dropped directories during wildcard resolution; 7.0.1/7.0.2 addressed hidden directories, Windows path separators, and prefix-collision exclusions). This is inherited risk from the test framework, not incremental risk from a new vendor.

When to Consider This Package

Consider it (implicitly) when:

• You run PHPUnit — in which case you already have it, and the only action is to keep it a dev-only, transitive dependency and verify the PHPUnit major you adopt is compatible with your PHP version.
• You are building an internal tool that must resolve glob patterns (including ** globstar) and filter by suffix/prefix/exclude, and you specifically want the same traversal semantics as the test runner so local runs and CI agree.
• You need a lightweight, immutable filter chain (addSuffix/addPrefix/addExclude returning new instances) rather than a fully featured filesystem abstraction.

Look elsewhere when:

• The code ships to production. Use symfony/finder (already a Laravel dependency) — it is the ecosystem standard, handles symlinks/permissions/multi-condition filters, and has a stable public API.
• You need content-based filtering (matching inside files, not just names) — extend FilterIterator directly or build on Finder; chaining name filters will not get you there.
• You need API stability guarantees across PHP minors. This package bumps a major version per PHP minor, which makes it a poor choice for anything you intend to pin loosely.
• You are on an older release and rely on mixed file/directory wildcard matching — pre-5.1.1/6.0.1 had directory-dropping bugs. Any custom tool must pin ≥5.1.1.

How to Pitch It (Stakeholders)

To executives: This is a zero-cost, zero-procurement item. It is a BSD-3-Clause utility that already lives inside PHPUnit, which we already use — there is no new vendor, no license review, and no incremental spend. The only "decision" is to leave it alone. The one thing worth putting on the radar is that its version tracks PHP releases, so it will surface as a small gating item during our next PHP upgrade; that work is already implied by the PHPUnit upgrade we would be doing anyway.

To engineering: Do not add phpunit/php-file-iterator to composer.json directly — consume it transitively through PHPUnit and keep it development-only. For any file enumeration in application or tooling code we own, use Symfony Finder for consistency with the rest of the Laravel stack. If we ever build internal tooling that must mirror the test runner's glob/directory semantics, this gives us those semantics for free — but note the API is unstable by design (major bump per PHP minor) and the traversal logic has had edge-case fixes as recently as 7.0.2, so pin and test rather than assume.