Finder

__construct()

Constructor.

static Finder create()

Creates a new Finder.

Return Value

Finder

A new Finder instance

Finder directories()

Restricts the matching to directories only.

Return Value

Finder

The current Finder instance

Finder files()

Restricts the matching to files only.

Return Value

Finder

The current Finder instance

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

DepthRangeFilterIterator
NumberComparator

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 range string

Return Value

Finder

The current Finder instance

See also

strtotime
DateRangeFilterIterator
DateComparator

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

FilenameFilterIterator

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

FilenameFilterIterator

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

FilecontentFilterIterator

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

FilecontentFilterIterator

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

FilenameFilterIterator

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

FilenameFilterIterator

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

SizeRangeFilterIterator
NumberComparator

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

ExcludeDirectoryFilterIterator

Finder ignoreDotFiles(bool $ignoreDotFiles)

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

Parameters

bool

$ignoreDotFiles

Whether to exclude "hidden" files or not

Return Value

Finder

The current Finder instance

See also

ExcludeDirectoryFilterIterator

Finder ignoreVCS(bool $ignoreVCS)

Forces the finder to ignore version control directories.

Parameters

bool

$ignoreVCS

Whether to exclude VCS files or not

Return Value

Finder

The current Finder instance

See also

ExcludeDirectoryFilterIterator

static addVCSPattern(string|string[] $pattern)

Adds VCS patterns.

Parameters

string|string[]

$pattern

VCS patterns to ignore

See also

ignoreVCS()

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

SortableIterator

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

SortableIterator

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

SortableIterator

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

SortableIterator

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

SortableIterator

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

SortableIterator

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

CustomFilterIterator

Finder followLinks()

Forces the following of symlinks.

Return Value

Finder

The current Finder instance

Finder ignoreUnreadableDirs(bool $ignore = true)

Tells finder to ignore unreadable directories.

By default, scanning unreadable directories content throws an AccessDeniedException.

Parameters

bool

$ignore

Return Value

Finder

The current Finder instance

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

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

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.

int count()

Counts all the results collected by the iterators.

Return Value

int