Documentation

Finder extends Finder
in package

Application

Finder allows to build rules to find files and directories.

Constants

IGNORE_DOT_FILES = 2
IGNORE_VCS_FILES = 1
IGNORE_VCS_IGNORED_FILES = 4

Properties

$contains : array<string|int, mixed>
$dates : array<string|int, mixed>
$depths : array<string|int, mixed>
$dirs : array<string|int, mixed>
$exclude : array<string|int, mixed>
$filters : array<string|int, mixed>
$followLinks : bool
$ignore : int
$ignoreUnreadableDirs : bool
$iterators : array<string|int, mixed>
$mode : int
$names : array<string|int, mixed>
$notContains : array<string|int, mixed>
$notNames : array<string|int, mixed>
$notPaths : array<string|int, mixed>
$paths : array<string|int, mixed>
$pruneFilters : array<string|int, mixed>
$reverseSorting : bool
$sizes : array<string|int, mixed>
$sort : Closure|int|false
$vcsPatterns : array<string|int, mixed>

Methods

__construct() : mixed
addVCSPattern() : void: 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<string, 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.
sortByCaseInsensitiveName() : $this: Sorts files and directories by name case insensitive.
sortByChangedTime() : $this: Sorts files and directories by the last inode changed time.
sortByExtension() : $this: Sorts files and directories by extension.
sortByModifiedTime() : $this: Sorts files and directories by the last modified time.
sortByName() : $this: Sorts files and directories by name.
sortBySize() : $this: Sorts files and directories by size.
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

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

$contains


    private
        array<string|int, mixed>
    $contains
     = []

$dates


    private
        array<string|int, mixed>
    $dates
     = []

$depths


    private
        array<string|int, mixed>
    $depths
     = []

$dirs


    private
        array<string|int, mixed>
    $dirs
     = []

$exclude


    private
        array<string|int, mixed>
    $exclude
     = []

$filters


    private
        array<string|int, mixed>
    $filters
     = []

$followLinks


    private
        bool
    $followLinks
     = false

$ignore


    private
        int
    $ignore
     = 0

$ignoreUnreadableDirs


    private
        bool
    $ignoreUnreadableDirs
     = false

$iterators


    private
        array<string|int, mixed>
    $iterators
     = []

$mode


    private
        int
    $mode
     = 0

$names


    private
        array<string|int, mixed>
    $names
     = []

$notContains


    private
        array<string|int, mixed>
    $notContains
     = []

$notNames


    private
        array<string|int, mixed>
    $notNames
     = []

$notPaths


    private
        array<string|int, mixed>
    $notPaths
     = []

$paths


    private
        array<string|int, mixed>
    $paths
     = []

$pruneFilters


    private
        array<string|int, mixed>
    $pruneFilters
     = []

$reverseSorting


    private
        bool
    $reverseSorting
     = false

$sizes


    private
        array<string|int, mixed>
    $sizes
     = []

$sort


    private
        Closure|int|false
    $sort
     = false

$vcsPatterns


    private
    static    array<string|int, mixed>
    $vcsPatterns
     = ['.svn', '_svn', 'CVS', '_darcs', '.arch-params', '.monotone', '.bzr', '.git', '.hg']

__construct()


    public
                    __construct() : mixed

addVCSPattern()

Adds VCS patterns.


    public
            static        addVCSPattern(string|array<string|int, string> $pattern) : void

Parameters

$pattern : string|array<string|int, string>: VCS patterns to ignore

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>

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

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

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

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

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(callable(SplFileInfo): bool $closure) : $this

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

Parameters

$closure : callable(SplFileInfo): bool

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<string, SplFileInfo>

This method implements the IteratorAggregate interface.

Return values

Iterator<string, SplFileInfo>

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

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

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

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, without dot files $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

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

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

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

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

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

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

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.

Return values

$this

sortByCaseInsensitiveName()

Sorts files and directories by name case insensitive.


    public
                    sortByCaseInsensitiveName([bool $useNaturalSort = false ]) : $this

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

Parameters

$useNaturalSort : bool = false

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.

Return values

$this

sortByExtension()

Sorts files and directories by extension.


    public
                    sortByExtension() : $this

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

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.

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

Return values

$this

sortBySize()

Sorts files and directories by size.


    public
                    sortBySize() : $this

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

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.

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

Finder extends Finder in package Application

Tags

Table of Contents

Constants

Properties

Methods

Constants

IGNORE_DOT_FILES

IGNORE_VCS_FILES

IGNORE_VCS_IGNORED_FILES

Properties

$contains

$dates

$depths

$dirs

$exclude

$filters

$followLinks

$ignore

$ignoreUnreadableDirs

$iterators

$mode

$names

$notContains

$notNames

$notPaths

$paths

$pruneFilters

$reverseSorting

$sizes

$sort

$vcsPatterns

Methods

__construct()

addVCSPattern()

Parameters

Tags

append()

Parameters

Tags

Return values

contains()

Parameters

Tags

Return values

count()

Return values

create()

Return values

date()

Parameters

Tags

Return values

depth()

Parameters

Tags

Return values

directories()

Return values

exclude()

Parameters

Tags

Return values

files()

Return values

filter()

Parameters

Tags

Return values

followLinks()

Return values

getIterator()

Tags

Return values

hasResults()

Return values

ignoreDotFiles()

Parameters

Tags

Return values

Finder extends Finder
in package

Application