Documentation

Finder
in package
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 chaining:

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

Fabien Potencier fabien@symfony.com

implements

\IteratorAggregate<string, SplFileInfo>

Interfaces, Classes, Traits and Enums

IteratorAggregate
Countable

Table of Contents

IGNORE_DOT_FILES  = 2
IGNORE_VCS_FILES  = 1
IGNORE_VCS_IGNORED_FILES  = 4
$contains  : array<string|int, mixed>
$dates  : array<string|int, mixed>
$depths  : array<string|int, mixed>
$dirs  : array<string|int, mixed>
$exclude  : array<string|int, mixed>
$filters  : array<string|int, mixed>
$followLinks  : bool
$ignore  : int
$ignoreUnreadableDirs  : bool
$iterators  : array<string|int, mixed>
$mode  : int
$names  : array<string|int, mixed>
$notContains  : array<string|int, mixed>
$notNames  : array<string|int, mixed>
$notPaths  : array<string|int, mixed>
$paths  : array<string|int, mixed>
$reverseSorting  : bool
$sizes  : array<string|int, mixed>
$sort  : Closure|int|false
$vcsPatterns  : array<string|int, mixed>
__construct()  : mixed
addVCSPattern()  : mixed
Adds VCS patterns.
append()  : $this
Appends an existing set of files/directories to the finder.
contains()  : $this
Adds tests that file contents must match.
count()  : int
Counts all the results collected by the iterators.
create()  : static
Creates a new Finder.
date()  : $this
Adds tests for file dates (last modified).
depth()  : $this
Adds tests for the directory depth.
directories()  : $this
Restricts the matching to directories only.
exclude()  : $this
Excludes directories.
files()  : $this
Restricts the matching to files only.
filter()  : $this
Filters the iterator with an anonymous function.
followLinks()  : $this
Forces the following of symlinks.
getIterator()  : Iterator<string, SplFileInfo>
Returns an Iterator for the current Finder configuration.
hasResults()  : bool
Check if any results were found.
ignoreDotFiles()  : $this
Excludes "hidden" directories and files (starting with a dot).
ignoreUnreadableDirs()  : $this
Tells finder to ignore unreadable directories.
ignoreVCS()  : $this
Forces the finder to ignore version control directories.
ignoreVCSIgnored()  : $this
Forces Finder to obey .gitignore and ignore files based on rules listed there.
in()  : $this
Searches files and directories which match defined rules.
name()  : $this
Adds rules that files must match.
notContains()  : $this
Adds tests that file contents must not match.
notName()  : $this
Adds rules that files must not match.
notPath()  : $this
Adds rules that filenames must not match.
path()  : $this
Adds rules that filenames must match.
reverseSorting()  : $this
Reverses the sorting.
size()  : $this
Adds tests for file sizes.
sort()  : $this
Sorts files and directories by an anonymous function.
sortByAccessedTime()  : $this
Sorts files and directories by the last accessed time.
sortByChangedTime()  : $this
Sorts files and directories by the last inode changed time.
sortByModifiedTime()  : $this
Sorts files and directories by the last modified time.
sortByName()  : $this
Sorts files and directories by name.
sortByType()  : $this
Sorts files and directories by type (directories before files), then by name.
normalizeDir()  : string
Normalizes given directory names by removing trailing slashes.
searchInDirectory()  : Iterator

Constants

IGNORE_DOT_FILES

public mixed IGNORE_DOT_FILES = 2

IGNORE_VCS_FILES

public mixed IGNORE_VCS_FILES = 1

IGNORE_VCS_IGNORED_FILES

public mixed IGNORE_VCS_IGNORED_FILES = 4

Properties

$contains

private array<string|int, mixed> $contains = []

$dates

private array<string|int, mixed> $dates = []

$depths

private array<string|int, mixed> $depths = []

$dirs

private array<string|int, mixed> $dirs = []

$exclude

private array<string|int, mixed> $exclude = []

$filters

private array<string|int, mixed> $filters = []

$followLinks

private bool $followLinks = false

$ignoreUnreadableDirs

private bool $ignoreUnreadableDirs = false

$iterators

private array<string|int, mixed> $iterators = []

$names

private array<string|int, mixed> $names = []

$notContains

private array<string|int, mixed> $notContains = []

$notNames

private array<string|int, mixed> $notNames = []

$notPaths

private array<string|int, mixed> $notPaths = []

$paths

private array<string|int, mixed> $paths = []

$reverseSorting

private bool $reverseSorting = false

$sizes

private array<string|int, mixed> $sizes = []

$sort

private Closure|int|false $sort = false

$vcsPatterns

private static array<string|int, mixed> $vcsPatterns = ['.svn', '_svn', 'CVS', '_darcs', '.arch-params', '.monotone', '.bzr', '.git', '.hg']

Methods

__construct()

public __construct() : mixed
Return values
mixed —

addVCSPattern()

Adds VCS patterns.

public static addVCSPattern(string|array<string|int, string> $pattern) : mixed
Parameters
$pattern : string|array<string|int, string>

VCS patterns to ignore

Tags
see
ignoreVCS()
Return values
mixed —

append()

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

public append(iteratable<string|int, mixed> $iterator) : $this

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

Parameters
$iterator : iteratable<string|int, mixed>
Tags
throws
InvalidArgumentException

when the given argument is not iterable

Return values
$this —

contains()

Adds tests that file contents must match.

public contains(string|array<string|int, string> $patterns) : $this

Strings or PCRE patterns can be used:

$finder->contains('Lorem ipsum') $finder->contains('/Lorem ipsum/i') $finder->contains(['dolor', '/ipsum/i'])

Parameters
$patterns : string|array<string|int, string>

A pattern (string or regexp) or an array of patterns

Tags
see
FilecontentFilterIterator
Return values
$this —

count()

Counts all the results collected by the iterators.

public count() : int
Return values
int —

create()

Creates a new Finder.

public static create() : static
Return values
static —

date()

Adds tests for file dates (last modified).

public date(string|array<string|int, string> $dates) : $this

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'); $finder->date(['>= 2005-10-15', '<= 2006-05-27']);

Parameters
$dates : string|array<string|int, string>

A date range string or an array of date ranges

Tags
see
strtotime
see
DateRangeFilterIterator
see
DateComparator
Return values
$this —

depth()

Adds tests for the directory depth.

public depth(string|int|array<string|int, string>|array<string|int, int> $levels) : $this

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. $finder->depth(['>= 1', '< 3'])

Parameters
$levels : string|int|array<string|int, string>|array<string|int, int>

The depth level expression or an array of depth levels

Tags
see
DepthRangeFilterIterator
see
NumberComparator
Return values
$this —

directories()

Restricts the matching to directories only.

public directories() : $this
Return values
$this —

exclude()

Excludes directories.

public exclude(string|array<string|int, mixed> $dirs) : $this

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

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

Parameters
$dirs : string|array<string|int, mixed>

A directory path or an array of directories

Tags
see
ExcludeDirectoryFilterIterator
Return values
$this —

files()

Restricts the matching to files only.

public files() : $this
Return values
$this —

filter()

Filters the iterator with an anonymous function.

public filter(Closure $closure) : $this

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

Parameters
$closure : Closure
Tags
see
CustomFilterIterator
Return values
$this —

followLinks()

Forces the following of symlinks.

public followLinks() : $this
Return values
$this —

getIterator()

Returns an Iterator for the current Finder configuration.

public getIterator() : Iterator<string, SplFileInfo>

This method implements the IteratorAggregate interface.

Tags
throws
LogicException

if the in() method has not been called

Return values
Iterator<string, SplFileInfo> —

hasResults()

Check if any results were found.

public hasResults() : bool
Return values
bool —

ignoreDotFiles()

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

public ignoreDotFiles(bool $ignoreDotFiles) : $this

This option is enabled by default.

Parameters
$ignoreDotFiles : bool
Tags
see
ExcludeDirectoryFilterIterator
Return values
$this —

ignoreUnreadableDirs()

Tells finder to ignore unreadable directories.

public ignoreUnreadableDirs([bool $ignore = true ]) : $this

By default, scanning unreadable directories content throws an AccessDeniedException.

Parameters
$ignore : bool = true
Return values
$this —

ignoreVCS()

Forces the finder to ignore version control directories.

public ignoreVCS(bool $ignoreVCS) : $this

This option is enabled by default.

Parameters
$ignoreVCS : bool
Tags
see
ExcludeDirectoryFilterIterator
Return values
$this —

ignoreVCSIgnored()

Forces Finder to obey .gitignore and ignore files based on rules listed there.

public ignoreVCSIgnored(bool $ignoreVCSIgnored) : $this

This option is disabled by default.

Parameters
$ignoreVCSIgnored : bool
Return values
$this —

in()

Searches files and directories which match defined rules.

public in(string|array<string|int, string> $dirs) : $this
Parameters
$dirs : string|array<string|int, string>

A directory path or an array of directories

Tags
throws
DirectoryNotFoundException

if one of the directories does not exist

Return values
$this —

name()

Adds rules that files must match.

public name(string|array<string|int, string> $patterns) : $this

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

$finder->name('*.php') $finder->name('/.php$/') // same as above $finder->name('test.php') $finder->name(['test.py', 'test.php'])

Parameters
$patterns : string|array<string|int, string>

A pattern (a regexp, a glob, or a string) or an array of patterns

Tags
see
FilenameFilterIterator
Return values
$this —

notContains()

Adds tests that file contents must not match.

public notContains(string|array<string|int, string> $patterns) : $this

Strings or PCRE patterns can be used:

$finder->notContains('Lorem ipsum') $finder->notContains('/Lorem ipsum/i') $finder->notContains(['lorem', '/dolor/i'])

Parameters
$patterns : string|array<string|int, string>

A pattern (string or regexp) or an array of patterns

Tags
see
FilecontentFilterIterator
Return values
$this —

notName()

Adds rules that files must not match.

public notName(string|array<string|int, string> $patterns) : $this
Parameters
$patterns : string|array<string|int, string>

A pattern (a regexp, a glob, or a string) or an array of patterns

Tags
see
FilenameFilterIterator
Return values
$this —

notPath()

Adds rules that filenames must not match.

public notPath(string|array<string|int, string> $patterns) : $this

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

$finder->notPath('some/special/dir')
$finder->notPath('/some\/special\/dir/') // same as above
$finder->notPath(['some/file.txt', 'another/file.log'])

Use only / as dirname separator.

Parameters
$patterns : string|array<string|int, string>

A pattern (a regexp or a string) or an array of patterns

Tags
see
FilenameFilterIterator
Return values
$this —

path()

Adds rules that filenames must match.

public path(string|array<string|int, string> $patterns) : $this

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

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

Use only / as dirname separator.

Parameters
$patterns : string|array<string|int, string>

A pattern (a regexp or a string) or an array of patterns

Tags
see
FilenameFilterIterator
Return values
$this —

reverseSorting()

Reverses the sorting.

public reverseSorting() : $this
Return values
$this —

size()

Adds tests for file sizes.

public size(string|int|array<string|int, string>|array<string|int, int> $sizes) : $this

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

Parameters
$sizes : string|int|array<string|int, string>|array<string|int, int>

A size range string or an integer or an array of size ranges

Tags
see
SizeRangeFilterIterator
see
NumberComparator
Return values
$this —

sort()

Sorts files and directories by an anonymous function.

public sort(Closure $closure) : $this

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
Tags
see
SortableIterator
Return values
$this —

sortByAccessedTime()

Sorts files and directories by the last accessed time.

public sortByAccessedTime() : $this

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.

Tags
see
SortableIterator
Return values
$this —

sortByChangedTime()

Sorts files and directories by the last inode changed time.

public sortByChangedTime() : $this

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.

Tags
see
SortableIterator
Return values
$this —

sortByModifiedTime()

Sorts files and directories by the last modified time.

public sortByModifiedTime() : $this

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.

Tags
see
SortableIterator
Return values
$this —

sortByName()

Sorts files and directories by name.

public sortByName([bool $useNaturalSort = false ]) : $this

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

Parameters
$useNaturalSort : bool = false
Tags
see
SortableIterator
Return values
$this —

sortByType()

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

public sortByType() : $this

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

Tags
see
SortableIterator
Return values
$this —

normalizeDir()

Normalizes given directory names by removing trailing slashes.

private normalizeDir(string $dir) : string

Excluding: (s)ftp:// or ssh2.(s)ftp:// wrapper

Parameters
$dir : string
Return values
string —

searchInDirectory()

private searchInDirectory(string $dir) : Iterator
Parameters
$dir : string
Return values
Iterator —

Search results