Finder: vyhledávání souborů
***************************

.[perex]
Potřebujete projít adresáře na disku? Hledáte v nich soubory? Třída [api:Nette\Utils\Finder] vám to maximálně usnadní.



Instalace:

```shell
composer require nette/finder
```

Všechny příklady předpokládají vytvořený alias:

```php
use Nette\Utils\Finder;
```


Hledání souborů
---------------

Jak vyhledat soubory `*.txt` v adresáři `$dir` a všech jeho podadresářích?

```php
foreach (Finder::findFiles('*.txt')->from($dir) as $key => $file) {
	// $key je řetězec s názvem souboru včetně cesty
	// $file je objekt SplFileInfo
}
```

Soubory v proměnné `$file` jsou instance třídy [SplFileInfo |php:SplFileInfo].

Pokud by adresář neexistoval, vyhodí se výjimka `Nette\UnexpectedValueException`.

A co třeba hledání souborů v adresáři bez procházení podadresářů? Místo `from()` použijeme `in()`:

```php
Finder::findFiles('*.txt')->in($dir)
```

Hledání podle více masek a dokonce z více adresářů najednou:

```php
Finder::findFiles('*.txt', '*.php')
	->in($dir1, $dir2) // nebo from($dir1, $dir2)
```

přičemž parametry lze zadat i ve formě polí:

```php
Finder::findFiles(['*.txt', '*.php'])
	->in([$dir1, $dir2]) // nebo from([$dir1, $dir2])
```

Omezit hloubku procházení lze metodou `limitDepth()`.


Hledání adresářů
----------------

Kromě souborů lze hledat také adresáře pomocí `Finder::findDirectories('subdir*')`.

Nebo soubory i adresáře dohromady pomocí `Finder::find('*.txt')`, maska se v tomto případě vztahuje jen na soubory. Při hledání do hloubky pomocí `from()` se vrací nejprve podadresář a teprve poté soubory v něm obsažené, což lze obrátit pomocí `childFirst()`.


Maska
-----

Maska nemusí popisovat jen název souboru, ale také cestu. Příklad: hledání souborů `*.jpg` umístěných v podadresáři začínajícím na `imag`:

```php
Finder::findFiles('imag*/*.jpg')
```

Známé zástupné symboly `*` a `?` tedy představují libovolné znaky s výjimkou oddělovače adresářů `/`. Dvojitý `**` představuje libovolné znaky včetně oddělovače adresářů:

```php
Finder::findFiles('imag**/*.jpg')
// najde i image/subdir/file.jpg
```

V masce můžete používat i rozsahy `[...]` nebo negativní rozsahy `[!...]` známé z regulárních výrazů. Hledání souborů `*.txt` obsahujících číslici v názvu:

```php
Finder::findFiles('*[0-9]*.txt')
```


Vyloučení
---------

Pomocí `exclude()` můžete předat masky, kterým naopak soubor nesmí vyhovovat. Hledání souborů `*.txt` kromě těch, co obsahují v názvu písmeno `X`

```php
Finder::findFiles('*.txt')
	->exclude('*X*')
```

Pokud `exclude()` uvedeme **až za** `from()`, vztahuje se na procházené podadresáře:

```php
Finder::findFiles('*.php')
	->from($dir)
	->exclude('temp', '.git')
```


Filtrování
----------

Dále je možné výsledky filtrovat, například podle velikosti souboru. Takto najdeme soubory s velikostí v rozmezí 100 až 200 bytů:

```php
Finder::findFiles('*.php')
	->size('>=', 100)
	->size('<=', 200)
	->from($dir)
```

Filtrování podle data poslední změny. Příklad: hledání souborů změněných v posledních dvou týdnech:

```php
Finder::findFiles('*.php')
	->date('>', '- 2 weeks')
	->from($dir)
```

Obě funkce rozumí operátorům `>`, `>=`, `<`, `<=`, `=`, `!=`.

Zde se prochází soubory PHP s počtem řádků větším než 1000. Jako filtr použijeme vlastní callback:

```php
$hasMoreThan100Lines = function (SplFileInfo $file): bool {
	return count(file($file->getPathname())) > 1000;
};

Finder::findFiles('*.php')
	->filter($hasMoreThan100Lines)
```

Šikovné, že? Finder určitě najde využití ve vašich aplikacích.


{{composer: nette/finder}}