Finder : Recherche de fichiers
******************************

.[perex]
Vous avez besoin de trouver des fichiers correspondant à un certain masque ? Le Finder peut vous aider. Il s'agit d'un outil polyvalent et rapide pour parcourir la structure des répertoires.


Installation :

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

Les exemples supposent qu'un alias a été créé :

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


Utilisation de .[#toc-using]
----------------------------

Tout d'abord, voyons comment vous pouvez utiliser [api:Nette\Utils\Finder] pour lister les noms de fichiers avec les extensions `.txt` et `.md` dans le répertoire actuel :

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

Le répertoire par défaut pour la recherche est le répertoire courant, mais vous pouvez le changer en utilisant les méthodes [in() ou from() |#Where to search?].
La variable `$file` est une instance de la classe [FileInfo |#FileInfo] avec de nombreuses méthodes utiles. La clé `$name` contient le chemin d'accès au fichier sous forme de chaîne.


Que rechercher ? .[#toc-what-to-search-for]
-------------------------------------------

En plus de la méthode `findFiles()`, il existe également `findDirectories()`, qui ne recherche que les répertoires, et `find()`, qui recherche les deux. Ces méthodes sont statiques, elles peuvent donc être appelées sans créer d'instance. Le paramètre mask est facultatif, si vous ne le spécifiez pas, tout est recherché.

```php
foreach (Finder::find() as $file) {
	echo $file; // maintenant tous les fichiers et répertoires sont listés
}
```

Utilisez les méthodes `files()` et `directories()` pour ajouter ce qui doit être recherché. Ces méthodes peuvent être appelées à plusieurs reprises et un tableau de masques peut être fourni en tant que paramètre :

```php
Finder::findDirectories('vendor') // tous les répertoires
	->files(['*.php', '*.phpt']); // plus tous les fichiers PHP
```

Une alternative aux méthodes statiques est de créer une instance à l'aide de `new Finder` (l'objet frais créé de cette façon ne cherche rien) et de spécifier ce qu'il faut rechercher à l'aide de `files()` et `directories()`:

```php
(new Finder)
	->directories()    // tous les répertoires
	->files('*.php');  // plus tous les fichiers PHP
```

Vous pouvez utiliser des [caractères génériques |#wildcards] `*`, `**`, `?` and `[...]` dans le masque. Vous pouvez même spécifier des répertoires, par exemple `src/*.php` recherchera tous les fichiers PHP dans le répertoire `src`.

Les liens symboliques sont également considérés comme des répertoires ou des fichiers.


Où chercher ? .[#toc-where-to-search]
-------------------------------------

Le répertoire de recherche par défaut est le répertoire courant. Vous pouvez le modifier en utilisant les méthodes `in()` et `from()`. Comme vous pouvez le constater d'après les noms des méthodes, `in()` ne recherche que dans le répertoire courant, tandis que `from()` recherche également dans ses sous-répertoires (de manière récursive). Si vous souhaitez effectuer une recherche récursive dans le répertoire courant, vous pouvez utiliser `from('.')`.

Ces méthodes peuvent être appelées plusieurs fois ou vous pouvez leur passer plusieurs chemins sous forme de tableaux, les fichiers seront alors recherchés dans tous les répertoires. Si l'un des répertoires n'existe pas, un message d'erreur ( `Nette\UnexpectedValueException` ) est lancé.

```php
Finder::findFiles('*.php')
	->in(['src', 'tests']) // recherche directement dans src/ et tests/
	->from('vendor');      // recherche également dans les sous-répertoires vendor/
```

Les chemins relatifs sont relatifs au répertoire actuel. Bien sûr, des chemins absolus peuvent également être spécifiés :

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

Les [caractères |#wildcards] génériques `*`, `**`, `?` can be used in the path. For example, you can use the path `src/*/*.php` pour rechercher tous les fichiers PHP dans les répertoires de deuxième niveau du répertoire `src`. Le caractère `**`, appelé globstar, est un atout puissant car il vous permet de rechercher également dans les sous-répertoires : utilisez `src/**/tests/*.php` pour rechercher tous les fichiers PHP du répertoire `tests` situés dans `src` ou n'importe lequel de ses sous-répertoires.

D'autre part, les caractères de remplacement `[...]` ne sont pas pris en charge dans le chemin d'accès, c'est-à-dire qu'ils n'ont pas de signification particulière pour éviter tout comportement indésirable dans le cas où vous recherchez par exemple `in(__DIR__)` et que par hasard les caractères `[]` apparaissent dans le chemin d'accès.

Lors d'une recherche approfondie de fichiers et de répertoires, le répertoire parent est renvoyé en premier et ensuite les fichiers qu'il contient, ce qui peut être inversé avec `childFirst()`.


Caractères génériques .[#toc-wildcards]
---------------------------------------

Vous pouvez utiliser plusieurs caractères spéciaux dans le masque :

- `*` - replaces any number of arbitrary characters (except `/`)
- `**` - remplace un nombre quelconque de caractères arbitraires, y compris `/` (c'est-à-dire qu'il peut être recherché sur plusieurs niveaux)
- `?` - replaces one arbitrary character (except `/`)
- `[a-z]` - remplace un caractère de la liste de caractères entre crochets.
- `[!a-z]` - remplace un caractère en dehors de la liste de caractères entre crochets

Exemples d'utilisation :

- `img/?.png` - fichiers avec le nom à une lettre `0.png`, `1.png`, `x.png`, etc.
- `logs/[0-9][0-9][0-9][0-9]-[01][0-9]-[0-3][0-9].log` - fichiers journaux au format `YYYY-MM-DD`
- `src/**/tests/*` - fichiers dans le répertoire `src/tests`, `src/foo/tests`, `src/foo/bar/tests` et ainsi de suite.
- `docs/**.md` - tous les fichiers avec l'extension `.md` dans tous les sous-répertoires du répertoire `docs`


A l'exception de .[#toc-excluding]
----------------------------------

Utilisez la méthode `exclude()` pour exclure des fichiers et des répertoires des recherches. Vous spécifiez un masque auquel le fichier ne doit pas correspondre. Exemple de recherche de fichiers `*.txt` à l'exception de ceux contenant la lettre `X` dans le nom :

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

Utilisez `exclude()` pour ignorer les sous-répertoires parcourus :

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


Filtrage de .[#toc-filtering]
-----------------------------

Le Finder propose plusieurs méthodes pour filtrer les résultats (c'est-à-dire les réduire). Vous pouvez les combiner et les appeler à plusieurs reprises.

Utilisez `size()` pour filtrer par taille de fichier. De cette façon, nous trouvons les fichiers dont la taille est comprise entre 100 et 200 octets :

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

La méthode `date()` permet de filtrer par la date de la dernière modification du fichier. Les valeurs peuvent être absolues ou relatives à la date et à l'heure actuelles. Par exemple, voici comment trouver les fichiers modifiés au cours des deux dernières semaines :

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

Les deux fonctions comprennent les opérateurs `>`, `>=`, `<`, `<=`, `=`, `!=`, `<>`.

Le Finder vous permet également de filtrer les résultats à l'aide de fonctions personnalisées. La fonction reçoit un objet `Nette\Utils\FileInfo` comme paramètre et doit retourner `true` pour inclure le fichier dans les résultats.

Exemple : rechercher les fichiers PHP qui contiennent la chaîne de caractères `Nette` (insensible à la casse) :

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


Filtrage en profondeur .[#toc-depth-filtering]
----------------------------------------------

Lors d'une recherche récursive, vous pouvez définir la profondeur d'exploration maximale à l'aide de la méthode `limitDepth()`. Si vous définissez `limitDepth(1)`, seuls les premiers sous-répertoires sont explorés, `limitDepth(0)` désactive l'exploration en profondeur, et une valeur de -1 annule la limite.

Le Finder vous permet d'utiliser ses propres fonctions pour décider du répertoire à pénétrer lors de l'exploration. La fonction reçoit un objet `Nette\Utils\FileInfo` comme paramètre et doit retourner `true` pour entrer dans le répertoire :

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


Triage .[#toc-sorting]
----------------------

Le Finder offre également plusieurs fonctions permettant de trier les résultats.

La méthode `sortByName()` trie les résultats par nom de fichier. Le tri est naturel, c'est-à-dire qu'il traite correctement les chiffres dans les noms et renvoie par exemple `foo1.txt` avant `foo10.txt`.

Le Finder vous permet également de trier en utilisant une fonction personnalisée. Elle prend deux objets `Nette\Utils\FileInfo` comme paramètres et doit retourner le résultat de la comparaison avec l'opérateur `<=>`c'est-à-dire `-1`, `0` nebo `1`. Par exemple, voici comment trier les fichiers par taille :

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


Plusieurs recherches différentes .[#toc-multiple-different-searches]
--------------------------------------------------------------------

Si vous devez trouver plusieurs fichiers différents dans des endroits différents ou répondant à des critères différents, utilisez la méthode `append()`. Elle renvoie un nouvel objet `Finder` afin que vous puissiez enchaîner les appels de méthode :


```php
($finder = new Finder) // enregistre le premier Finder dans la variable $finder !
	->files('*.php')   // recherche les fichiers *.php dans src/
	->from('src')
	->append()
	->files('*.md')    // dans docs/ recherche les fichiers *.md
	->from('docs')
	->append()
	->files('*.json'); // dans le dossier actuel, recherche des fichiers *.json
```

Alternativement, vous pouvez utiliser la méthode `append()` pour ajouter un fichier spécifique (ou un tableau de fichiers). Elle renvoie alors le même objet `Finder`:

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


FileInfo .[#toc-fileinfo]
-------------------------

[Nette\Utils\FileInfo |api:] est une classe représentant un fichier ou un répertoire dans les résultats de recherche. Il s'agit d'une extension de la classe [SplFileInfo |php:SplFileInfo] qui fournit des informations telles que la taille du fichier, la date de dernière modification, le nom, le chemin, etc.

De plus, elle fournit des méthodes pour renvoyer les chemins relatifs, ce qui est utile lors d'une navigation en profondeur :

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

Vous disposez également de méthodes pour lire et écrire le contenu d'un fichier :

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


Renvoyer les résultats sous forme de tableau .[#toc-returning-results-as-an-array]
----------------------------------------------------------------------------------

Comme nous l'avons vu dans les exemples, le Finder implémente l'interface `IteratorAggregate`, ce qui vous permet d'utiliser `foreach` pour parcourir les résultats. Il est programmé de manière à ce que les résultats ne soient chargés qu'au fur et à mesure de la navigation, donc si vous avez un grand nombre de fichiers, il n'attend pas qu'ils soient tous lus.

Vous pouvez également obtenir les résultats sous la forme d'un tableau d'objets `Nette\Utils\FileInfo`, en utilisant la méthode `collect()`. Le tableau n'est pas associatif, mais numérique.

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