PHP Class Symfony\Component\Finder\Finder

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__);
Author: Fabien Potencier ([email protected])
Inheritance: implements IteratorAggregate, implements Countable
Show file Open project: symfony/symfony Class Usage Examples

Public Methods

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

Private Methods

Method Description
searchInDirectory ( $dir ) : Iterator

Method Details

__construct() public method

Constructor.
public __construct ( )

addVCSPattern() public static method

Adds VCS patterns.
See also: ignoreVCS()
public static addVCSPattern ( string | string[] $pattern )
$pattern string | string[] VCS patterns to ignore

append() public method

The set can be another Finder, an Iterator, an IteratorAggregate, or even a plain array.
public append ( mixed $iterator ) : Finder | Symfony\Component\Finder\SplFileInfo[]
$iterator mixed
return Finder | Symfony\Component\Finder\SplFileInfo[] The finder

contains() public method

Strings or PCRE patterns can be used: $finder->contains('Lorem ipsum') $finder->contains('/Lorem ipsum/i')
See also: FilecontentFilterIterator
public contains ( string $pattern ) : Finder | Symfony\Component\Finder\SplFileInfo[]
$pattern string A pattern (string or regexp)
return Finder | Symfony\Component\Finder\SplFileInfo[] The current Finder instance

count() public method

Counts all the results collected by the iterators.
public count ( ) : integer
return integer

create() public static method

Creates a new Finder.
public static create ( ) : Finder
return Finder A new Finder instance

date() public method

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: strtotime
See also: DateRangeFilterIterator
See also: DateComparator
public date ( string $date ) : Finder | Symfony\Component\Finder\SplFileInfo[]
$date string A date range string
return Finder | Symfony\Component\Finder\SplFileInfo[] The current Finder instance

depth() public method

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: DepthRangeFilterIterator
See also: NumberComparator
public depth ( string | integer $level ) : Finder | Symfony\Component\Finder\SplFileInfo[]
$level string | integer The depth level expression
return Finder | Symfony\Component\Finder\SplFileInfo[] The current Finder instance

directories() public method

Restricts the matching to directories only.
public directories ( ) : Finder | Symfony\Component\Finder\SplFileInfo[]
return Finder | Symfony\Component\Finder\SplFileInfo[] The current Finder instance

exclude() public method

Excludes directories.
See also: ExcludeDirectoryFilterIterator
public exclude ( string | array $dirs ) : Finder | Symfony\Component\Finder\SplFileInfo[]
$dirs string | array A directory path or an array of directories
return Finder | Symfony\Component\Finder\SplFileInfo[] The current Finder instance

files() public method

Restricts the matching to files only.
public files ( ) : Finder | Symfony\Component\Finder\SplFileInfo[]
return Finder | Symfony\Component\Finder\SplFileInfo[] The current Finder instance

filter() public method

The anonymous function receives a \SplFileInfo and must return false to remove files.
See also: CustomFilterIterator
public filter ( Closure $closure ) : Finder | Symfony\Component\Finder\SplFileInfo[]
$closure Closure An anonymous function
return Finder | Symfony\Component\Finder\SplFileInfo[] The current Finder instance

getIterator() public method

This method implements the IteratorAggregate interface.
public getIterator ( ) : Iterator | Symfony\Component\Finder\SplFileInfo[]
return Iterator | Symfony\Component\Finder\SplFileInfo[] An iterator

ignoreDotFiles() public method

Excludes "hidden" directories and files (starting with a dot).
See also: ExcludeDirectoryFilterIterator
public ignoreDotFiles ( boolean $ignoreDotFiles ) : Finder | Symfony\Component\Finder\SplFileInfo[]
$ignoreDotFiles boolean Whether to exclude "hidden" files or not
return Finder | Symfony\Component\Finder\SplFileInfo[] The current Finder instance

ignoreUnreadableDirs() public method

By default, scanning unreadable directories content throws an AccessDeniedException.
public ignoreUnreadableDirs ( boolean $ignore = true ) : Finder | Symfony\Component\Finder\SplFileInfo[]
$ignore boolean
return Finder | Symfony\Component\Finder\SplFileInfo[] The current Finder instance

ignoreVCS() public method

Forces the finder to ignore version control directories.
See also: ExcludeDirectoryFilterIterator
public ignoreVCS ( boolean $ignoreVCS ) : Finder | Symfony\Component\Finder\SplFileInfo[]
$ignoreVCS boolean Whether to exclude VCS files or not
return Finder | Symfony\Component\Finder\SplFileInfo[] The current Finder instance

in() public method

Searches files and directories which match defined rules.
public in ( string | array $dirs ) : Finder | Symfony\Component\Finder\SplFileInfo[]
$dirs string | array A directory path or an array of directories
return Finder | Symfony\Component\Finder\SplFileInfo[] The current Finder instance

name() public method

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: FilenameFilterIterator
public name ( string $pattern ) : Finder | Symfony\Component\Finder\SplFileInfo[]
$pattern string A pattern (a regexp, a glob, or a string)
return Finder | Symfony\Component\Finder\SplFileInfo[] The current Finder instance

notContains() public method

Strings or PCRE patterns can be used: $finder->notContains('Lorem ipsum') $finder->notContains('/Lorem ipsum/i')
See also: FilecontentFilterIterator
public notContains ( string $pattern ) : Finder | Symfony\Component\Finder\SplFileInfo[]
$pattern string A pattern (string or regexp)
return Finder | Symfony\Component\Finder\SplFileInfo[] The current Finder instance

notName() public method

Adds rules that files must not match.
See also: FilenameFilterIterator
public notName ( string $pattern ) : Finder | Symfony\Component\Finder\SplFileInfo[]
$pattern string A pattern (a regexp, a glob, or a string)
return Finder | Symfony\Component\Finder\SplFileInfo[] The current Finder instance

notPath() public method

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: FilenameFilterIterator
public notPath ( string $pattern ) : Finder | Symfony\Component\Finder\SplFileInfo[]
$pattern string A pattern (a regexp or a string)
return Finder | Symfony\Component\Finder\SplFileInfo[] The current Finder instance

path() public method

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: FilenameFilterIterator
public path ( string $pattern ) : Finder | Symfony\Component\Finder\SplFileInfo[]
$pattern string A pattern (a regexp or a string)
return Finder | Symfony\Component\Finder\SplFileInfo[] The current Finder instance

size() public method

$finder->size('> 10K'); $finder->size('<= 1Ki'); $finder->size(4);
See also: SizeRangeFilterIterator
See also: NumberComparator
public size ( string | integer $size ) : Finder | Symfony\Component\Finder\SplFileInfo[]
$size string | integer A size range string or an integer
return Finder | Symfony\Component\Finder\SplFileInfo[] The current Finder instance

sort() public method

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: SortableIterator
public sort ( Closure $closure ) : Finder | Symfony\Component\Finder\SplFileInfo[]
$closure Closure An anonymous function
return Finder | Symfony\Component\Finder\SplFileInfo[] The current Finder instance

sortByAccessedTime() public method

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: SortableIterator
public sortByAccessedTime ( ) : Finder | Symfony\Component\Finder\SplFileInfo[]
return Finder | Symfony\Component\Finder\SplFileInfo[] The current Finder instance

sortByChangedTime() public method

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: SortableIterator
public sortByChangedTime ( ) : Finder | Symfony\Component\Finder\SplFileInfo[]
return Finder | Symfony\Component\Finder\SplFileInfo[] The current Finder instance

sortByModifiedTime() public method

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: SortableIterator
public sortByModifiedTime ( ) : Finder | Symfony\Component\Finder\SplFileInfo[]
return Finder | Symfony\Component\Finder\SplFileInfo[] The current Finder instance

sortByName() public method

This can be slow as all the matching files and directories must be retrieved for comparison.
See also: SortableIterator
public sortByName ( ) : Finder | Symfony\Component\Finder\SplFileInfo[]
return Finder | Symfony\Component\Finder\SplFileInfo[] The current Finder instance

sortByType() public method

This can be slow as all the matching files and directories must be retrieved for comparison.
See also: SortableIterator
public sortByType ( ) : Finder | Symfony\Component\Finder\SplFileInfo[]
return Finder | Symfony\Component\Finder\SplFileInfo[] The current Finder instance