Fonctions du système de fichiers
********************************

.[perex]
[api:Nette\Utils\FileSystem] est une classe qui contient des fonctions utiles pour travailler avec un système de fichiers. Un avantage par rapport aux fonctions natives de PHP est qu'elles lèvent des exceptions en cas d'erreur.


Si vous devez rechercher des fichiers sur le disque, utilisez le [Finder |finder].

Installation :

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

Les exemples suivants supposent que l'alias de classe suivant est défini :

```php
use Nette\Utils\FileSystem;
```


Manipulation .[#toc-manipulation]
=================================


copy(string $origin, string $target, bool $overwrite=true): void .[method]
--------------------------------------------------------------------------

Copie un fichier ou un répertoire entier. Ecrase les fichiers et répertoires existants par défaut. Si `$overwrite` a pour valeur `false` et qu'un `$target` existe déjà, lance une exception `Nette\InvalidStateException`. Lance une exception `Nette\IOException` en cas d'erreur.

```php
FileSystem::copy('/path/to/source', '/path/to/dest', overwrite: true);
```


createDir(string $directory, int $mode=0777): void .[method]
------------------------------------------------------------

Crée un répertoire s'il n'existe pas, y compris les répertoires parents. Lance une exception `Nette\IOException` en cas d'erreur.

```php
FileSystem::createDir('/path/to/dir');
```


delete(string $path): void .[method]
------------------------------------

Supprime un fichier ou un répertoire entier s'il existe. Si le répertoire n'est pas vide, il supprime son contenu en premier. Lance une exception `Nette\IOException` en cas d'erreur.

```php
FileSystem::delete('/path/to/fileOrDir');
```


makeWritable(string $path, int $dirMode=0777, int $fileMode=0666): void .[method]
---------------------------------------------------------------------------------

Définit les permissions des fichiers à `$fileMode` ou les permissions des répertoires à `$dirMode`. Parcourt récursivement et définit également les autorisations sur l'ensemble du contenu du répertoire.

```php
FileSystem::makeWritable('/path/to/fileOrDir');
```


open(string $path, string $mode): resource .[method]
----------------------------------------------------

Ouvre le fichier et retourne la ressource. Le paramètre `$mode` fonctionne de la même manière que la fonction native `fopen()`:https://www.php.net/manual/en/function.fopen.php. Si une erreur se produit, elle soulève l'exception `Nette\IOException`.

```php
$res = FileSystem::open('/path/to/file', 'r');
```


read(string $file): string .[method]
------------------------------------

Lit le contenu d'un fichier `$file`. Lance une exception `Nette\IOException` si une erreur se produit.

```php
$content = FileSystem::read('/path/to/file');
```


readLines(string $file, bool $stripNewLines=true): \Generator .[method]
-----------------------------------------------------------------------

Lit le contenu du fichier ligne par ligne. Contrairement à la fonction native `file()`, elle ne lit pas le fichier entier en mémoire, mais le lit de manière continue, de sorte que les fichiers plus grands que la mémoire disponible peuvent être lus. Le paramètre `$stripNewLines` indique s'il faut supprimer les caractères de saut de ligne `\r` et `\n`.
En cas d'erreur, elle lève une exception `Nette\IOException`.

```php
$lines = FileSystem::readLines('/path/to/file');

foreach ($lines as $lineNum => $line) {
	echo "Line $lineNum: $line\n";
}
```


rename(string $origin, string $target, bool $overwrite=true): void .[method]
----------------------------------------------------------------------------

Renomme ou déplace un fichier ou un répertoire spécifié par `$origin` vers `$target`. Ecrase les fichiers et répertoires existants par défaut. Si `$overwrite` a pour valeur `false` et que `$target` existe déjà, lance une exception `Nette\InvalidStateException`. Lance une exception `Nette\IOException` en cas d'erreur.

```php
FileSystem::rename('/path/to/source', '/path/to/dest', overwrite: true);
```


write(string $file, string $content, int $mode=0666): void .[method]
--------------------------------------------------------------------

Écrit l'adresse `$content` dans un fichier `$file`. Lance une exception `Nette\IOException` si une erreur se produit.

```php
FileSystem::write('/path/to/file', $content);
```


Chemins d'accès .[#toc-paths]
=============================


isAbsolute(string $path): bool .[method]
----------------------------------------

Détermine si le site `$path` est absolu.

```php
FileSystem::isAbsolute('../backup'); // false
FileSystem::isAbsolute('/backup');   // true
FileSystem::isAbsolute('C:/backup'); // true
```


joinPaths(string ...$segments): string .[method]
------------------------------------------------
Joint tous les segments du chemin et normalise le résultat.

```php
FileSystem::joinPaths('a', 'b', 'file.txt'); // 'a/b/file.txt'
FileSystem::joinPaths('/a/', '/b/');         // '/a/b/'
FileSystem::joinPaths('/a/', '/../b');       // '/b'
```


normalizePath(string $path): string .[method]
---------------------------------------------
Normalise `..` et `.` et les séparateurs de répertoire dans le chemin.

```php
FileSystem::normalizePath('/file/.');        // '/file/'
FileSystem::normalizePath('\file\..');       // '/file'
FileSystem::normalizePath('/file/../..');    // '/..'
FileSystem::normalizePath('file/../../bar'); // '/../bar'
```


unixSlashes(string $path): string .[method]
-------------------------------------------

Convertit les barres obliques en `/` utilisées sur les systèmes Unix.

```php
$path = FileSystem::unixSlashes($path);
```


platformSlashes(string $path): string .[method]
-----------------------------------------------

Convertit les barres obliques en caractères spécifiques à la plate-forme actuelle, c'est-à-dire `\` sous Windows et `/` ailleurs.

```php
$path = FileSystem::platformSlashes($path);
```


Approche statique ou non statique .[#toc-static-vs-non-static-approach]
=======================================================================

Pour remplacer facilement la classe `FileSystem` par une autre classe, par exemple à des fins de test, utilisez-la de manière non statique :

```php
class AnyClassUsingFileSystem
{
	public function __construct(
		private FileSystem $fileSystem,
	) {
	}

	public function readConfig(): string
	{
		return $this->fileSystem->read(/* ... */);
	}

	...
}
```