Nette Documentation Preview

syntax
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í.

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

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


Instalace
---------

Knihovnu stáhnete a nainstalujete pomocí nástroje [Composer|/best-practices/composer]:

```shell
composer require nette/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}}
{{leftbar: utils/@left-menu}}

Finder: vyhledávání souborů

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

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

use Nette\Utils\Finder;

Instalace

Knihovnu stáhnete a nainstalujete pomocí nástroje Composer:

composer require nette/finder

Hledání souborů

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

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.

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

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

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

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

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

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:

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ářů:

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:

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

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

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

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

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:

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:

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