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

.[perex]
[api:Nette\Utils\FileSystem] es una clase que contiene funciones útiles para trabajar con un sistema de archivos. Una ventaja sobre las funciones nativas de PHP es que lanzan excepciones en caso de errores.


Si necesitas buscar archivos en el disco, utiliza el [Finder |finder].

Instalación:

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

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

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


Manipulación .[#toc-manipulation]
=================================


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

Copia un archivo o un directorio completo. Sobrescribe los archivos y directorios existentes por defecto. Si `$overwrite` se establece en `false` y ya existe un `$target`, lanza una excepción `Nette\InvalidStateException`. Lanza una excepción `Nette\IOException` en caso de error.

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


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

Crea un directorio si no existe, incluyendo los directorios padre. Lanza una excepción `Nette\IOException` en caso de error.

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


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

Borra un fichero o un directorio entero si existe. Si el directorio no está vacío, borra primero su contenido. Lanza una excepción `Nette\IOException` en caso de error.

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


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

Establece los permisos de archivo a `$fileMode` o los permisos de directorio a `$dirMode`. Recursivamente recorre y establece permisos en todo el contenido del directorio también.

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


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

Abre el archivo y devuelve el recurso. El parámetro `$mode` funciona igual que la función nativa `fopen()`:https://www.php.net/manual/en/function.fopen.php. Si se produce un error, lanza la excepción `Nette\IOException`.

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


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

Lee el contenido de un `$file`. Lanza una excepción `Nette\IOException` si se produce un error.

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


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

Lee el contenido del fichero línea a línea. A diferencia de la función nativa `file()`, no lee todo el fichero en memoria, sino que lo lee de forma continua, de modo que se pueden leer ficheros mayores que la memoria disponible. `$stripNewLines` especifica si se eliminan los caracteres de salto de línea de `\r` y `\n`.
En caso de error, lanza una excepción `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]
----------------------------------------------------------------------------

Renombra o mueve un archivo o un directorio especificado por `$origin` a `$target`. Sobrescribe los archivos y directorios existentes por defecto. Si `$overwrite` se establece en `false` y `$target` ya existe, lanza una excepción `Nette\InvalidStateException`. Lanza una excepción `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 `$content` en `$file`. Lanza una excepción `Nette\IOException` si se produce un error.

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


Rutas .[#toc-paths]
===================


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

Determina si la dirección `$path` es absoluta.

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


joinPaths(string ...$segments): string .[method]
------------------------------------------------
Une todos los segmentos de la 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 `.` y los separadores de directorio de la ruta.

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


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

Convierte las barras oblicuas en `/` utilizadas en los sistemas Unix.

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


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

Convierte las barras inclinadas en caracteres específicos de la plataforma actual, es decir, `\` en Windows y `/` en otros sistemas.

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


Enfoque estático frente a no estático .[#toc-static-vs-non-static-approach]
===========================================================================

Para reemplazar fácilmente la clase `FileSystem` por otra clase, por ejemplo para realizar pruebas, utilícela de forma no estática:

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

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

	...
}
```