class Finder implements IteratorAggregate, Countable

Finder allows to build rules to find files and directories.

It is a thin wrapper around several specialized iterator classes.

All rules may be invoked several times.

All methods return the current Finder object to allow easy chaining:

$finder = Finder::create()->files()->name('*.php')->in(__DIR__);

Constants

IGNORE_VCS_FILES

IGNORE_DOT_FILES

Methods

__construct()

No description

static Finder
create()

Creates a new Finder.

$this
addAdapter(AdapterInterface $adapter, int $priority = 0) deprecated

Registers a finder engine implementation.

$this
useBestAdapter() deprecated

Sets the selected adapter to the best one according to the current platform the code is run on.

$this
setAdapter(string $name) deprecated

Selects the adapter to use.

$this
removeAdapters() deprecated

Removes all adapters registered in the finder.

getAdapters() deprecated

Returns registered adapters ordered by priority without extra information.

$this
directories()

Restricts the matching to directories only.

$this
files()

Restricts the matching to files only.

$this
depth(string|int $level)

Adds tests for the directory depth.

$this
date(string $date)

Adds tests for file dates (last modified).

$this
name(string $pattern)

Adds rules that files must match.

$this
notName(string $pattern)

Adds rules that files must not match.

$this
contains(string $pattern)

Adds tests that file contents must match.

$this
notContains(string $pattern)

Adds tests that file contents must not match.

$this
path(string $pattern)

Adds rules that filenames must match.

$this
notPath(string $pattern)

Adds rules that filenames must not match.

$this
size(string|int $size)

Adds tests for file sizes.

$this
exclude(string|array $dirs)

Excludes directories.

$this
ignoreDotFiles(bool $ignoreDotFiles)

Excludes "hidden" directories and files (starting with a dot).

$this
ignoreVCS(bool $ignoreVCS)

Forces the finder to ignore version control directories.

static 
addVCSPattern(string|string[] $pattern)

Adds VCS patterns.

$this
sort(Closure $closure)

Sorts files and directories by an anonymous function.

$this
sortByName()

Sorts files and directories by name.

$this
sortByType()

Sorts files and directories by type (directories before files), then by name.

$this
sortByAccessedTime()

Sorts files and directories by the last accessed time.

$this
sortByChangedTime()

Sorts files and directories by the last inode changed time.

$this
sortByModifiedTime()

Sorts files and directories by the last modified time.

$this
filter(Closure $closure)

Filters the iterator with an anonymous function.

$this
followLinks()

Forces the following of symlinks.

$this
ignoreUnreadableDirs(bool $ignore = true)

Tells finder to ignore unreadable directories.

$this
in(string|array $dirs)

Searches files and directories which match defined rules.

getIterator()

Returns an Iterator for the current Finder configuration.

$this
append(iterable $iterator)

Appends an existing set of files/directories to the finder.

int
count()

Counts all the results collected by the iterators.

Details

at line 70
__construct()

at line 80
static Finder create()

Creates a new Finder.

Return Value

Finder

at line 95
$this addAdapter(AdapterInterface $adapter, int $priority = 0) deprecated

deprecated since 2.8, to be removed in 3.0.

Registers a finder engine implementation.

Parameters

AdapterInterface $adapter An adapter instance
int $priority Highest is selected first

Return Value

$this

at line 117
$this useBestAdapter() deprecated

deprecated since 2.8, to be removed in 3.0.

Sets the selected adapter to the best one according to the current platform the code is run on.

Return Value

$this

at line 139
$this setAdapter(string $name) deprecated

deprecated since 2.8, to be removed in 3.0.

Selects the adapter to use.

Parameters

string $name

Return Value

$this

Exceptions

InvalidArgumentException

at line 162
$this removeAdapters() deprecated

deprecated since 2.8, to be removed in 3.0.

Removes all adapters registered in the finder.

Return Value

$this

at line 178
AdapterInterface[] getAdapters() deprecated

deprecated since 2.8, to be removed in 3.0.

Returns registered adapters ordered by priority without extra information.

Return Value

AdapterInterface[]

at line 194
$this directories()

Restricts the matching to directories only.

Return Value

$this

at line 206
$this files()

Restricts the matching to files only.

Return Value

$this

at line 228
$this depth(string|int $level)

Adds tests for the directory depth.

Usage:

$finder->depth('> 1') // the Finder will start matching at level 1.
$finder->depth('< 3') // the Finder will descend at most 3 levels of directories below the starting point.

Parameters

string|int $level The depth level expression

Return Value

$this

See also

DepthRangeFilterIterator
NumberComparator

at line 253
$this date(string $date)

Adds tests for file dates (last modified).

The date must be something that strtotime() is able to parse:

$finder->date('since yesterday');
$finder->date('until 2 days ago');
$finder->date('> now - 2 hours');
$finder->date('>= 2005-10-15');

Parameters

string $date A date range string

Return Value

$this

See also

strtotime
DateRangeFilterIterator
DateComparator

at line 275
$this name(string $pattern)

Adds rules that files must match.

You can use patterns (delimited with / sign), globs or simple strings.

$finder->name('*.php')
$finder->name('/\.php$/') // same as above
$finder->name('test.php')

Parameters

string $pattern A pattern (a regexp, a glob, or a string)

Return Value

$this

See also

FilenameFilterIterator

at line 291
$this notName(string $pattern)

Adds rules that files must not match.

Parameters

string $pattern A pattern (a regexp, a glob, or a string)

Return Value

$this

See also

FilenameFilterIterator

at line 312
$this contains(string $pattern)

Adds tests that file contents must match.

Strings or PCRE patterns can be used:

$finder->contains('Lorem ipsum')
$finder->contains('/Lorem ipsum/i')

Parameters

string $pattern A pattern (string or regexp)

Return Value

$this

See also

FilecontentFilterIterator

at line 333
$this notContains(string $pattern)

Adds tests that file contents must not match.

Strings or PCRE patterns can be used:

$finder->notContains('Lorem ipsum')
$finder->notContains('/Lorem ipsum/i')

Parameters

string $pattern A pattern (string or regexp)

Return Value

$this

See also

FilecontentFilterIterator

at line 356
$this path(string $pattern)

Adds rules that filenames must match.

You can use patterns (delimited with / sign) or simple strings.

$finder->path('some/special/dir')
$finder->path('/some\/special\/dir/') // same as above

Use only / as dirname separator.

Parameters

string $pattern A pattern (a regexp or a string)

Return Value

$this

See also

FilenameFilterIterator

at line 379
$this notPath(string $pattern)

Adds rules that filenames must not match.

You can use patterns (delimited with / sign) or simple strings.

$finder->notPath('some/special/dir')
$finder->notPath('/some\/special\/dir/') // same as above

Use only / as dirname separator.

Parameters

string $pattern A pattern (a regexp or a string)

Return Value

$this

See also

FilenameFilterIterator

at line 400
$this size(string|int $size)

Adds tests for file sizes.

$finder->size('> 10K'); $finder->size('<= 1Ki'); $finder->size(4);

Parameters

string|int $size A size range string or an integer

Return Value

$this

See also

SizeRangeFilterIterator
NumberComparator

at line 420
$this exclude(string|array $dirs)

Excludes directories.

Directories passed as argument must be relative to the ones defined with the in() method. For example:

$finder->in(__DIR__)->exclude('ruby');

Parameters

string|array $dirs A directory path or an array of directories

Return Value

$this

See also

ExcludeDirectoryFilterIterator

at line 438
$this ignoreDotFiles(bool $ignoreDotFiles)

Excludes "hidden" directories and files (starting with a dot).

This option is enabled by default.

Parameters

bool $ignoreDotFiles Whether to exclude "hidden" files or not

Return Value

$this

See also

ExcludeDirectoryFilterIterator

at line 460
$this ignoreVCS(bool $ignoreVCS)

Forces the finder to ignore version control directories.

This option is enabled by default.

Parameters

bool $ignoreVCS Whether to exclude VCS files or not

Return Value

$this

See also

ExcludeDirectoryFilterIterator

at line 478
static addVCSPattern(string|string[] $pattern)

Adds VCS patterns.

Parameters

string|string[] $pattern VCS patterns to ignore

See also

ignoreVCS()

at line 498
$this sort(Closure $closure)

Sorts files and directories by an anonymous function.

The anonymous function receives two \SplFileInfo instances to compare.

This can be slow as all the matching files and directories must be retrieved for comparison.

Parameters

Closure $closure

Return Value

$this

See also

SortableIterator

at line 514
$this sortByName()

Sorts files and directories by name.

This can be slow as all the matching files and directories must be retrieved for comparison.

Return Value

$this

See also

SortableIterator

at line 530
$this sortByType()

Sorts files and directories by type (directories before files), then by name.

This can be slow as all the matching files and directories must be retrieved for comparison.

Return Value

$this

See also

SortableIterator

at line 548
$this sortByAccessedTime()

Sorts files and directories by the last accessed time.

This is the time that the file was last accessed, read or written to.

This can be slow as all the matching files and directories must be retrieved for comparison.

Return Value

$this

See also

SortableIterator

at line 568
$this sortByChangedTime()

Sorts files and directories by the last inode changed time.

This is the time that the inode information was last modified (permissions, owner, group or other metadata).

On Windows, since inode is not available, changed time is actually the file creation time.

This can be slow as all the matching files and directories must be retrieved for comparison.

Return Value

$this

See also

SortableIterator

at line 586
$this sortByModifiedTime()

Sorts files and directories by the last modified time.

This is the last time the actual contents of the file were last modified.

This can be slow as all the matching files and directories must be retrieved for comparison.

Return Value

$this

See also

SortableIterator

at line 603
$this filter(Closure $closure)

Filters the iterator with an anonymous function.

The anonymous function receives a \SplFileInfo and must return false to remove files.

Parameters

Closure $closure

Return Value

$this

See also

CustomFilterIterator

Forces the following of symlinks.

Return Value

$this

at line 631
$this ignoreUnreadableDirs(bool $ignore = true)

Tells finder to ignore unreadable directories.

By default, scanning unreadable directories content throws an AccessDeniedException.

Parameters

bool $ignore

Return Value

$this

at line 647
$this in(string|array $dirs)

Searches files and directories which match defined rules.

Parameters

string|array $dirs A directory path or an array of directories

Return Value

$this

Exceptions

InvalidArgumentException if one of the directories does not exist

at line 675
Iterator|SplFileInfo[] getIterator()

Returns an Iterator for the current Finder configuration.

This method implements the IteratorAggregate interface.

Return Value

Iterator|SplFileInfo[] An iterator

Exceptions

LogicException if the in() method has not been called

at line 708
$this append(iterable $iterator)

Appends an existing set of files/directories to the finder.

The set can be another Finder, an Iterator, an IteratorAggregate, or even a plain array.

Parameters

iterable $iterator

Return Value

$this

Exceptions

InvalidArgumentException when the given argument is not iterable

at line 732
int count()

Counts all the results collected by the iterators.

Return Value

int