Class Symfony\Component\Finder\Finder

InheritanceSymfony\Component\Finder\Finder
ImplementsCountable, IteratorAggregate

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

Public Methods

Hide inherited methods

MethodDescriptionDefined By
__construct() Constructor. Symfony\Component\Finder\Finder
addVCSPattern() Adds VCS patterns. Symfony\Component\Finder\Finder
append() Appends an existing set of files/directories to the finder. Symfony\Component\Finder\Finder
contains() Adds tests that file contents must match. Symfony\Component\Finder\Finder
count() Counts all the results collected by the iterators. Symfony\Component\Finder\Finder
create() Creates a new Finder. Symfony\Component\Finder\Finder
date() Adds tests for file dates (last modified). Symfony\Component\Finder\Finder
depth() Adds tests for the directory depth. Symfony\Component\Finder\Finder
directories() Restricts the matching to directories only. Symfony\Component\Finder\Finder
exclude() Excludes directories. Symfony\Component\Finder\Finder
files() Restricts the matching to files only. Symfony\Component\Finder\Finder
filter() Filters the iterator with an anonymous function. Symfony\Component\Finder\Finder
followLinks() Forces the following of symlinks. Symfony\Component\Finder\Finder
getIterator() Returns an Iterator for the current Finder configuration. Symfony\Component\Finder\Finder
ignoreDotFiles() Excludes "hidden" directories and files (starting with a dot). Symfony\Component\Finder\Finder
ignoreUnreadableDirs() Tells finder to ignore unreadable directories. Symfony\Component\Finder\Finder
ignoreVCS() Forces the finder to ignore version control directories. Symfony\Component\Finder\Finder
in() Searches files and directories which match defined rules. Symfony\Component\Finder\Finder
name() Adds rules that files must match. Symfony\Component\Finder\Finder
notContains() Adds tests that file contents must not match. Symfony\Component\Finder\Finder
notName() Adds rules that files must not match. Symfony\Component\Finder\Finder
notPath() Adds rules that filenames must not match. Symfony\Component\Finder\Finder
path() Adds rules that filenames must match. Symfony\Component\Finder\Finder
size() Adds tests for file sizes. Symfony\Component\Finder\Finder
sort() Sorts files and directories by an anonymous function. Symfony\Component\Finder\Finder
sortByAccessedTime() Sorts files and directories by the last accessed time. Symfony\Component\Finder\Finder
sortByChangedTime() Sorts files and directories by the last inode changed time. Symfony\Component\Finder\Finder
sortByModifiedTime() Sorts files and directories by the last modified time. Symfony\Component\Finder\Finder
sortByName() Sorts files and directories by name. Symfony\Component\Finder\Finder
sortByType() Sorts files and directories by type (directories before files), then by name. Symfony\Component\Finder\Finder

Constants

Hide inherited constants

ConstantValueDescriptionDefined By
IGNORE_DOT_FILES 2 Symfony\Component\Finder\Finder
IGNORE_VCS_FILES 1 Symfony\Component\Finder\Finder

Method Details

__construct() public method

Constructor.

public void __construct ( )
addVCSPattern() public static method

Adds VCS patterns.

See also ignoreVCS().

public static void addVCSPattern ( $pattern )
$pattern string|string[]

VCS patterns to ignore

append() public method

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.

public Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[] append ( $iterator )
$iterator mixed
return Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[]

The finder

throws InvalidArgumentException

When the given argument is not iterable.

contains() public method

Adds tests that file contents must match.

Strings or PCRE patterns can be used:

$finder->contains('Lorem ipsum') $finder->contains('/Lorem ipsum/i')

See also Symfony\Component\Finder\Iterator\FilecontentFilterIterator.

public Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[] contains ( $pattern )
$pattern string

A pattern (string or regexp)

return Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[]

The current Finder instance

count() public method

Counts all the results collected by the iterators.

public int count ( )
create() public static method

Creates a new Finder.

public static Symfony\Component\Finder\Finder create ( )
return Symfony\Component\Finder\Finder

A new Finder instance

date() public method

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');

See also:

public Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[] date ( $date )
$date string

A date range string

return Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[]

The current Finder instance

depth() public method

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.

See also:

public Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[] depth ( $level )
$level int

The depth level expression

return Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[]

The current Finder instance

directories() public method

Restricts the matching to directories only.

public Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[] directories ( )
return Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[]

The current Finder instance

exclude() public method
public Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[] exclude ( $dirs )
$dirs string|array

A directory path or an array of directories

return Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[]

The current Finder instance

files() public method

Restricts the matching to files only.

public Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[] files ( )
return Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[]

The current Finder instance

filter() public method

Filters the iterator with an anonymous function.

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

See also Symfony\Component\Finder\Iterator\CustomFilterIterator.

public Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[] filter ( Closure $closure )
$closure Closure

An anonymous function

return Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[]

The current Finder instance

followLinks() public method

Forces the following of symlinks.

public Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[] followLinks ( )
return Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[]

The current Finder instance

getIterator() public method

Returns an Iterator for the current Finder configuration.

This method implements the IteratorAggregate interface.

public Iterator|Symfony\Component\Finder\SplFileInfo[] getIterator ( )
return Iterator|Symfony\Component\Finder\SplFileInfo[]

An iterator

throws LogicException

if the in() method has not been called

ignoreDotFiles() public method

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

See also Symfony\Component\Finder\Iterator\ExcludeDirectoryFilterIterator.

public Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[] ignoreDotFiles ( $ignoreDotFiles )
$ignoreDotFiles bool

Whether to exclude "hidden" files or not

return Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[]

The current Finder instance

ignoreUnreadableDirs() public method

Tells finder to ignore unreadable directories.

By default, scanning unreadable directories content throws an AccessDeniedException.

public Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[] ignoreUnreadableDirs ( $ignore true )
$ignore bool
return Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[]

The current Finder instance

ignoreVCS() public method

Forces the finder to ignore version control directories.

See also Symfony\Component\Finder\Iterator\ExcludeDirectoryFilterIterator.

public Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[] ignoreVCS ( $ignoreVCS )
$ignoreVCS bool

Whether to exclude VCS files or not

return Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[]

The current Finder instance

in() public method

Searches files and directories which match defined rules.

public Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[] in ( $dirs )
$dirs string|array

A directory path or an array of directories

return Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[]

The current Finder instance

throws InvalidArgumentException

if one of the directories does not exist

name() public method

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

See also Symfony\Component\Finder\Iterator\FilenameFilterIterator.

public Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[] name ( $pattern )
$pattern string

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

return Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[]

The current Finder instance

notContains() public method

Adds tests that file contents must not match.

Strings or PCRE patterns can be used:

$finder->notContains('Lorem ipsum') $finder->notContains('/Lorem ipsum/i')

See also Symfony\Component\Finder\Iterator\FilecontentFilterIterator.

public Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[] notContains ( $pattern )
$pattern string

A pattern (string or regexp)

return Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[]

The current Finder instance

notName() public method

Adds rules that files must not match.

See also Symfony\Component\Finder\Iterator\FilenameFilterIterator.

public Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[] notName ( $pattern )
$pattern string

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

return Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[]

The current Finder instance

notPath() public method

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.

See also Symfony\Component\Finder\Iterator\FilenameFilterIterator.

public Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[] notPath ( $pattern )
$pattern string

A pattern (a regexp or a string)

return Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[]

The current Finder instance

path() public method

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.

See also Symfony\Component\Finder\Iterator\FilenameFilterIterator.

public Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[] path ( $pattern )
$pattern string

A pattern (a regexp or a string)

return Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[]

The current Finder instance

size() public method

Adds tests for file sizes.

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

See also:

public Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[] size ( $size )
$size string

A size range string

return Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[]

The current Finder instance

sort() public method

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.

See also Symfony\Component\Finder\Iterator\SortableIterator.

public Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[] sort ( Closure $closure )
$closure Closure

An anonymous function

return Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[]

The current Finder instance

sortByAccessedTime() public method

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.

See also Symfony\Component\Finder\Iterator\SortableIterator.

public Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[] sortByAccessedTime ( )
return Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[]

The current Finder instance

sortByChangedTime() public method

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.

See also Symfony\Component\Finder\Iterator\SortableIterator.

public Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[] sortByChangedTime ( )
return Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[]

The current Finder instance

sortByModifiedTime() public method

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.

See also Symfony\Component\Finder\Iterator\SortableIterator.

public Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[] sortByModifiedTime ( )
return Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[]

The current Finder instance

sortByName() public method

Sorts files and directories by name.

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

See also Symfony\Component\Finder\Iterator\SortableIterator.

public Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[] sortByName ( )
return Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[]

The current Finder instance

sortByType() public method

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.

See also Symfony\Component\Finder\Iterator\SortableIterator.

public Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[] sortByType ( )
return Symfony\Component\Finder\Finder|Symfony\Component\Finder\SplFileInfo[]

The current Finder instance