Функции файловой системы

Nette\Utils\FileSystem – класс с полезными функциями для работы с файловой системой. Одно из преимуществ перед нативными функциями PHP в том, что при ошибках они выбрасывают исключения.

Если вам нужно искать файлы на диске, используйте Finder.

Установка:

composer require nette/utils

В следующих примерах предполагается, что определён такой псевдоним класса:

use Nette\Utils\FileSystem;

Операции

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

Копирует файл или целый каталог. По умолчанию перезаписывает существующие файлы и каталоги. Если $overwrite установлен в false и целевой файл или каталог $target уже существует, выбрасывает Nette\InvalidStateException. При ошибке выбрасывает Nette\IOException.

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

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

Создаёт каталог, если его нет, включая родительские каталоги. При ошибке выбрасывает Nette\IOException.

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

delete (string $path): void

Удаляет файл или целый каталог, если он существует. Если каталог не пуст, сначала удаляет его содержимое. При ошибке выбрасывает Nette\IOException.

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

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

Устанавливает права файла в $fileMode или права каталога в $dirMode. Рекурсивно обходит и устанавливает права и для всего содержимого каталога.

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

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

Открывает файл и возвращает дескриптор ресурса. Параметр $mode работает так же, как у нативной функции fopen(). При ошибке выбрасывает Nette\IOException.

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

read (string $file): string

Читает содержимое файла $file. При ошибке выбрасывает Nette\IOException.

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

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

Читает содержимое файла построчно. В отличие от нативной функции file(), не загружает весь файл в память, а читает его последовательно, благодаря чему вы можете читать файлы больше доступной памяти. $stripNewLines указывает, убирать ли символы перевода строки \r и \n. При ошибке выбрасывает 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

Переименовывает или перемещает файл либо каталог, заданный в $origin, в $target. По умолчанию перезаписывает существующие файлы и каталоги. Если $overwrite установлен в false и целевой файл или каталог $target уже существует, выбрасывает Nette\InvalidStateException. При ошибке выбрасывает Nette\IOException.

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

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

Записывает строку $content в файл $file. Если родительского каталога нет, он создаётся автоматически. По умолчанию также устанавливает права файла; передайте null в $mode, чтобы пропустить вызов chmod. При ошибке выбрасывает Nette\IOException.

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

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

Записывает строку $content в файл $file атомарно: содержимое сначала записывается во временный файл, который затем одним действием заменяет целевой. Поэтому читатель, обратившийся к файлу в тот же момент, никогда не увидит его записанным наполовину или обрезанным. В остальном ведёт себя точно как write(). При ошибке выбрасывает Nette\IOException.

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

Пути

isAbsolute (string $path): bool

Определяет, является ли путь $path абсолютным.

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

isValidFilename (string $name): bool

Проверяет, является ли $name корректным кросс-платформенным именем файла без сведений о пути. Отклоняет пустые строки, . и .., управляющие символы, символы <>:"|?*\/, имена, оканчивающиеся точкой или пробелом, и зарезервированные имена Windows (CON, NUL, COM1, …).

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

joinPaths (string …$segments): string

Соединяет все части пути и нормализует результат.

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

Нормализует в пути .., . и разделители каталогов к системному стандарту.

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

unixSlashes (string $path): string

Преобразует слеши в /, используемые в системах Unix.

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

platformSlashes (string $path): string

Преобразует слеши в символы, свойственные текущей платформе, то есть \ в Windows и / в остальных случаях.

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

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

Определяет итоговый путь из $path относительно базового каталога $basePath. Абсолютные пути (/foo, C:/foo) остаются без изменений (нормализуются только слеши), относительные пути присоединяются к базовому.

// В Windows слеши в выводе были бы обратными (\)
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'

Статический и нестатический подход

Чтобы в тестах можно было легко подменить класс другим (например, mock-объектом), используйте его нестатически:

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

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

	// ...
}