Filesystem Functions

Nette\Utils\FileSystem is a class, which contains useful functions for working with a filesystem. One advantage over native PHP functions is that they throw exceptions in case of errors.

If you need to search for files on the disk, use the Finder.

Installation:

composer require nette/utils

Following examples assume the following class alias is defined:

use Nette\Utils\FileSystem;

Manipulation

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

Copies a file or an entire directory. Overwrites existing files and directories by default. If $overwrite is set to false and a $target already exists, throws an exception Nette\InvalidStateException. Throws an exception Nette\IOException on error occurred.

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

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

Creates a directory if it does not exist, including parent directories. Throws an exception Nette\IOException on error occurred.

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

delete (string $path): void

Deletes a file or an entire directory if exists. If the directory is not empty, it deletes its contents first. Throws an exception Nette\IOException on error occurred.

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

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

Sets file permissions to $fileMode or directory permissions to $dirMode. Recursively traverses and sets permissions on the entire contents of the directory as well.

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

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

Opens file and returns resource. The $mode parameter works the same as the native fopen() function. If an error occurs, it raises the Nette\IOException exception.

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

read (string $file): string

Reads the content of a $file. Throws an exception Nette\IOException on error occurred.

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

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

Reads the file content line by line. Unlike the native file() function, it does not read the entire file into memory, but reads it continuously, so that files larger than the available memory can be read. The $stripNewLines specifies whether to strip the \r and \n line break characters. In case of an error, it raises a Nette\IOException exception.

$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

Renames or moves a file or a directory specified by $origin to $target. Overwrites existing files and directories by default. If $overwrite is set to false and $target already exists, throws an exception Nette\InvalidStateException. Throws an exception Nette\IOException on error occurred.

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

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

Writes the $content to a $file. Throws an exception Nette\IOException on error occurred.

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

Paths

isAbsolute (string $path): bool

Determines if the $path is absolute.

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

joinPaths (string …$segments): string

Joins all segments of the path and normalizes the result.

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

Normalizes .. and . and directory separators in path.

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

unixSlashes (string $path): string

Converts slashes to / used on Unix systems.

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

platformSlashes (string $path): string

Converts slashes to characters specific to the current platform, i.e. \ on Windows and / elsewhere.

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

Static vs Non-static Approach

To easily replace the FileSystem class with another class for example for testing purposes, use it non-statically:

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

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

	...
}