Funzioni per il file system

Nette\Utils\FileSystem è una classe con utili funzioni per lavorare con il file system. Un vantaggio rispetto alle funzioni native di PHP è che sollevano eccezioni in caso di errore.

Se avete bisogno di cercare file su disco, usate Finder.

Installazione:

composer require nette/utils

Gli esempi seguenti presuppongono che sia definito questo alias di classe:

use Nette\Utils\FileSystem;

Manipolazione

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

Copia un file o un'intera directory. Per impostazione predefinita sovrascrive i file e le directory esistenti. Se $overwrite è impostato a false e il file o la directory di destinazione $target esiste già, solleva Nette\InvalidStateException. In caso di errore solleva Nette\IOException.

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

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

Crea una directory se non esiste, comprese le directory superiori. In caso di errore solleva Nette\IOException.

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

delete (string $path): void

Elimina un file o un'intera directory, se esistono. Se la directory non è vuota, ne elimina prima il contenuto. In caso di errore solleva Nette\IOException.

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

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

Imposta i permessi del file a $fileMode o quelli della directory a $dirMode. Attraversa ricorsivamente l'intero contenuto della directory e ne imposta i permessi.

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

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

Apre un file e restituisce un handle di risorsa. Il parametro $mode funziona come nella funzione nativa fopen(). In caso di errore solleva Nette\IOException.

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

read (string $file): string

Legge il contenuto del file $file. In caso di errore solleva Nette\IOException.

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

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

Legge il contenuto del file riga per riga. A differenza della funzione nativa file(), non carica l'intero file in memoria ma lo legge progressivamente, il che vi permette di leggere file più grandi della memoria disponibile. $stripNewLines indica se rimuovere i caratteri di a capo \r e \n. In caso di errore solleva Nette\IOException.

$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

Rinomina o sposta il file o la directory indicati da $origin in $target. Per impostazione predefinita sovrascrive i file e le directory esistenti. Se $overwrite è impostato a false e il file o la directory di destinazione $target esiste già, solleva Nette\InvalidStateException. In caso di errore solleva Nette\IOException.

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

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

Scrive la stringa $content nel file $file. Se la directory superiore non esiste, viene creata automaticamente. Per impostazione predefinita imposta anche i permessi del file; passate null come $mode per saltare la chiamata a chmod. In caso di errore solleva Nette\IOException.

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

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

Scrive la stringa $content nel file $file in modo atomico: il contenuto viene prima scritto in un file temporaneo, che poi sostituisce il file di destinazione in un unico passaggio. Chi legge il file nello stesso istante non può quindi mai vederlo scritto a metà o troncato. Per il resto si comporta esattamente come write(). In caso di errore solleva Nette\IOException.

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

Percorsi

isAbsolute (string $path): bool

Stabilisce se il percorso $path è assoluto.

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

isValidFilename (string $name): bool

Controlla se $name è un nome di file valido su tutte le piattaforme, privo di informazioni di percorso. Rifiuta le stringhe vuote, . e .., i caratteri di controllo, i caratteri <>:"|?*\/, i nomi che terminano con un punto o uno spazio e i nomi riservati di Windows (CON, NUL, COM1, …).

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

joinPaths (string …$segments): string

Unisce tutti i segmenti di percorso e ne normalizza il risultato.

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

Normalizza .., . e i separatori di directory del percorso allo standard del sistema.

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

unixSlashes (string $path): string

Converte le barre in /, come si usa nei sistemi Unix.

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

platformSlashes (string $path): string

Converte le barre nei caratteri specifici della piattaforma corrente, cioè \ su Windows e / altrove.

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

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

Ricava il percorso finale da $path relativamente alla directory di base $basePath. I percorsi assoluti (/foo, C:/foo) restano invariati (vengono solo normalizzate le barre), quelli relativi vengono aggiunti al percorso di base.

// su Windows le barre nel risultato sarebbero rovesciate (\)
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'

Approccio statico o non statico

Per sostituire facilmente la classe con un'altra (per esempio con un mock) a scopo di test, usatela in modo non statico:

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

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

	// ...
}