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
Interfaces, Classes and Traits
- IteratorAggregate
- Countable
Table of Contents
- IGNORE_DOT_FILES = 2
- IGNORE_VCS_FILES = 1
- IGNORE_VCS_IGNORED_FILES = 4
- $contains : mixed
- $dates : mixed
- $depths : mixed
- $dirs : mixed
- $exclude : mixed
- $filters : mixed
- $followLinks : mixed
- $ignore : mixed
- $ignoreUnreadableDirs : mixed
- $iterators : mixed
- $mode : mixed
- $names : mixed
- $notContains : mixed
- $notNames : mixed
- $notPaths : mixed
- $paths : mixed
- $reverseSorting : mixed
- $sizes : mixed
- $sort : mixed
- $vcsPatterns : 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|array<string|int, 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
mixed
$contains
= []
$dates
private
mixed
$dates
= []
$depths
private
mixed
$depths
= []
$dirs
private
mixed
$dirs
= []
$exclude
private
mixed
$exclude
= []
$filters
private
mixed
$filters
= []
$followLinks
private
mixed
$followLinks
= false
$ignore
private
mixed
$ignore
= 0
$ignoreUnreadableDirs
private
mixed
$ignoreUnreadableDirs
= false
$iterators
private
mixed
$iterators
= []
$mode
private
mixed
$mode
= 0
$names
private
mixed
$names
= []
$notContains
private
mixed
$notContains
= []
$notNames
private
mixed
$notNames
= []
$notPaths
private
mixed
$notPaths
= []
$paths
private
mixed
$paths
= []
$reverseSorting
private
mixed
$reverseSorting
= false
$sizes
private
mixed
$sizes
= []
$sort
private
mixed
$sort
= false
$vcsPatterns
private
static 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
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
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
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
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
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
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
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|array<string|int, SplFileInfo>
This method implements the IteratorAggregate interface.
Tags
Return values
Iterator|array<string|int, SplFileInfo> —An iterator
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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