Локация

Локация - единственный обязательный критерий. Она сообщает Finder, какой каталог использовать для поиска:

1

$finder->in(__DIR__);

Искать в нескльких локациях, изменяя вызов на in():

1
2
3
4
5

// искать внутри *обоих* каталогов
$finder->in(array(__DIR__, '/elsewhere'));

// то же, что и выше
$finder->in(__DIR__)->in('/elsewhere');

Используйте * в качестве символа-заполнителя, чтобы искать в каталогах, соответствующих паттерну (каждый паттерн должен разрешать хотя бы один путь каталога):

1

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

Исключите каталоги, совпадающие с методом exclude():

1
2

// каталоги, переданные в качестве аргумента, должны быть связаны с теми, что определены в методе in()
$finder->in(__DIR__)->exclude('ruby');

Также возможно игнорировать каталоги, на чтение которых у вас нет разрешения:

1

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

Так как Finder использует PHP итераторы, вы можете передать любой URL, поддерживаемый PHP-оберткой для протоколов типа URL (ftp://, zlib://, etc.):

1
2
3
4
5

// всегда добавляйте закрывающий слеш, когда ищете dir корна FTP
$finder->in('ftp://example.com/');

// вы можете также искать в каталоге FTP
$finder->in('ftp://example.com/pub/');

И это также работает с потоками, определёнными пользователями:

1
2
3
4
5
6
7
8
9
10
11

use Symfony\Component\Finder\Finder;

// зарегистрировать обертку 's3://' с официальным 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) {
    // ... сделать что-то с файлом
}

Файлы или каталоги

По умолчанию, Finder возвращает и файлы, и каталоги. Если вам нужны только файлы, или только каталоги, используйте методы files() и directories():

1
2
3
4
5

// искать только файлы; игнорировать каталоги
$finder->files();

// искать только каталоги; игнорировать файлы
$finder->directories();

Если вы хотите следовать символьным ссылкам, используйте метод followLinks():

1

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

Файлы контроля версий

Системы контроля версий (или сокращённо "VCS"), такие как Git и Mercurial, создают специальные файлы для хранения своих метаданных. Эти файлы игнорируются при поиске файлов и каталогов по умолчанию, но вы можете изменить это методом ignoreVCS():

1

$finder->ignoreVCS(false);

Если поисковый каталог и его подкаталоги содержат файлы .gitignore, вы можете повторно использовать эти правила, чтобы исключить файлы и каталоги из результатов, методом ignoreVCSIgnored():

1
2

// исключить files/directories, совпадающие с паттернами .gitignore
$finder->ignoreVCSIgnored(true);

Правила каталога всегда главенствуют над правилами родительских каталогов.

Имя файла

Найдите файлы по имени методом name():

1

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

Метод name() принимает глобальные выражения, строки, регулярные выражения и массивы глобальных или регулярных выражений:

1

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

Множество имен файлов может быть определено путем создания цепочки вызовов или передачи массива:

1
2
3
4

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

// то же, что и выше
$finder->files()->name(['*.php', '*.twig']);

Метод notName() исключает файлы, совпадающие со схемой:

1

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

Множество имен файлов может быть исключено путем создания цепочки вызовов или передачи массива:

1
2
3
4

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

// то же, что и выше
$finder->files()->notName(['*.rb', '*.py']);

Содержание файла

Найдите файлы по содержанию, методом contains():

1

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

Метод contains() принимает строки или регулярные выражения:

1

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

Метод notContains() исключает файлы, содержащие заданный паттерн:

1

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

Путь

Найдите файлы и папки по пути, методом path():

1
2
3
4

// сопоставляет файлы, содержащие "data" где-либо в их путях (файлах или каталогах)
$finder->path('data');
// например, это будет соответстсовать data/*.xml и data.xml, если они существуют
$finder->path('data')->name('*.xml');

Используйте слеш вправо (т.e. /) в качестве разделителя каталогов на всех платформах, включая Windows. Компонент проведет необходимые преобразования внутренне.

Метод path() принимает строку, регулярное выражение или массив строк или регулярных выражений:

1
2

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

Множество путей может быть определено путем создания цепочки вызовов или передачи массива:

1
2
3
4

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

// то же, что и выше
$finder->path(['data', 'foo/bar']);

Внутренне, строки преобразуются в регулярные выражения, экранируя слеши и добавляя разграничители:

Метод notPath() исключает файлы по пути:

1

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

Множество путей можно исключить путем создания цепочки вызовов или передачи массива:

1
2
3
4

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

// то же, что и выше
$finder->notPath(['first/dir', 'other/dir']);

Размер файла

Найдите файлы по размеру, методом size():

1

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

Ограничьте по диапазону размера, создав цепочку вызовов или передав массив:

1
2
3
4

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

// то же, что и выше
$finder->files()->size(['>= 1K', '<= 2K']);

Оператор сравнения может быть чем-либо из следующего: >, >=, <, <=, ==, !=.

Целевое значение может использовать величины килобайтов (k, ki), мегабайтов (m, mi), или гигабайтов (g, gi). Те, что имеют суффикс i, используют соответствующую версию 2**n в соответствии со стандартом IEC.

Дата файла

Найдите файлы по датам последних изменений, методом date() :

1

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

Ограничьте по диапазноу данных путем создания цепочки вызовов или передачи массива:

1
2
3
4

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

// то же, что и выше
$finder->date(['>= 2018-01-01', '<= 2018-12-31']);

Оператор сравнения может быть любым из следующих: >, >=, <, <=, ==. Вы можете также использовать since или after в качестве дополнительного имени >, и until или before в качестве дополнительного имени <.

Целевое значение может быть любыми данными, поддерживаемыми функцией 1c350a865b162006bdcde18296214585964867dd.

Глубина каталога

По умолчанию, Finder траверсирует каталоги в обратном порядке. Ограничьте глубину траверсирования методом depth():

1
2
3

// это будет рассматривать только файлы/каталоги, которые являются прямыми дочерними
$finder->depth('== 0');
$finder->depth('< 3');

Ограничьте по диапазону глубины путем создания цепочки вызовов или передачи массива:

1
2
3
4

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

// то же, что и выше
$finder->depth(['> 2', '< 5']);

Пользовательское фильтрование

Чтобы отфильтровать результаты по собственной стратегии, используйте filter():

1
2
3
4
5
6
7
8

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

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

Метод filter() берёт Closure в качестве аргумента. Для каждого совпадающего файла, он вызываетя с файлом SplFileInfo в качестве экземпляра. Файл исключается из набора результатов, если замыкание возвращает false.

Метод filter() содержит второй необязательный аргумент для обрезки каталогов. Если установить значение true, этот метод полностью пропускает исключенные каталоги вместо того, чтобы обходить всю структуру файлов/каталогов и исключать их позже. При использовании замыкания, верните false для каталогов, которые вы хотите обрезать.

Раннее обрезание каталогов может значительно повысить производительность в зависимости от сложности иерархии файлов/каталогов и количества исключаемых каталогов.

Чтение содержания возвращённых файлов

Содержание возвращённых файлов можно прочитать с помощью getContents():

1
2
3
4
5
6
7
8
9
10

use Symfony\Component\Finder\Finder;

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

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

    // ...
}