platform/api/symfony/Component/Finder/Finder.yaml

name: Finder
class_comment: '# * 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__);

  # *

  # * @author Fabien Potencier <fabien@symfony.com>

  # *

  # * @implements \IteratorAggregate<string, SplFileInfo>'
dependencies:
- name: DateComparator
  type: class
  source: Symfony\Component\Finder\Comparator\DateComparator
- name: NumberComparator
  type: class
  source: Symfony\Component\Finder\Comparator\NumberComparator
- name: DirectoryNotFoundException
  type: class
  source: Symfony\Component\Finder\Exception\DirectoryNotFoundException
- name: CustomFilterIterator
  type: class
  source: Symfony\Component\Finder\Iterator\CustomFilterIterator
- name: DateRangeFilterIterator
  type: class
  source: Symfony\Component\Finder\Iterator\DateRangeFilterIterator
- name: DepthRangeFilterIterator
  type: class
  source: Symfony\Component\Finder\Iterator\DepthRangeFilterIterator
- name: ExcludeDirectoryFilterIterator
  type: class
  source: Symfony\Component\Finder\Iterator\ExcludeDirectoryFilterIterator
- name: FilecontentFilterIterator
  type: class
  source: Symfony\Component\Finder\Iterator\FilecontentFilterIterator
- name: FilenameFilterIterator
  type: class
  source: Symfony\Component\Finder\Iterator\FilenameFilterIterator
- name: LazyIterator
  type: class
  source: Symfony\Component\Finder\Iterator\LazyIterator
- name: SizeRangeFilterIterator
  type: class
  source: Symfony\Component\Finder\Iterator\SizeRangeFilterIterator
- name: SortableIterator
  type: class
  source: Symfony\Component\Finder\Iterator\SortableIterator
properties: []
methods:
- name: create
  visibility: public
  parameters: []
  comment: "# * Finder allows to build rules to find files and directories.\n# *\n\
    # * It is a thin wrapper around several specialized iterator classes.\n# *\n#\
    \ * All rules may be invoked several times.\n# *\n# * All methods return the current\
    \ Finder object to allow chaining:\n# *\n# *     $finder = Finder::create()->files()->name('*.php')->in(__DIR__);\n\
    # *\n# * @author Fabien Potencier <fabien@symfony.com>\n# *\n# * @implements \\\
    IteratorAggregate<string, SplFileInfo>\n# */\n# class Finder implements \\IteratorAggregate,\
    \ \\Countable\n# {\n# public const IGNORE_VCS_FILES = 1;\n# public const IGNORE_DOT_FILES\
    \ = 2;\n# public const IGNORE_VCS_IGNORED_FILES = 4;\n# \n# private int $mode\
    \ = 0;\n# private array $names = [];\n# private array $notNames = [];\n# private\
    \ array $exclude = [];\n# private array $filters = [];\n# private array $pruneFilters\
    \ = [];\n# private array $depths = [];\n# private array $sizes = [];\n# private\
    \ bool $followLinks = false;\n# private bool $reverseSorting = false;\n# private\
    \ \\Closure|int|false $sort = false;\n# private int $ignore = 0;\n# private array\
    \ $dirs = [];\n# private array $dates = [];\n# private array $iterators = [];\n\
    # private array $contains = [];\n# private array $notContains = [];\n# private\
    \ array $paths = [];\n# private array $notPaths = [];\n# private bool $ignoreUnreadableDirs\
    \ = false;\n# \n# private static array $vcsPatterns = ['.svn', '_svn', 'CVS',\
    \ '_darcs', '.arch-params', '.monotone', '.bzr', '.git', '.hg'];\n# \n# public\
    \ function __construct()\n# {\n# $this->ignore = static::IGNORE_VCS_FILES | static::IGNORE_DOT_FILES;\n\
    # }\n# \n# /**\n# * Creates a new Finder."
- name: directories
  visibility: public
  parameters: []
  comment: '# * Restricts the matching to directories only.

    # *

    # * @return $this'
- name: files
  visibility: public
  parameters: []
  comment: '# * Restricts the matching to files only.

    # *

    # * @return $this'
- name: depth
  visibility: public
  parameters:
  - name: levels
  comment: '# * 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''])

    # *

    # * @param string|int|string[]|int[] $levels The depth level expression or an
    array of depth levels

    # *

    # * @return $this

    # *

    # * @see DepthRangeFilterIterator

    # * @see NumberComparator'
- name: date
  visibility: public
  parameters:
  - name: dates
  comment: '# * 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'']);

    # *

    # * @param string|string[] $dates A date range string or an array of date ranges

    # *

    # * @return $this

    # *

    # * @see strtotime

    # * @see DateRangeFilterIterator

    # * @see DateComparator'
- name: name
  visibility: public
  parameters:
  - name: patterns
  comment: '# * 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''])

    # *

    # * @param string|string[] $patterns A pattern (a regexp, a glob, or a string)
    or an array of patterns

    # *

    # * @return $this

    # *

    # * @see FilenameFilterIterator'
- name: notName
  visibility: public
  parameters:
  - name: patterns
  comment: '# * Adds rules that files must not match.

    # *

    # * @param string|string[] $patterns A pattern (a regexp, a glob, or a string)
    or an array of patterns

    # *

    # * @return $this

    # *

    # * @see FilenameFilterIterator'
- name: contains
  visibility: public
  parameters:
  - name: patterns
  comment: '# * 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''])

    # *

    # * @param string|string[] $patterns A pattern (string or regexp) or an array
    of patterns

    # *

    # * @return $this

    # *

    # * @see FilecontentFilterIterator'
- name: notContains
  visibility: public
  parameters:
  - name: patterns
  comment: '# * 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''])

    # *

    # * @param string|string[] $patterns A pattern (string or regexp) or an array
    of patterns

    # *

    # * @return $this

    # *

    # * @see FilecontentFilterIterator'
- name: path
  visibility: public
  parameters:
  - name: patterns
  comment: '# * 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.

    # *

    # * @param string|string[] $patterns A pattern (a regexp or a string) or an array
    of patterns

    # *

    # * @return $this

    # *

    # * @see FilenameFilterIterator'
- name: notPath
  visibility: public
  parameters:
  - name: patterns
  comment: '# * 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.

    # *

    # * @param string|string[] $patterns A pattern (a regexp or a string) or an array
    of patterns

    # *

    # * @return $this

    # *

    # * @see FilenameFilterIterator'
- name: size
  visibility: public
  parameters:
  - name: sizes
  comment: '# * Adds tests for file sizes.

    # *

    # *     $finder->size(''> 10K'');

    # *     $finder->size(''<= 1Ki'');

    # *     $finder->size(4);

    # *     $finder->size([''> 10K'', ''< 20K''])

    # *

    # * @param string|int|string[]|int[] $sizes A size range string or an integer
    or an array of size ranges

    # *

    # * @return $this

    # *

    # * @see SizeRangeFilterIterator

    # * @see NumberComparator'
- name: exclude
  visibility: public
  parameters:
  - name: dirs
  comment: '# * Excludes directories.

    # *

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

    # *

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

    # *

    # * @param string|array $dirs A directory path or an array of directories

    # *

    # * @return $this

    # *

    # * @see ExcludeDirectoryFilterIterator'
- name: ignoreDotFiles
  visibility: public
  parameters:
  - name: ignoreDotFiles
  comment: '# * Excludes "hidden" directories and files (starting with a dot).

    # *

    # * This option is enabled by default.

    # *

    # * @return $this

    # *

    # * @see ExcludeDirectoryFilterIterator'
- name: ignoreVCS
  visibility: public
  parameters:
  - name: ignoreVCS
  comment: '# * Forces the finder to ignore version control directories.

    # *

    # * This option is enabled by default.

    # *

    # * @return $this

    # *

    # * @see ExcludeDirectoryFilterIterator'
- name: ignoreVCSIgnored
  visibility: public
  parameters:
  - name: ignoreVCSIgnored
  comment: '# * Forces Finder to obey .gitignore and ignore files based on rules listed
    there.

    # *

    # * This option is disabled by default.

    # *

    # * @return $this'
- name: addVCSPattern
  visibility: public
  parameters:
  - name: pattern
  comment: '# * Adds VCS patterns.

    # *

    # * @see ignoreVCS()

    # *

    # * @param string|string[] $pattern VCS patterns to ignore'
- name: sort
  visibility: public
  parameters:
  - name: closure
  comment: '# * 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.

    # *

    # * @return $this

    # *

    # * @see SortableIterator'
- name: sortByExtension
  visibility: public
  parameters: []
  comment: '# * Sorts files and directories by extension.

    # *

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

    # *

    # * @return $this

    # *

    # * @see SortableIterator'
- name: sortByName
  visibility: public
  parameters:
  - name: useNaturalSort
    default: 'false'
  comment: '# * Sorts files and directories by name.

    # *

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

    # *

    # * @return $this

    # *

    # * @see SortableIterator'
- name: sortByCaseInsensitiveName
  visibility: public
  parameters:
  - name: useNaturalSort
    default: 'false'
  comment: '# * Sorts files and directories by name case insensitive.

    # *

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

    # *

    # * @return $this

    # *

    # * @see SortableIterator'
- name: sortBySize
  visibility: public
  parameters: []
  comment: '# * Sorts files and directories by size.

    # *

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

    # *

    # * @return $this

    # *

    # * @see SortableIterator'
- name: sortByType
  visibility: public
  parameters: []
  comment: '# * 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.

    # *

    # * @return $this

    # *

    # * @see SortableIterator'
- name: sortByAccessedTime
  visibility: public
  parameters: []
  comment: '# * 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.

    # *

    # * @return $this

    # *

    # * @see SortableIterator'
- name: reverseSorting
  visibility: public
  parameters: []
  comment: '# * Reverses the sorting.

    # *

    # * @return $this'
- name: sortByChangedTime
  visibility: public
  parameters: []
  comment: '# * 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.

    # *

    # * @return $this

    # *

    # * @see SortableIterator'
- name: sortByModifiedTime
  visibility: public
  parameters: []
  comment: '# * 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.

    # *

    # * @return $this

    # *

    # * @see SortableIterator'
- name: filter
  visibility: public
  parameters:
  - name: closure
  - name: prune
    default: 'false'
  comment: '# * Filters the iterator with an anonymous function.

    # *

    # * The anonymous function receives a \SplFileInfo and must return false

    # * to remove files.

    # *

    # * @param \Closure(SplFileInfo): bool $closure

    # * @param bool                        $prune   Whether to skip traversing directories
    further

    # *

    # * @return $this

    # *

    # * @see CustomFilterIterator'
- name: followLinks
  visibility: public
  parameters: []
  comment: '# * Forces the following of symlinks.

    # *

    # * @return $this'
- name: ignoreUnreadableDirs
  visibility: public
  parameters:
  - name: ignore
    default: 'true'
  comment: '# * Tells finder to ignore unreadable directories.

    # *

    # * By default, scanning unreadable directories content throws an AccessDeniedException.

    # *

    # * @return $this'
- name: in
  visibility: public
  parameters:
  - name: dirs
  comment: '# * Searches files and directories which match defined rules.

    # *

    # * @param string|string[] $dirs A directory path or an array of directories

    # *

    # * @return $this

    # *

    # * @throws DirectoryNotFoundException if one of the directories does not exist'
- name: getIterator
  visibility: public
  parameters: []
  comment: '# * Returns an Iterator for the current Finder configuration.

    # *

    # * This method implements the IteratorAggregate interface.

    # *

    # * @return \Iterator<string, SplFileInfo>

    # *

    # * @throws \LogicException if the in() method has not been called'
- name: append
  visibility: public
  parameters:
  - name: iterator
  comment: '# * 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.

    # *

    # * @return $this

    # *

    # * @throws \InvalidArgumentException when the given argument is not iterable'
- name: hasResults
  visibility: public
  parameters: []
  comment: '# * Check if any results were found.'
- name: count
  visibility: public
  parameters: []
  comment: '# * Counts all the results collected by the iterators.'
- name: searchInDirectory
  visibility: private
  parameters:
  - name: dir
  comment: null
- name: normalizeDir
  visibility: private
  parameters:
  - name: dir
  comment: '# * Normalizes given directory names by removing trailing slashes.

    # *

    # * Excluding: (s)ftp:// or ssh2.(s)ftp:// wrapper'
traits:
- Symfony\Component\Finder\Comparator\DateComparator
- Symfony\Component\Finder\Comparator\NumberComparator
- Symfony\Component\Finder\Exception\DirectoryNotFoundException
- Symfony\Component\Finder\Iterator\CustomFilterIterator
- Symfony\Component\Finder\Iterator\DateRangeFilterIterator
- Symfony\Component\Finder\Iterator\DepthRangeFilterIterator
- Symfony\Component\Finder\Iterator\ExcludeDirectoryFilterIterator
- Symfony\Component\Finder\Iterator\FilecontentFilterIterator
- Symfony\Component\Finder\Iterator\FilenameFilterIterator
- Symfony\Component\Finder\Iterator\LazyIterator
- Symfony\Component\Finder\Iterator\SizeRangeFilterIterator
- Symfony\Component\Finder\Iterator\SortableIterator
interfaces:
- \IteratorAggregate
- \IteratorAggregate
- the