Class Finder · Webisters Docs

Finder class

Symfony\Component\Finder\Finder

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

Implements: IteratorAggregate, Countable, Traversable

Defined in D:/WEBISTERS/projects/app/vendor/symfony/finder/Finder.php

Properties #

$mode: -
$names: -
$notNames: -
$exclude: -
$filters: -
$pruneFilters: -
$depths: -
$sizes: -
$followLinks: -
$reverseSorting: -
$sort: -
$ignore: -
$dirs: -
$dates: -
$iterators: -
$contains: -
$notContains: -
$paths: -
$notPaths: -
$ignoreUnreadableDirs: -
$vcsPatterns: -

$mode

private int $mode = 0

$names

private array $names = array ( )

$notNames

private array $notNames = array ( )

$exclude

private array $exclude = array ( )

$filters

private array $filters = array ( )

$pruneFilters

private array $pruneFilters = array ( )

$depths

private array $depths = array ( )

$sizes

private array $sizes = array ( )

$followLinks

private bool $followLinks = false

$reverseSorting

private bool $reverseSorting = false

$sort

private Closure|int|false $sort = false

$ignore

private int $ignore = 0

$dirs

private array $dirs = array ( )

$dates

private array $dates = array ( )

$iterators

private array $iterators = array ( )

$contains

private array $contains = array ( )

$notContains

private array $notContains = array ( )

$paths

private array $paths = array ( )

$notPaths

private array $notPaths = array ( )

$ignoreUnreadableDirs

private bool $ignoreUnreadableDirs = false

$vcsPatterns

private static array $vcsPatterns = array ( 0 => '.svn', 1 => '_svn', 2 => 'CVS', 3 => '_darcs', 4 => '.arch-params', 5 => '.monotone', 6 => '.bzr', 7 => '.git', 8 => '.hg', )

Methods #

__construct(): -
addVCSPattern(): Adds VCS patterns.
append(): Appends an existing set of files/directories to the finder.
contains(): Adds tests that file contents must match.
count(): Counts all the results collected by the iterators.
create(): Creates a new Finder.
date(): Adds tests for file dates (last modified).
depth(): Adds tests for the directory depth.
directories(): Restricts the matching to directories only.
exclude(): Excludes directories.
files(): Restricts the matching to files only.
filter(): Filters the iterator with an anonymous function.
followLinks(): Forces the following of symlinks.
getIterator(): Returns an Iterator for the current Finder configuration.
hasResults(): Check if any results were found.
ignoreDotFiles(): Excludes "hidden" directories and files (starting with a dot).
ignoreUnreadableDirs(): Tells finder to ignore unreadable directories.
ignoreVCS(): Forces the finder to ignore version control directories.
ignoreVCSIgnored(): Forces Finder to obey .gitignore and ignore files based on rules listed there.
in(): Searches files and directories which match defined rules.
name(): Adds rules that files must match.
notContains(): Adds tests that file contents must not match.
notName(): Adds rules that files must not match.
notPath(): Adds rules that filenames must not match.
path(): Adds rules that filenames must match.
reverseSorting(): Reverses the sorting.
size(): Adds tests for file sizes.
sort(): Sorts files and directories by an anonymous function.
sortByAccessedTime(): Sorts files and directories by the last accessed time.
sortByCaseInsensitiveName(): Sorts files and directories by name case insensitive.
sortByChangedTime(): Sorts files and directories by the last inode changed time.
sortByExtension(): Sorts files and directories by extension.
sortByModifiedTime(): Sorts files and directories by the last modified time.
sortByName(): Sorts files and directories by name.
sortBySize(): Sorts files and directories by size.
sortByType(): Sorts files and directories by type (directories before files), then by name.
normalizeDir(): Normalizes given directory names by removing trailing slashes.
searchInDirectory(): -

__construct()

public function __construct()

addVCSPattern()

public static function addVCSPattern(array|string $pattern): void

Adds VCS patterns.

Parameters

array|string $pattern - VCS patterns to ignore

Returns void

append()

public function append(iterable $iterator): static

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.

Parameters

iterable $iterator

Returns static

contains()

public function contains(array|string $patterns): static

Adds tests that file contents must match.

Strings or PCRE patterns can be used:

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

Parameters

array|string $patterns - A pattern (string or regexp) or an array of patterns

Returns static

count()

public function count(): int

Counts all the results collected by the iterators.

Returns int

create()

public static function create(): static

Creates a new Finder.

Returns static

date()

public function date(array|string $dates): static

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

Parameters

array|string $dates - A date range string or an array of date ranges

Returns static

depth()

public function depth(array|string|int $levels): static

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

Parameters

array|string|int $levels - The depth level expression or an array of depth levels

Returns static

directories()

public function directories(): static

Restricts the matching to directories only.

Returns static

exclude()

public function exclude(array|string $dirs): static

Excludes directories.

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

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

Parameters

array|string $dirs - A directory path or an array of directories

Returns static

files()

public function files(): static

Restricts the matching to files only.

Returns static

filter()

public function filter(Closure $closure, bool $prune = false): static

Filters the iterator with an anonymous function.

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

Parameters

Closure $closure
bool $prune - Whether to skip traversing directories further

Returns static

followLinks()

public function followLinks(): static

Forces the following of symlinks.

Returns static

getIterator()

public function getIterator(): Iterator

Returns an Iterator for the current Finder configuration.

This method implements the IteratorAggregate interface.

Returns Iterator - SplFileInfo>

hasResults()

public function hasResults(): bool

Check if any results were found.

Returns bool

ignoreDotFiles()

public function ignoreDotFiles(bool $ignoreDotFiles): static

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

This option is enabled by default.

Parameters

bool $ignoreDotFiles

Returns static

ignoreUnreadableDirs()

public function ignoreUnreadableDirs(bool $ignore = true): static

Tells finder to ignore unreadable directories.

By default, scanning unreadable directories content throws an AccessDeniedException.

Parameters

bool $ignore

Returns static

ignoreVCS()

public function ignoreVCS(bool $ignoreVCS): static

Forces the finder to ignore version control directories.

This option is enabled by default.

Parameters

bool $ignoreVCS

Returns static

ignoreVCSIgnored()

public function ignoreVCSIgnored(bool $ignoreVCSIgnored): static

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

This option is disabled by default.

Parameters

bool $ignoreVCSIgnored

Returns static

in()

public function in(array|string $dirs): static

Searches files and directories which match defined rules.

Parameters

array|string $dirs - A directory path or an array of directories

Returns static

name()

public function name(array|string $patterns): static

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, without dot files
$finder->name('test.php')
$finder->name(['test.py', 'test.php'])

Parameters

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

Returns static

notContains()

public function notContains(array|string $patterns): static

Adds tests that file contents must not match.

Strings or PCRE patterns can be used:

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

Parameters

array|string $patterns - A pattern (string or regexp) or an array of patterns

Returns static

notName()

public function notName(array|string $patterns): static

Adds rules that files must not match.

Parameters

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

Returns static

notPath()

public function notPath(array|string $patterns): static

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
$finder->notPath(['some/file.txt', 'another/file.log'])

Use only / as dirname separator.

Parameters

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

Returns static

path()

public function path(array|string $patterns): static

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
$finder->path(['some dir', 'another/dir'])

Use only / as dirname separator.

Parameters

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

Returns static

reverseSorting()

public function reverseSorting(): static

Reverses the sorting.

Returns static

size()

public function size(array|string|int $sizes): static

Adds tests for file sizes.

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

Parameters

array|string|int $sizes - A size range string or an integer or an array of size ranges

Returns static

sort()

public function sort(Closure $closure): static

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.

Parameters

Closure $closure

Returns static

sortByAccessedTime()

public function sortByAccessedTime(): static

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.

Returns static

sortByCaseInsensitiveName()

public function sortByCaseInsensitiveName(bool $useNaturalSort = false): static

Sorts files and directories by name case insensitive.

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

Parameters

bool $useNaturalSort

Returns static

sortByChangedTime()

public function sortByChangedTime(): static

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.

Returns static

sortByExtension()

public function sortByExtension(): static

Sorts files and directories by extension.

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

Returns static

sortByModifiedTime()

public function sortByModifiedTime(): static

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.

Returns static

sortByName()

public function sortByName(bool $useNaturalSort = false): static

Sorts files and directories by name.

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

Parameters

bool $useNaturalSort

Returns static

sortBySize()

public function sortBySize(): static

Sorts files and directories by size.

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

Returns static

sortByType()

public function sortByType(): static

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.

Returns static

normalizeDir()

private function normalizeDir(string $dir): string

Normalizes given directory names by removing trailing slashes.

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

Parameters

string $dir

Returns string

searchInDirectory()

private function searchInDirectory(string $dir): Iterator

Parameters

string $dir

Returns Iterator