Funciones del sistema de archivos
*********************************

.[perex]
[api:Nette\Utils\FileSystem] es una clase con funciones útiles para trabajar con el sistema de archivos. Una ventaja frente a las funciones nativas de PHP es que lanzan excepciones ante los errores.


Si necesita buscar archivos en el disco, use [Finder|finder].

Instalación:

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

Los ejemplos siguientes suponen que está definido el siguiente alias de clase:

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


Manipulación
============


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

Copia un archivo o un directorio entero. De forma predeterminada sobrescribe los archivos y directorios existentes. Si `$overwrite` se pone a `false` y el archivo o directorio de destino `$target` ya existe, lanza `Nette\InvalidStateException`. Lanza `Nette\IOException` en caso de error.

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


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

Crea un directorio si no existe, incluidos los directorios padre. Lanza `Nette\IOException` en caso de error.

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


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

Elimina un archivo o un directorio entero si existe. Si el directorio no está vacío, elimina primero su contenido. Lanza `Nette\IOException` en caso de error.

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


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

Fija los permisos del archivo a `$fileMode` o los del directorio a `$dirMode`. Recorre recursivamente el contenido del directorio y le fija también los permisos.

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


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

Abre un archivo y devuelve un recurso (handle). El parámetro `$mode` funciona igual que en la función nativa `fopen()`:https://www.php.net/manual/en/function.fopen.php. Lanza `Nette\IOException` en caso de error.

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


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

Lee el contenido del archivo `$file`. Lanza `Nette\IOException` en caso de error.

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


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

Lee el contenido del archivo línea a línea. A diferencia de la función nativa `file()`, no carga todo el archivo en memoria, sino que lo lee de forma continua, lo que permite leer archivos mayores que la memoria disponible. `$stripNewLines` indica si deben eliminarse los caracteres de salto de línea `\r` y `\n`. Lanza `Nette\IOException` en caso de error.

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

Renombra o mueve hacia `$target` el archivo o directorio indicado por `$origin`. De forma predeterminada sobrescribe los archivos y directorios existentes. Si `$overwrite` se pone a `false` y el archivo o directorio de destino `$target` ya existe, lanza `Nette\InvalidStateException`. Lanza `Nette\IOException` en caso de error.

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


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

Escribe la cadena `$content` en el archivo `$file`. Si el directorio padre no existe, se crea automáticamente. De forma predeterminada fija además los permisos del archivo; pase `null` como `$mode` para saltarse la llamada a `chmod`. Lanza `Nette\IOException` en caso de error.

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


writeAtomic(string $file, string $content, ?int $mode=0666): void .[method]{data-version:4.1.5}
-----------------------------------------------------------------------------------------------

Escribe la cadena `$content` en el archivo `$file` de forma atómica: el contenido se escribe primero en un archivo temporal, que después sustituye al destino en un único paso. Quien lea el archivo en ese mismo instante no puede, por tanto, verlo escrito a medias ni truncado. Por lo demás se comporta exactamente como `write()`. Lanza `Nette\IOException` en caso de error.

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


Rutas
=====


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

Determina si la ruta `$path` es absoluta.

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


isValidFilename(string $name): bool .[method]
---------------------------------------------

Comprueba si `$name` es un nombre de archivo válido en todas las plataformas y sin información de ruta. Rechaza las cadenas vacías, `.` y `..`, los caracteres de control, los caracteres `<>:"|?*\/`, los nombres que acaban en punto o espacio y los nombres reservados de Windows (`CON`, `NUL`, `COM1`, …).

```php
FileSystem::isValidFilename('photo.jpg');    // true
FileSystem::isValidFilename('../photo.jpg'); // false
FileSystem::isValidFilename('CON');          // false
```


joinPaths(string ...$segments): string .[method]
------------------------------------------------
Une todos los segmentos de ruta y normaliza el resultado.

```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]
---------------------------------------------
Normaliza `..`, `.` y los separadores de directorio de la ruta al estándar del sistema.

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


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

Convierte las barras a `/`, las usadas en los sistemas Unix.

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


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

Convierte las barras a los caracteres propios de la plataforma actual, es decir, `\` en Windows y `/` en el resto.

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


resolvePath(string $basePath, string $path): string .[method]{data-version:4.0.6}
---------------------------------------------------------------------------------

Resuelve la ruta final a partir de `$path` respecto al directorio base `$basePath`. Las rutas absolutas (`/foo`, `C:/foo`) quedan sin cambios (solo se normalizan las barras); las relativas se añaden a la ruta base.

```php
// En Windows, las barras de la salida estarían invertidas (\)
FileSystem::resolvePath('/base/dir', '/abs/path');      // '/abs/path'
FileSystem::resolvePath('/base/dir', 'rel');            // '/base/dir/rel'
FileSystem::resolvePath('base/dir', '../file.txt');     // 'base/file.txt'
FileSystem::resolvePath('base', '');                    // 'base'
```


Enfoque estático frente a no estático
=====================================

Para poder sustituir con facilidad la clase por otra (por ejemplo, un mock) con fines de prueba, úsela de forma no estática:

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

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

	// ...
}
```