Class Finder
Finder provides a fluent interface for finding files and directories.
Example usage:
// Find files
$finder = new Finder();
$files = $finder
->in('src')
->name('*.php')
->exclude('vendor')
->files();
foreach ($files as $file) {
echo $file->getPathname();
}
// Find directories
$directories = (new Finder())
->in('src')
->exclude('vendor')
->directories();
// Find both files and directories
$all = (new Finder())
->in('src')
->all();Property Summary
-
$depths protected
array<array{0: \Cake\Utility\Fs\Enum\DepthOperator, 1: int}>Depth conditions
-
$exclude protected
array<string>Directories to exclude
-
$filters protected
array<Closure(SplFileInfo, string): bool>Custom filter callbacks
-
$globPatterns protected
array<string>Glob patterns for full path matching
-
$ignoreHiddenFiles protected
boolWhether to ignore hidden files
-
$mode protected
Cake\Utility\Fs\Enum\FinderMode|nullThe iteration mode (files, directories, or all)
-
$names protected
array<string>Name patterns to match
-
$notNames protected
array<string>Name patterns to exclude
-
$notPathPatterns protected
array<string>Path patterns to exclude
-
$pathPatterns protected
array<string>Path patterns to include
-
$paths protected
array<string>Base paths to search in
-
$recursive protected
boolWhether to search recursively
Method Summary
-
all() public
Get both files and directories matching the criteria.
-
buildIterator() protected
Build an iterator chain with all configured filters.
-
depth() public
Add a depth condition.
-
directories() public
Get directories matching the criteria.
-
exclude() public
Exclude a directory from the search.
-
files() public
Get files matching the criteria.
-
filter() public
Add a custom filter callback.
-
ignoreHiddenFiles() public
Set whether to ignore hidden files and directories.
-
in() public
Add a path to search in.
-
iterate() protected
Iterate over items matching the criteria.
-
name() public
Add a name pattern to match.
-
notName() public
Add a name pattern that must not be matched.
-
notPath() public
Add a path pattern that must not be matched.
-
path() public
Add a path pattern that must be matched.
-
pattern() public
Add a glob pattern for full path matching.
-
recursive() public
Set whether to search recursively into subdirectories.
Method Detail
all() ¶ public
all(): Iterator<SplFileInfo>Get both files and directories matching the criteria.
Returns
Iterator<SplFileInfo>buildIterator() ¶ protected
buildIterator(string $path): Iterator<SplFileInfo>Build an iterator chain with all configured filters.
Parameters
-
string$path The directory path
Returns
Iterator<SplFileInfo>depth() ¶ public
depth(int $level, Cake\Utility\Fs\Enum\DepthOperator $operator = DepthOperator::EQUAL): $thisAdd a depth condition.
Parameters
-
int$level The depth level (0 = top-level directory)
-
Cake\Utility\Fs\Enum\DepthOperator$operator optional The comparison operator (default: EQUAL)
Returns
$thisdirectories() ¶ public
directories(): Iterator<SplFileInfo>Get directories matching the criteria.
Returns
Iterator<SplFileInfo>exclude() ¶ public
exclude(string $directory): $thisExclude a directory from the search.
Parameters
-
string$directory Directory name to exclude
Returns
$thisfiles() ¶ public
files(): Iterator<SplFileInfo>Get files matching the criteria.
Returns
Iterator<SplFileInfo>filter() ¶ public
filter(Closure(SplFileInfo, string): bool $callback): $thisAdd a custom filter callback.
The callback receives the SplFileInfo object and relative path, and should return true to include the file.
Example:
$finder->filter(fn(\SplFileInfo $file) => $file->getSize() > 1024);Parameters
-
Closure(SplFileInfo, string): bool$callback Filter callback
Returns
$thisignoreHiddenFiles() ¶ public
ignoreHiddenFiles(bool $ignore = true): $thisSet whether to ignore hidden files and directories.
Parameters
-
bool$ignore optional Whether to ignore hidden files
Returns
$thisin() ¶ public
in(string $path): $thisAdd a path to search in.
Parameters
-
string$path The directory path
Returns
$thisiterate() ¶ protected
iterate(): Iterator<SplFileInfo>Iterate over items matching the criteria.
Returns
Iterator<SplFileInfo>name() ¶ public
name(string $pattern): $thisAdd a name pattern to match.
Parameters
-
string$pattern Glob pattern (e.g., '*.php')
Returns
$thisnotName() ¶ public
notName(string $pattern): $thisAdd a name pattern that must not be matched.
Parameters
-
string$pattern Glob pattern to exclude (e.g., '.rb', 'Test.php')
Returns
$thisnotPath() ¶ public
notPath(string $pattern): $thisAdd a path pattern that must not be matched.
Parameters
-
string$pattern Path pattern to exclude
Returns
$thispath() ¶ public
path(string $pattern): $thisAdd a path pattern that must be matched.
Parameters
-
string$pattern Path pattern (e.g., 'Controller')
Returns
$thispattern() ¶ public
pattern(string $pattern): $thisAdd a glob pattern for full path matching.
Supports wildcards like src/**\/*.php for recursive matching.
Parameters
-
string$pattern Glob pattern (e.g., 'src/*\/.php', 'tests/*\/Test.php')
Returns
$thisrecursive() ¶ public
recursive(bool $recursive = true): $thisSet whether to search recursively into subdirectories.
Parameters
-
bool$recursive optional Whether to search recursively (default: true)
Returns
$this