Funciones del sistema de archivos

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.

Instalación:

composer require nette/utils

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

use Nette\Utils\FileSystem;

Manipulación

copy (string $origin, string $target, bool $overwrite=true): void

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.

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

createDir (string $dir, int $mode=0777): void

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

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

delete (string $path): void

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.

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

makeWritable (string $path, int $dirMode=0777, int $fileMode=0666): void

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.

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

open (string $path, string $mode): resource

Abre un archivo y devuelve un recurso (handle). El parámetro $mode funciona igual que en la función nativa fopen(). Lanza Nette\IOException en caso de error.

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

read (string $file): string

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

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

readLines (string $file, bool $stripNewLines=true): \Generator

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.

$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

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.

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

write (string $file, string $content, ?int $mode=0666): void

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.

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

writeAtomic (string $file, string $content, ?int $mode=0666): void

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.

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

Rutas

isAbsolute (string $path): bool

Determina si la ruta $path es absoluta.

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

isValidFilename (string $name): bool

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, …).

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

joinPaths (string …$segments): string

Une todos los segmentos de ruta y normaliza el resultado.

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

Normaliza .., . y los separadores de directorio de la ruta al estándar del sistema.

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

unixSlashes (string $path): string

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

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

platformSlashes (string $path): string

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

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

resolvePath (string $basePath, string $path): string

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.

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

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

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

	// ...
}