Location

The location is the only mandatory criteria. It tells the finder which directory to use for the search:

1

$finder->in(__DIR__);

Search in several locations by chaining calls to in():

1

$finder->files()->in(__DIR__)->in('/elsewhere');

Exclude directories from matching with the exclude() method:

1

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

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

1

$finder->in('ftp://example.com/pub/');

And it also works with user-defined streams:

1
2
3
4
5
6
7
8
9
10
11
12

use Symfony\Component\Finder\Finder;

$s3 = new \Zend_Service_Amazon_S3($key, $secret);
$s3->registerStreamWrapper("s3");

$finder = new Finder();
$finder->name('photos*')->size('< 100K')->date('since 1 hour ago');
foreach ($finder->in('s3://bucket-name') as $file) {
    // ... do something

    print $file->getFilename()."\n";
}

Files or Directories

By default, the Finder returns files and directories; but the files() and directories() methods control that:

1
2
3

$finder->files();

$finder->directories();

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

1

$finder->files()->followLinks();

By default, the iterator ignores popular VCS files. This can be changed with the ignoreVCS() method:

1

$finder->ignoreVCS(false);

Sorting

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

1
2
3

$finder->sortByName();

$finder->sortByType();

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

1
2
3
4
5
6

$sort = function (\SplFileInfo $a, \SplFileInfo $b)
{
    return strcmp($a->getRealpath(), $b->getRealpath());
};

$finder->sort($sort);

File Name

Restrict files by name with the name() method:

1

$finder->files()->name('*.php');

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

1

$finder->files()->name('/\.php$/');

The notName() method excludes files matching a pattern:

1

$finder->files()->notName('*.rb');

File Size

Restrict files by size with the size() method:

1

$finder->files()->size('< 1.5K');

Restrict by a size range by chaining calls:

1

$finder->files()->size('>= 1K')->size('<= 2K');

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

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 date() method:

1

$finder->date('since yesterday');

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 depth():

1
2

$finder->depth('== 0');
$finder->depth('< 3');

Custom Filtering

To restrict the matching file with your own strategy, use filter():

1
2
3
4
5
6
7
8

$filter = function (\SplFileInfo $file)
{
    if (strlen($file) > 10) {
        return false;
    }
};

$finder->files()->filter($filter);

The filter() method takes a Closure as an argument. For each matching file, it is called with the file as a SplFileInfo instance. The file is excluded from the result set if the Closure returns false.