Php File Iterator Laravel Package

Getting Started

Start by installing the package via Composer: composer require phpunit/php-file-iterator. Its core purpose is to traverse directories and filter files—ideal for build tools, test runners, or static analysis tools that need to operate on specific file sets. The first use case is typically collecting PHP files in a project:

use PHPUnit\File\Iterator;

$iterator = (new Iterator)->getIterator('/path/to/src', ['php']);
foreach ($iterator as $file) {
    echo $file->getPathname() . PHP_EOL;
}

Check the README and source for quick reference on class names (Iterator, Factory) and basic API patterns.

Implementation Patterns

• Using Factory for complex globs: Prefer Factory::getIterator() when using glob patterns (including ** globstar syntax since v5.1.0):

  $iterator = Factory::getIterator(['/path/to/**/{src,tests}/*.php']);
  

• Programmatic filtering: Chain conditions via addExclude()/addSuffix()/addPrefix() on an Iterator instance:

  $iterator = (new Iterator)->addSuffix(['php'])->addPrefix(['Abstract', 'Test']);
  $iterator = $iterator->addExclude(['*/.git/*', 'vendor/*']);
  

• Integrating with existing tools: Commonly used by PHPUnit (via phpunit/php-code-coverage), Psalm, and custom tooling to prepare file lists before parsing or linting. Wrap your own RecursiveDirectoryIterator or RecursiveIteratorIterator if needed for extended context.

Gotchas and Tips

• Globstar behavior: ** requires path separators on both sides to be recognized as recursive (e.g., src/**/*.php works; **.php does not). From v5.1+, test with echo $pattern; in debug mode to confirm parsing.
• Case sensitivity: On Windows/macOS with case-insensitive filesystems, paths may appear differently depending on the underlying FS; normalize paths with realpath() if consistency matters.
• Directory traversal quirks: Older versions (pre-5.1.1/6.0.1) dropped directories during wildcard resolution (#84); ensure you’re on ≥5.1.1/6.0.1 if relying on mixed file/directory wildcard matching.
• PHP version support: v7.0.0+ drops PHP 8.3 support (readme date is futuristic; verify actual compatibility in real releases). Always match your target PHP version to supported releases.
• Extensibility: Extend FilterIterator directly for custom logic (e.g., content-based filtering) rather than chaining filters—Iterator is lightweight and immutable (methods return new instances), so avoid repeated operations in loops.