The Finder Component

小技巧

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 iterator_to_array method, or get the number of items with iterator_count.

警告

When searching through multiple locations passed to the in() method, a separate iterator is created internally for every location. This means we have multiple result sets aggregated into one. Since iterator_to_array uses keys of result sets by default, when converting to an array, some keys might be duplicated and their values overwritten. This can be avoided by passing false as a second parameter to iterator_to_array.

Location¶

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

$finder->in(__DIR__);

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

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

Use wildcard characters to search in the directories matching a pattern:

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

Each pattern has to resolve to at least one directory path.

Exclude directories from matching with the exclude() method:

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

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

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

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

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

And it also works with user-defined streams:

use SymfonyComponentFinderFinder;

$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:

$finder->files();

$finder->directories();

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

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

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

$finder->ignoreVCS(false);

Sorting¶

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

$finder->sortByName();

$finder->sortByType();

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

$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:

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

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

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

The notName() method excludes files matching a pattern:

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

File Contents¶

Restrict files by contents with the contains() method:

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

The contains() method accepts strings or regexes:

$finder->files()->contains('/lorems+ipsum$/i');

The notContains() method excludes files containing given pattern:

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

Path¶

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

$finder->path('some/special/dir');

On all platforms slash (i.e. /) should be used as the directory separator.

The path() method accepts a string or a regular expression:

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

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

dirname    ===>    /dirname/
a/b/c      ===>    /a/b/c/

The notPath() method excludes files by path:

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

File Size¶

Restrict files by size with the size() method:

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

Restrict by a size range by chaining calls:

$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:

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

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

Custom Filtering¶

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

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

Reading Contents of Returned Files¶

The contents of returned files can be read with getContents():

use SymfonyComponentFinderFinder;

$finder = new Finder();
$finder->files()->in(__DIR__);

foreach ($finder as $file) {
    $contents = $file->getContents();

    // ...
}