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

.[perex]
Potřebujete najít soubory vyhovující určité masce? Finder vám v tom pomůže. Je to všestranný a rychlý nástroj pro procházení adresářové struktury.


Instalace:

```shell
composer require nette/utils
```

Příklady předpokládají vytvořený alias:

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


Použití
-------

Nejprve si ukážeme, jak můžete pomocí [api:Nette\Utils\Finder] vypsat jména souborů s příponami `.txt` a `.md` v aktuálním adresáři:

```php
foreach (Finder::findFiles(['*.txt', '*.md']) as $name => $file) {
	echo $file;
}
```

Výchozí adresář pro hledání je aktuální adresář, ale můžete ho změnit pomocí metod [in() nebo from()|#Kde se má hledat?].
Proměnná `$file` je instancí třídy [FileInfo |#FileInfo] se spoustou užitečných metod. V klíči `$name` je cesta k souboru jako řetězec.


Co se má hledat?
----------------

Kromě metody `findFiles()` existuje i `findDirectories()`, která hledá jen adresáře, a `find()`, která hledá obojí. Tyto metody jsou statické, takže je lze volat bez vytvoření instance. Parameter s maskou je volitelný, pokud ho neuvedete, vyhledá se vše.

```php
foreach (Finder::find() as $file) {
	echo $file; // nyní se vypíší všechny soubory i adresáře
}
```

Pomocí metod `files()` a `directories()` můžete doplňovat co dalšího se má vyhledat. Metody lze volat opakovaně a jako parametr lze uvést i pole masek:

```php
Finder::findDirectories('vendor') // všechny adresáře
	->files(['*.php', '*.phpt']); // plus všechny PHP soubory
```

Alternativou statických metod je vytvoření instance pomocí `new Finder` (takto vytvořený čerstvý objekt nevyhledává nic) a uvedení co hledat pomocí `files()` a `directories()`:

```php
(new Finder)
	->directories()      // všechny adresáře
	->files('*.php');    // plus všechny PHP soubory
```

V masce můžete používat [zástupné znaky|#Zástupné znaky] `*`, `**`, `?` a `[...]`. Dokonce můžete specifikovat i v adresáře, například `src/*.php` vyhledá všechny PHP soubory v adresáři `src`.

Symlinky jsou také považovány za adresáře nebo soubory.


Kde se má hledat?
-----------------

Výchozí adresář pro hledání je aktuální adresář. Změníte ho pomocí metod `in()` a `from()`. Jak je z názvů metod  patrné, `in()` hledá pouze v daném adresáři, zatímco `from()` hledá i v jeho podadresářích (rekurzivně). Pokud chcete vyhledávat rekurzivně v aktuálním adresáři, můžete použít `from('.')`.

Tyto metody lze volat vícekrát nebo jim předat více cest jakožto pole, soubory se pak budou hledat ve všech adresářích. Pokud některý z adresářů neexistuje, vyhodí se výjimka `Nette\UnexpectedValueException`.

```php
Finder::findFiles('*.php')
	->in(['src', 'tests']) // hledá přímo v src/ a tests/
	->from('vendor');      // hledá i v podadresářích vendor/
```

Relativní cesty jsou relativní vůči aktuálnímu adresáři. Lze samozřejme uvést i absolutní cesty:

```php
Finder::findFiles('*.php')
	->in('/var/www/html');
```

V cestě je možné použít zástupné znaky [zástupné znaky|#Zástupné znaky] `*`, `**`, `?`. Můžete tak třeba pomocí cesty `src/*/*.php` hledat všechny PHP soubory v adresářích druhé úrovně v adresáři `src`. Znak `**` nazývaný globstar je mocným trumfem, protože umožňuje hledat i v podadresářích: pomocí `src/**/tests/*.php` hledáte všechny PHP soubory v adresáři `tests` nacházejícím se v `src` nebo jakémkoliv jeho podadresáři.

Naopak zástupné znaky `[...]` v cestě podporovány nejsou, tj. nemají speciální význam, aby nedocházelo k nežádoucímu chování v případě, že budete hledat třeba `in(__DIR__)` a náhodou v cestě se budou vyskytovat znaky `[]`.

Při vyhledávání souborů i adresáře do hloubky se vrací nejprve rodičovský adresář a teprve poté soubory v něm obsažené, což lze obrátit pomocí `childFirst()`.


Zástupné znaky
--------------

V masce můžete používat několik speciálních znaků:

- `*` - nahrazuje libovolný počet libovolných znaků (kromě `/`)
- `**` - nahrazuje libovolný počet libovolných znaků včetně `/` (tj. lze hledat víceúrovňově)
- `?` - nahrazuje jeden libovolný znak (kromě `/`)
- `[a-z]` - nahrazuje jeden znak ze seznamu znaků v hranatých závorkách
- `[!a-z]` - nahrazuje jeden znak mimo seznam znaků v hranatých závorkách

Příklady použití:

- `img/?.png` - soubory s jednopísmenným názvem `0.png`, `1.png`, `x.png`, atd.
- `logs/[0-9][0-9][0-9][0-9]-[01][0-9]-[0-3][0-9].log` - logy ve formátu `YYYY-MM-DD`
- `src/**/tests/*` - soubory v adresáři `src/tests`, `src/foo/tests`, `src/foo/bar/tests` a tak dále.
- `docs/**.md` - všechny soubory s příponou `.md` ve všech podadresářích adresáře `docs`


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

Pomocí metody `exclude()` lze vyloučít soubory a adresáře z vyhledávání. Uvedete masku, které soubor nesmí vyhovovat. Příklad hledání souborů `*.txt` kromě těch, co obsahují v názvu písmeno `X`:

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

Vynechání procházených podadresářů použijte `exclude()`:

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


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

Finder nabízí několik metod pro filtrování výsledků (tj. jejich redukci). Můžete je kombinovat a volat opakovaně.

Pomocí `size()` filtrujeme podle velikosti souboru. Takto najdeme soubory s velikostí v rozmezí 100 až 200 bytů:

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

Metoda `date()` filtruje podle data poslední změny souboru. Hodnoty mohou být absolutní nebo relativní k aktuálnímu datu a času, například takto najdeme soubory změněné v posledních dvou týdnech:

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

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

Finder umožňuje také filtrovat výsledky pomocí vlastních funkcí. Funkce dostane jako parametr objekt `Nette\Utils\FileInfo` a musí vrátit `true`, aby byl soubor zahrnut do výsledků.

Příklad: hledání souborů PHP, které obsahují řetězec `Nette` (bez ohledu na velikost písmen):

```php
Finder::findFiles('*.php')
	->filter(fn($file) => strcasecmp($file->read(), 'Nette') === 0);
```


Filtrování do hloubky
---------------------

Při rekurzivním vyhledávání můžete nastavit maximální hloubku procházení pomocí metody `limitDepth()`. Pokud nastavíte `limitDepth(1)`, prochází se pouze první podadresáře, `limitDepth(0)` vypne procházení do hloubky a hodnota -1 ruší limit.

Finder umožňuje pomocí vlastních funkcí rozhodovat, do kterého adresáře se má při procházení vstupit. Funkce dostane jako parametr objekt `Nette\Utils\FileInfo` a musí vrátit `true`, aby se do adresáře vstoupilo:

```php
Finder::findFiles('*.php')
	->descentFilter($file->getBasename() !== 'temp');
```


Řazení
------

Finder nabízí také několik funkcí pro řazení výsledků.

Metoda `sortByName()` řadí výsledky podle názvů souborů. Řazení je naturální, tedy správně si poradí s čísly v názvech a vrací např. `foo1.txt` před `foo10.txt`.

Finder umožňuje také řadit pomocí vlastní funkce. Ta dostane jako parametr dva objekty `Nette\Utils\FileInfo` a musí vrátit výsledek porovnání operátorem `<=>`, tedy `-1`, `0` nebo `1`. Například takto seřadíme soubory podle velikosti:

```php
$finder->sortBy(fn($a, $b) => $a->getSize() <=> $b->getSize());
```


Více různých hledání
--------------------

Pokud potřebujete najít více různých souborů v různých lokacích nebo splňujích jiná kritéria, použijte metodu `append()`. Vrací nový objekt `Finder`, takže je možné řetězit volání metod:


```php
($finder = new Finder) // do proměnné $finder si uložíme první Finder!
	->files('*.php')   // v src/ hledáme soubory *.php
	->from('src')
	->append()
	->files('*.md')    // v docs/ hledáme soubory *.md
	->from('docs')
	->append()
	->files('*.json'); // v aktuální složce hledáme soubory *.json
```

Alternativně lze použít metodu `append()` pro přidání konkrétního souboru (nebo pole souborů). Pak vrací ten samý objekt `Finder`:

```php
$finder = Finder::findFiles('*.txt')
	->append(__FILE__);
```


FileInfo
--------

[Nette\Utils\FileInfo |api:] je třída reprezentující soubor nebo adresář ve výsledků hledání. Jde o rozšíření třídy [SplFileInfo |php:SplFileInfo], která poskytuje informace, jako je velikost souboru, datum poslední změny, jméno, cesta, atd.

Navic poskytuje metody pro vrácení relativní cesty, což je užitečné při procházení do hloubky:

```php
foreach (Finder::findFiles('*.jpg')->from('.') as $file) {
	$absoluteFilePath = $file->getRealPath();
	$relativeFilePath = $file->getRelativePathname();
}
```

Dále máte k dispozici metody pro přečtení a zápis obsahu souboru:

```php
foreach ($finder as $file) {
    $contents = $file->read();
    // ...
    $file->write($contents);
}
```


Vrácení výsledků jako pole
--------------------------

Jak bylo vidět v příkladech, Finder implementuje rozhraní `IteratorAggregate`, takže můžete použít `foreach` pro procházení výsledků. Je naprogramovaný tak, že výsledky jsou načítány pouze v průběhu procházení, takže pokud máte velké množství souborů, nečeká se, než se všechny přečtou.

Výsledky si můžete nechat také vrátit jako pole objektů `Nette\Utils\FileInfo`, a to metodou `collect()`. Pole není asociativní, ale numerické.

```php
$array = $finder->findFiles('*.php')->collect();
```