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()

Constructor.

static Finder
create()

Creates a new Finder.

addAdapter(AdapterInterface $adapter, integer $priority)

Registers a finder engine implementation.

useBestAdapter()

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

setAdapter(string $name)

Selects the adapter to use.

removeAdapters()

Removes all adapters registered in the finder.

getAdapters()

Returns registered adapters ordered by priority without extra information.

directories()

Restricts the matching to directories only.

files()

Restricts the matching to files only.

depth(int $level)

Adds tests for the directory depth.

date(string $date)

Adds tests for file dates (last modified).

name(string $pattern)

Adds rules that files must match.

notName(string $pattern)

Adds rules that files must not match.

contains(string $pattern)

Adds tests that file contents must match.

notContains(string $pattern)

Adds tests that file contents must not match.

path(string $pattern)

Adds rules that filenames must match.

notPath(string $pattern)

Adds rules that filenames must not match.

size(string $size)

Adds tests for file sizes.

exclude(string|array $dirs)

Excludes directories.

ignoreDotFiles(Boolean $ignoreDotFiles)

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

ignoreVCS(Boolean $ignoreVCS)

Forces the finder to ignore version control directories.

static 
addVCSPattern(string|string[] $pattern)

Adds VCS patterns.

sort(Closure $closure)

Sorts files and directories by an anonymous function.

sortByName()

Sorts files and directories by name.

sortByType()

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

sortByAccessedTime()

Sorts files and directories by the last accessed time.

sortByChangedTime()

Sorts files and directories by the last inode changed time.

sortByModifiedTime()

Sorts files and directories by the last modified time.

filter(Closure $closure)

Filters the iterator with an anonymous function.

followLinks()

Forces the following of symlinks.

ignoreUnreadableDirs(boolean $ignore = true)

Tells finder to ignore unreadable directories.

in(string|array $dirs)

Searches files and directories which match defined rules.

getIterator()

Returns an Iterator for the current Finder configuration.

append(mixed $iterator)

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

int
count()

Counts all the results collected by the iterators.

Details

at line line 65
__construct()

Constructor.

at line line 84
static Finder create()

Creates a new Finder.

Return Value

Finder A new Finder instance

at line line 97
Finder addAdapter(AdapterInterface $adapter, integer $priority)

Registers a finder engine implementation.

Parameters

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

Return Value

Finder The current Finder instance

at line line 113
Finder useBestAdapter()

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

Return Value

Finder The current Finder instance

at line line 129
Finder setAdapter(string $name)

Selects the adapter to use.

Parameters

string $name

Return Value

Finder The current Finder instance

Exceptions

InvalidArgumentException

at line line 146
Finder removeAdapters()

Removes all adapters registered in the finder.

Return Value

Finder The current Finder instance

at line line 158
AdapterInterface[] getAdapters()

Returns registered adapters ordered by priority without extra information.

Return Value

AdapterInterface[]

at line line 172
Finder directories()

Restricts the matching to directories only.

Return Value

Finder The current Finder instance

at line line 186
Finder files()

Restricts the matching to files only.

Return Value

Finder The current Finder instance

at line line 210
Finder depth(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

int $level The depth level expression

Return Value

Finder The current Finder instance

See also

Symfony\Component\Finder\Iterator\DepthRangeFilterIterator
Symfony\Component\Finder\Comparator\NumberComparator

at line line 237
Finder 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 rage string

Return Value

Finder The current Finder instance

See also

strtotime
Symfony\Component\Finder\Iterator\DateRangeFilterIterator
Symfony\Component\Finder\Comparator\DateComparator

at line line 261
Finder 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

Finder The current Finder instance

See also

Symfony\Component\Finder\Iterator\FilenameFilterIterator

at line line 279
Finder notName(string $pattern)

Adds rules that files must not match.

Parameters

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

Return Value

Finder The current Finder instance

See also

Symfony\Component\Finder\Iterator\FilenameFilterIterator

at line line 300
Finder 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

Finder The current Finder instance

See also

Symfony\Component\Finder\Iterator\FilecontentFilterIterator

at line line 321
Finder 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

Finder The current Finder instance

See also

Symfony\Component\Finder\Iterator\FilecontentFilterIterator

at line line 344
Finder 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

Finder The current Finder instance

See also

Symfony\Component\Finder\Iterator\FilenameFilterIterator

at line line 367
Finder 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

Finder The current Finder instance

See also

Symfony\Component\Finder\Iterator\FilenameFilterIterator

at line line 390
Finder size(string $size)

Adds tests for file sizes.

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

Parameters

string $size A size range string

Return Value

Finder The current Finder instance

See also

Symfony\Component\Finder\Iterator\SizeRangeFilterIterator
Symfony\Component\Finder\Comparator\NumberComparator

at line line 408
Finder exclude(string|array $dirs)

Excludes directories.

Parameters

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

Return Value

Finder The current Finder instance

See also

Symfony\Component\Finder\Iterator\ExcludeDirectoryFilterIterator

at line line 426
Finder ignoreDotFiles(Boolean $ignoreDotFiles)

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

Parameters

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

Return Value

Finder The current Finder instance

See also

Symfony\Component\Finder\Iterator\ExcludeDirectoryFilterIterator

at line line 448
Finder ignoreVCS(Boolean $ignoreVCS)

Forces the finder to ignore version control directories.

Parameters

Boolean $ignoreVCS Whether to exclude VCS files or not

Return Value

Finder The current Finder instance

See also

Symfony\Component\Finder\Iterator\ExcludeDirectoryFilterIterator

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

Adds VCS patterns.

Parameters

string|string[] $pattern VCS patterns to ignore

See also

ignoreVCS

at line line 490
Finder 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 An anonymous function

Return Value

Finder The current Finder instance

See also

Symfony\Component\Finder\Iterator\SortableIterator

at line line 508
Finder 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

Finder The current Finder instance

See also

Symfony\Component\Finder\Iterator\SortableIterator

at line line 526
Finder 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

Finder The current Finder instance

See also

Symfony\Component\Finder\Iterator\SortableIterator

at line line 546
Finder 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

Finder The current Finder instance

See also

Symfony\Component\Finder\Iterator\SortableIterator

at line line 568
Finder 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

Finder The current Finder instance

See also

Symfony\Component\Finder\Iterator\SortableIterator

at line line 588
Finder 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

Finder The current Finder instance

See also

Symfony\Component\Finder\Iterator\SortableIterator

at line line 609
Finder 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 An anonymous function

Return Value

Finder The current Finder instance

See also

Symfony\Component\Finder\Iterator\CustomFilterIterator

Forces the following of symlinks.

Return Value

Finder The current Finder instance

at line line 639
Finder ignoreUnreadableDirs(boolean $ignore = true)

Tells finder to ignore unreadable directories.

By default, scanning unreadable directories content throws an AccessDeniedException.

Parameters

boolean $ignore

Return Value

Finder The current Finder instance

at line line 657
Finder 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

Finder The current Finder instance

Exceptions

InvalidArgumentException if one of the directories does not exist

at line line 685
Iterator getIterator()

Returns an Iterator for the current Finder configuration.

This method implements the IteratorAggregate interface.

Return Value

Iterator An iterator

Exceptions

LogicException if the in() method has not been called

at line line 718
Finder append(mixed $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

mixed $iterator

Return Value

Finder The finder

Exceptions

InvalidArgumentException When the given argument is not iterable.

at line line 742
int count()

Counts all the results collected by the iterators.

Return Value

int