The Finder Component

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
2
3
4
5

// search inside *both* directories
$finder->in([__DIR__, '/elsewhere']);

// same as above
$finder->in(__DIR__)->in('/elsewhere');

Use * as a wildcard character to search in the directories matching a pattern (each pattern has to resolve to at least one directory path):

1

$finder->in('src/Symfony/*/*/Resources');

Exclude directories from matching with the exclude() method:

1
2

// directories passed as argument must be relative to the ones defined with the in() method
$finder->in(__DIR__)->exclude('ruby');

It's also possible to ignore directories that you don't have permission to read:

1

$finder->ignoreUnreadableDirs()->in(__DIR__);

As the Finder uses PHP iterators, you can pass any URL with a supported PHP wrapper for URL-style protocols (ftp://, zlib://, etc.):

1
2
3
4
5

// always add a trailing slash when looking for in the FTP root dir
$finder->in('ftp://example.com/');

// you can also look for in a FTP directory
$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

use Symfony\Component\Finder\Finder;

// register a 's3://' wrapper with the official AWS SDK
$s3Client = new Aws\S3\S3Client([/* config options */]);
$s3Client->registerStreamWrapper();

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

Files or Directories

By default, the Finder returns both files and directories. If you need to find either files or directories only, use the files() and directories() methods:

1
2
3
4
5

// look for files only; ignore directories
$finder->files();

// look for directories only; ignore files
$finder->directories();

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

1

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

Note that this method follows links but it doesn't resolve them. Consider the following structure of files of directories:

1
2
3
4
5
6
7
8

├── folder1/
│   ├──file1.txt
│   ├── file2link (symbolic link to folder2/file2.txt file)
│   └── folder3link (symbolic link to folder3/ directory)
├── folder2/
│   └── file2.txt
└── folder3/
    └── file3.txt

If you try to find all files in folder1/ via $finder->files()->in('/path/to/folder1/') you'll get the following results:

• When not using the followLinks() method: file1.txt and file2link (this link is not resolved). The folder3link doesn't appear in the results because it's not followed or resolved;
• When using the followLinks() method: file1.txt, file2link (this link is still not resolved) and folder3/file3.txt (this file appears in the results because the folder1/folder3link link was followed).

Version Control Files

Version Control Systems (or "VCS" for short), such as Git and Mercurial, create some special files to store their metadata. Those files are ignored by default when looking for files and directories, but you can change this with the ignoreVCS() method:

1

$finder->ignoreVCS(false);

If the search directory and its subdirectories contain .gitignore files, you can reuse those rules to exclude files and directories from the results with the ignoreVCSIgnored() method:

1
2

// excludes files/directories matching the .gitignore patterns
$finder->ignoreVCSIgnored(true);

The rules of a directory always override the rules of its parent directories.

File Name

Find files by name with the name() method:

1

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

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

1

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

Multiple filenames can be defined by chaining calls or passing an array:

1
2
3
4

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

// same as above
$finder->files()->name(['*.php', '*.twig']);

The notName() method excludes files matching a pattern:

1

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

Multiple filenames can be excluded by chaining calls or passing an array:

1
2
3
4

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

// same as above
$finder->files()->notName(['*.rb', '*.py']);

File Contents

Find files by content with the contains() method:

1

$finder->files()->contains('lorem ipsum');

The contains() method accepts strings or regexes:

1

$finder->files()->contains('/lorem\s+ipsum$/i');

The notContains() method excludes files containing given pattern:

1

$finder->files()->notContains('dolor sit amet');

Path

Find files and directories by path with the path() method:

1
2
3
4

// matches files that contain "data" anywhere in their paths (files or directories)
$finder->path('data');
// for example this will match data/*.xml and data.xml if they exist
$finder->path('data')->name('*.xml');

Use the forward slash (i.e. /) as the directory separator on all platforms, including Windows. The component makes the necessary conversion internally.

The path() method accepts a string, a regular expression or an array of strings or regular expressions:

1
2

$finder->path('foo/bar');
$finder->path('/^foo\/bar/');

Multiple paths can be defined by chaining calls or passing an array:

1
2
3
4

$finder->path('data')->path('foo/bar');

// same as above
$finder->path(['data', 'foo/bar']);

Internally, strings are converted into regular expressions by escaping slashes and adding delimiters:

The notPath() method excludes files by path:

1

$finder->notPath('other/dir');

Multiple paths can be excluded by chaining calls or passing an array:

1
2
3
4

$finder->notPath('first/dir')->notPath('other/dir');

// same as above
$finder->notPath(['first/dir', 'other/dir']);

File Size

Find files by size with the size() method:

1

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

Restrict by a size range by chaining calls or passing an array:

1
2
3
4

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

// same as above
$finder->files()->size(['>= 1K', '<= 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

Find files by last modified dates with the date() method:

1

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

Restrict by a date range by chaining calls or passing an array:

1
2
3
4

$finder->date('>= 2018-01-01')->date('<= 2018-12-31');

// same as above
$finder->date(['>= 2018-01-01', '<= 2018-12-31']);

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 strtotime.

Directory Depth

By default, the Finder recursively traverses directories. Restrict the depth of traversing with depth():

1
2
3

// this will only consider files/directories which are direct children
$finder->depth('== 0');
$finder->depth('< 3');

Restrict by a depth range by chaining calls or passing an array:

1
2
3
4

$finder->depth('> 2')->depth('< 5');

// same as above
$finder->depth(['> 2', '< 5']);

Custom Filtering

To filter results 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.

The filter() method includes a second optional argument to prune directories. If set to true, this method completely skips the excluded directories instead of traversing the entire file/directory structure and excluding them later. When using a closure, return false for the directories which you want to prune.

Pruning directories early can improve performance significantly depending on the file/directory hierarchy complexity and the number of excluded directories.