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

Table of Contents

Interfaces

IteratorAggregate
Countable

Constants

IGNORE_DOT_FILES  = 2
IGNORE_VCS_FILES  = 1
IGNORE_VCS_IGNORED_FILES  = 4

Properties

$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

Methods

__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 = []

$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 = []

$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

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

append()

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

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

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

Parameters
$iterator : iterable<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
Attributes
#[ReturnTypeWillChange]
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|array<string|int, SplFileInfo>

This method implements the IteratorAggregate interface.

Tags
throws
LogicException

if the in() method has not been called

Attributes
#[ReturnTypeWillChange]
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

Whether to exclude "hidden" files or not

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

Whether to exclude VCS files or not

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() : $this

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

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 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results