formats into arrays and vice versa, and Normalizer will deal with

turning specific objects into arrays and vice versa.

From the graph above is also clear what encoding, decoding, normalize,

denormalize, serialize and deserialize mean.

The :class:`Symfony\\Component\\Finder\\Finder` class finds files and/or

directories::

The ``$file`` is an instance of :class:`Symfony\\Component\\Finder\\SplFileInfo`

which extends :phpclass:`SplFileInfo` to provide methods to work with relative

paths.

The above code prints the names of all the files in the current directory

recursively. The Finder class uses a fluent interface, so all methods return

the Finder instance.

.. tip::

A Finder instance is a PHP `Iterator`_. So, instead of iterating over the

Finder with ``foreach``, you can also convert it to an array with the

:phpfunction:`iterator_to_array` method, or get the number of items with

:phpfunction:`iterator_count`.

Criteria

Location

The location is the only mandatory criteria. It tells the finder which

directory to use for the search::

Search in several locations by chaining calls to

:method:`Symfony\\Component\\Finder\\Finder::in`::

Exclude directories from matching with the

:method:`Symfony\\Component\\Finder\\Finder::exclude` method::

As the Finder uses PHP iterators, you can pass any URL with a supported

`protocol`_::

And it also works with user-defined streams::

.. note::

Read the `Streams`_ documentation to learn how to create your own streams.

Files or Directories

By default, the Finder returns files and directories; but the

:method:`Symfony\\Component\\Finder\\Finder::files` and

:method:`Symfony\\Component\\Finder\\Finder::directories` methods control that::

If you want to follow links, use the ``followLinks()`` method::

By default, the iterator ignores popular VCS files. This can be changed with

the ``ignoreVCS()`` method::

Sorting

Sort the result by name or by type (directories first, then files)::

.. note::

Notice that the ``sort*`` methods need to get all matching elements to do

their jobs. For large iterators, it is slow.

You can also define your own sorting algorithm with ``sort()`` method::

File Name

Restrict files by name with the

:method:`Symfony\\Component\\Finder\\Finder::name` method::

The ``name()`` method accepts globs, strings, or regexes::

The ``notName()`` method excludes files matching a pattern::

File Contents

.. versionadded:: 2.1

Methods ``contains()`` and ``notContains()`` have been

introduced in version 2.1.

Restrict files by contents with the

:method:`Symfony\\Component\\Finder\\Finder::contains` method::

The ``contains()`` method accepts strings or regexes::

The ``notContains()`` method excludes files containing given pattern::

File Size

Restrict files by size with the

:method:`Symfony\\Component\\Finder\\Finder::size` method::

Restrict by a size range by chaining calls::

The comparison operator can be any of the following: ``>``, ``>=``, ``<``, ``<=``,

``==``, ``!=``.

.. versionadded:: 2.1

The operator ``!=`` was added in version 2.1.

The target value may use magnitudes of kilobytes (``k``, ``ki``), megabytes

(``m``, ``mi``), or gigabytes (``g``, ``gi``). Those suffixed with an ``i`` use

the appropriate ``2**n`` version in accordance with the `IEC standard`_.

File Date

Restrict files by last modified dates with the

:method:`Symfony\\Component\\Finder\\Finder::date` method::

The comparison operator can be any of the following: ``>``, ``>=``, ``<``, '<=',

'=='. You can also use ``since`` or ``after`` as an alias for ``>``, and

``until`` or ``before`` as an alias for ``<``.

The target value can be any date supported by the `strtotime`_ function.

Directory Depth

By default, the Finder recursively traverse directories. Restrict the depth of

traversing with :method:`Symfony\\Component\\Finder\\Finder::depth`::

Custom Filtering

To restrict the matching file with your own strategy, use

:method:`Symfony\\Component\\Finder\\Finder::filter`::

The ``filter()`` method takes a Closure as an argument. For each matching file,

it is called with the file as a :class:`Symfony\\Component\\Finder\\SplFileInfo`

instance. The file is excluded from the result set if the Closure returns

``false``.

Reading contents of returned files

.. versionadded:: 2.1

Method ``getContents()`` have been introduced in version 2.1.

The contents of returned files can be read with

:method:`Symfony\\Component\\Finder\\SplFileInfo::getContents`::

.. _strtotime: http://www.php.net/manual/en/datetime.formats.php

.. _Iterator: http://www.php.net/manual/en/spl.iterators.php

.. _protocol: http://www.php.net/manual/en/wrappers.php

.. _Streams: http://www.php.net/streams

.. _IEC standard: http://physics.nist.gov/cuu/Units/binary.html