Symfony Finder

The Symfony Finder component finds files and directories via an intuitive fluent interface. Instead of juggling glob patterns, recursive iterators, and stat calls, you chain expressive methods to describe exactly which files you want, by name, size, modification date, depth, path, or content.

Finder returns lazily-evaluated iterators of SplFileInfo objects, supports gitignore-style exclusion, custom filters and sorting, and works across the local filesystem as well as any stream wrapper. It is a widely reused building block for CLI tools, build scripts, and applications that need to traverse directory trees.

What You Get

• A fluent Finder API to filter by file name, extension, path, size, depth, and modification date
• Lazily-evaluated iterators yielding rich SplFileInfo objects for each match
• Gitignore-style ignoring and directory exclusion helpers
• Custom filter and sort callbacks, plus built-in sorting by name, type, size, or time
• Support for the local filesystem and any PHP stream wrapper or virtual filesystem

Common Use Cases

• Recursively locating source, config, or asset files that match name or extension patterns
• Filtering files by size, modification date, or directory depth in a build or cleanup script
• Excluding vendor, cache, or gitignored directories while scanning a project tree
• Iterating matched files with rich SplFileInfo metadata for further processing

Under The Hood

Architecture - The central Finder.php class accumulates criteria and, on iteration, composes a stack of lightweight Iterator decorators (FilenameFilterIterator, SizeRangeFilterIterator, DateRangeFilterIterator, DepthRangeFilterIterator, PathFilterIterator, ExcludeDirectoryFilterIterator, and sort iterators) over a recursive directory iterator. Glob.php and Gitignore.php translate patterns into regexes, and each result is wrapped in an enhanced SplFileInfo carrying its relative path.

Tech Stack - Pure PHP under the Symfony\Component\Finder namespace with PSR-4 autoloading and no runtime dependencies, targeting modern PHP. It is distributed as a read-only subtree split of the symfony/symfony monorepo.

Code Quality - The repository includes a thorough PHPUnit suite under Tests/ exercising each filter iterator, glob and gitignore translation, sorting, and stream-wrapper support, and adheres to Symfony’s strict coding standards and backward-compatibility promise.

API Design - The chainable Finder API is one of the most approachable in the component suite: method names map directly to intent (name, path, size, date, depth, exclude), the object is immutable per configuration step, and results iterate as familiar SplFileInfo objects, giving it a gentle learning curve well covered by the documentation.