Souborový systém

Nette\Utils\FileSystem je třída s užitečnými funkcemi pro práci se souborovým systémem. Jednou z výhod oproti nativním PHP funkcím je, že v případě chyby vyhazují výjimky.

Pokud potřebujete hledat soubory na disku, použijte Finder.

Instalace:

composer require nette/utils

Následující příklady předpokládají vytvořený alias:

use Nette\Utils\FileSystem;

Manipulace

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

Zkopíruje soubor nebo celý adresář. Ve výchozím nastavení přepisuje existující soubory a adresáře. S parametrem $overwrite nastaveným na hodnotou false vyvolá výjimku Nette\InvalidStateException, pokud cílový soubor nebo adresář $target existuje. Při chybě vyvolá výjimku Nette\IOException.

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

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

Vytvoří adresář, pokud neexistuje, včetně nadřazených adresářů. Při chybě vyvolá výjimku Nette\IOException.

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

delete (string $path): void

Smaže soubor nebo celý adresář pokud existuje. Pokud adresář není prázdný, smaže nejprve jeho obsah. Při chybě vyvolá výjimku Nette\IOException.

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

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

Nastaví oprávnění souboru na $fileMode nebo adresáři na $dirMode. Rekurzivně projde a nastaví oprávnění i celému obsahu adresáře.

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

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

Otevře soubor a vrátí resource. Parametr $mode funguje stejně jako u nativní funkce fopen(). V případě chyby vyvolá výjimku Nette\IOException.

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

read (string $file): string

Vrátí obsah souboru $file. Při chybě vyvolá výjimku Nette\IOException.

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

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

Přečte obsah souboru řádek po řádku. Na rozdíl od nativní funkce file() nenačítá celý soubor do paměti, ale čte jej průběžně, takže je možné číst i soubory větší než dostupná paměť. $stripNewLines říká, zda se mají odstranit znaky konce řádku \r a \n. V případě chyby vyvolá výjimku 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

Přejmenuje nebo přesune soubor či adresář $origin. Ve výchozím nastavení přepisuje existující soubory a adresáře. S parametrem $overwrite nastaveným na hodnotou false vyvolá výjimku Nette\InvalidStateException, pokud cílový soubor nebo adresář $target existuje. Při chybě vyvolá výjimku Nette\IOException.

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

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

Zapíše řetězec $content do souboru $file. Pokud nadřazený adresář neexistuje, automaticky se vytvoří. Ve výchozím nastavení také nastaví oprávnění souboru; předáním null do $mode přeskočíte volání chmod. Při chybě vyvolá výjimku Nette\IOException.

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

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

Zapíše řetězec $content do souboru $file atomicky: obsah se nejprve zapíše do dočasného souboru, který pak v jediném kroku nahradí cílový. Kdo soubor ve stejném okamžiku čte, nemůže ho proto nikdy vidět rozepsaný nebo zkrácený. Jinak se chová úplně stejně jako write(). Při chybě vyvolá výjimku Nette\IOException.

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

Cesty

isAbsolute (string $path): bool

Zjišťuje, zda je cesta $path absolutní.

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

isValidFilename (string $name): bool

Zjišťuje, zda je $name platný název souboru bez cesty, který funguje na všech platformách. Odmítne prázdný řetězec, . a .., řídicí znaky, znaky <>:"|?*\/, názvy končící tečkou nebo mezerou a vyhrazené názvy zařízení Windows (CON, NUL, COM1, …).

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

joinPaths (string …$segments): string

Spojí všechny segmenty cesty a výsledek normalizuje.

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

Normalizuje .. a . a oddělovače adresářů v cestě na systémové.

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

unixSlashes (string $path): string

Převede lomítka na / používané v unixových systémech.

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

platformSlashes (string $path): string

Převede lomítka na znaky specifické pro aktuální platformu, tj. \ ve Windows a / jinde.

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

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

Odvozuje finální cestu z cesty $path vzhledem k základnímu adresáři $basePath. Absolutní cesty (/foo, C:/foo) ponechá beze změny (pouze normalizuje lomítka), relativní cesty připojí k základní cestě.

// Na Windows by lomítka ve výstupu byla opačná (\)
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'

Statický vs nestatický přístup

Abyste kupříkladu pro účely testování mohli třídu snadno nahradit jinou (mockem), používejte ji nestaticky:

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

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

	// ...
}