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], zatímco `$name` je řetězec s cestou k souboru.

Cesta se vrací tak, jak jste ji zapsali, se zachovanými oddělovači platformy; na Windows tak výsledek může míchat `/` a `\`. Pokud potřebujete jednotný tvar, zavolejte `FileSystem::unixSlashes()`.


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. Parametr 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] jako `*`, `**`, `?` a `[...]`. Dokonce můžete specifikovat i adresáře, například `src/*.php` najde 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()`:

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

Metody se liší hloubkou: `in()` hledá pouze v daném adresáři, zatímco `from()` sestupuje i do jeho podadresářů (rekurzivně). Pokud chcete prohledat aktuální adresář rekurzivně, použijte `from('.')`.

Rekurzi ovšem neurčuje jen `from()` - řídí ji i zástupný znak `**` v masce, takže `findFiles('**/*.php')->in('src')` také hledá rekurzivně. Jinak řečeno, `from('src')` je jen zkratka za `in('src')` s rekurzivní maskou. Viz [#Zástupné znaky].

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\InvalidStateException`.

Relativní cesty jsou relativní vůči aktuálnímu adresáři, lze ale uvést i cesty absolutní:

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

V cestě lze použít zástupné znaky `*`, `**` a `?`, ale **ne** `[...]`, které se tam berou doslova. Tím se předchází nežádoucímu chování, když třeba hledáte `in(__DIR__)` a v cestě se náhodou vyskytnou znaky `[]`. Například `src/*/*.php` hledá všechny PHP soubory v adresářích druhé úrovně v adresáři `src`.

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

Maska může obsahovat několik speciálních znaků:

- `*` - libovolný počet znaků, kromě oddělovače `/` (zůstává v rámci jedné úrovně adresářů)
- `**` - libovolný počet znaků, **včetně** `/` (překlenuje úrovně adresářů, viz níže)
- `?` - právě jeden znak, kromě `/`
- `[a-z]` - jeden znak z rozsahu nebo výčtu v hranatých závorkách
- `[!a-z]` - jeden znak, který v závorkách *není*

Zásadní a snadno přehlédnutelný bod: `**` matchuje **nula a více** úrovní adresářů. *Neznamená* „aspoň jeden podadresář". Proto `src/**/*.php` odpovídá souboru ležícímu přímo v `src` stejně dobře jako souboru zanořenému o několik úrovní hlouběji. Uvažujme tento strom:

/--pre
src/
├── app.php
├── Model/
│   ├── User.php
│   └── Repository/
│       └── UserRepository.php
└── Control/
    └── SignForm.php
\--

Následující tabulka ukazuje, co jednotlivé masky najdou, a to pro soubory i adresáře:

|-------------------------------------------------------------------------------
| Maska | Najde
|-------------------------------------------------------------------------------
| `src/*.php` | jen `src/app.php` (přímo v `src`)
| `src/**/*.php` | `src/app.php`, `src/Model/User.php`, `src/Model/Repository/UserRepository.php` (**všechny úrovně, včetně přímo v `src`**)
| `src/*` | přímé potomky `src`: `app.php`, `Model`, `Control`
| `src/**` | vše pod `src`, soubory i adresáře (zkratka za `src/**/*`)
| `src/*/` | přímé *podadresáře* `src`: `Model`, `Control`
| `src/**/` | *všechny* podadresáře v jakékoliv hloubce: `Model`, `Model/Repository`, `Control`

Za zapamatování stojí dvě zkratky:

- `**`, za kterým bezprostředně nenásleduje `/`, se chová jako `**/` plus `*`. Takže `src/**` je zkratka za `src/**/*` a `**.php` za `**/*.php`.
- Koncové lomítko omezí masku jen na adresáře. Takže `find('log/')` vrátí adresáře jménem `log`, ale nikdy stejnojmenný soubor. (`findFiles()` koncové lomítko odmítne, protože hledat soubor-„adresář" nedává smysl.)

Další příklady použití:

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


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

Pomocí metody `exclude()` lze vyloučit soubory a adresáře z výsledků. Parametrem je maska, které položka **nesmí** vyhovovat. Zde hledáme soubory `*.txt` kromě těch, co obsahují v názvu písmeno `X`:

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

Maska pro vyloučení používá úplně stejnou gramatiku jako masky pro hledání - stejné [#zástupné znaky], kotvení přes `./` i zkratku `**`. Její koncová část určuje rozsah vyloučení:

|-------------------------------------------------------------------------------
| Maska | Vyloučí
|-------------------------------------------------------------------------------
| `temp` | jakýkoliv soubor nebo adresář jménem `temp`, v jakékoliv hloubce
| `temp/` | jen adresář `temp` (a jeho obsah); soubor jménem `temp` zůstane
| `temp/*` | obsah `temp`, ale samotný adresář `temp` ponechá
| `temp/**` | totéž jako `temp/*`

Vyloučený adresář se při procházení ani neotevře, takže vyloučení celých podstromů hledání i zrychluje. Takto přeskočíte konkrétní podadresáře:

```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) => str_contains(strtolower($file->read()), 'nette'));
```


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í vstoupit. Funkce dostane jako parametr objekt `Nette\Utils\FileInfo` a musí vrátit `true`, aby se do adresáře vstoupilo:

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


Nečitelné adresáře
------------------

Ve výchozím nastavení Finder přeskočí adresáře, které nemůže přečíst (například kvůli nedostatečným oprávněním). Pokud chcete, aby v takovém případě místo toho vyhodil výjimku, zavolejte `ignoreUnreadableDirs(false)`.

```php
Finder::findFiles('*.php')
	->from($dir)
	->ignoreUnreadableDirs(false);
```


Ř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ící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ýsledcích 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.

Navíc 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();
```