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(/* ... */);
}
...
}