Funktionen für das Dateisystem

Nette\Utils\FileSystem ist eine Klasse mit nützlichen Funktionen für die Arbeit mit dem Dateisystem. Ein Vorteil gegenüber den nativen PHP-Funktionen ist, dass sie im Fehlerfall Exceptions werfen.

Wenn Sie Dateien auf der Festplatte suchen müssen, verwenden Sie den Finder.

Installation:

composer require nette/utils

Die folgenden Beispiele setzen voraus, dass dieser Klassen-Alias definiert ist:

use Nette\Utils\FileSystem;

Manipulation

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

Kopiert eine Datei oder ein ganzes Verzeichnis. Bestehende Dateien und Verzeichnisse werden standardmäßig überschrieben. Ist $overwrite auf false gesetzt und die Zieldatei bzw. das Zielverzeichnis $target existiert bereits, wirft die Methode eine Nette\InvalidStateException. Im Fehlerfall wirft sie eine Nette\IOException.

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

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

Erzeugt ein Verzeichnis, wenn es nicht existiert, samt der übergeordneten Verzeichnisse. Im Fehlerfall wirft die Methode eine Nette\IOException.

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

delete (string $path): void

Löscht eine Datei oder ein ganzes Verzeichnis, sofern es existiert. Ist das Verzeichnis nicht leer, löscht die Methode zuerst seinen Inhalt. Im Fehlerfall wirft sie eine Nette\IOException.

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

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

Setzt die Rechte einer Datei auf $fileMode bzw. die eines Verzeichnisses auf $dirMode. Sie durchläuft rekursiv den gesamten Inhalt eines Verzeichnisses und setzt auch dort die Rechte.

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

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

Öffnet eine Datei und gibt ein Resource-Handle zurück. Der Parameter $mode funktioniert genauso wie bei der nativen Funktion fopen(). Im Fehlerfall wirft die Methode eine Nette\IOException.

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

read (string $file): string

Liest den Inhalt der Datei $file. Im Fehlerfall wirft die Methode eine Nette\IOException.

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

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

Liest den Inhalt der Datei Zeile für Zeile. Anders als die native Funktion file() lädt sie nicht die gesamte Datei in den Speicher, sondern liest sie fortlaufend, sodass sich auch Dateien lesen lassen, die größer als der verfügbare Speicher sind. $stripNewLines bestimmt, ob die Zeilenumbruchzeichen \r und \n entfernt werden. Im Fehlerfall wirft die Methode eine Nette\IOException.

$lines = FileSystem::readLines('/path/to/file');

foreach ($lines as $lineNum => $line) {
	echo "Zeile $lineNum: $line\n";
}

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

Benennt die durch $origin angegebene Datei oder das Verzeichnis in $target um oder verschiebt sie dorthin. Bestehende Dateien und Verzeichnisse werden standardmäßig überschrieben. Ist $overwrite auf false gesetzt und die Zieldatei bzw. das Zielverzeichnis $target existiert bereits, wirft die Methode eine Nette\InvalidStateException. Im Fehlerfall wirft sie eine Nette\IOException.

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

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

Schreibt den String $content in die Datei $file. Existiert das übergeordnete Verzeichnis nicht, wird es automatisch angelegt. Standardmäßig setzt die Methode auch die Rechte der Datei; übergeben Sie null als $mode, um den Aufruf von chmod zu überspringen. Im Fehlerfall wirft sie eine Nette\IOException.

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

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

Schreibt den String $content atomar in die Datei $file: Der Inhalt wird zuerst in eine temporäre Datei geschrieben, die das Ziel dann in einem einzigen Schritt ersetzt. Ein Leser, der im selben Moment auf die Datei zugreift, kann sie deshalb nie halb geschrieben oder abgeschnitten sehen. Ansonsten verhält sie sich genau wie write(). Im Fehlerfall wirft sie eine Nette\IOException.

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

Pfade

isAbsolute (string $path): bool

Ermittelt, ob der Pfad $path absolut ist.

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

isValidFilename (string $name): bool

Prüft, ob $name ein plattformübergreifend gültiger Dateiname ohne Pfadangabe ist. Abgelehnt werden leere Strings, . und .., Steuerzeichen, die Zeichen <>:"|?*\/, Namen, die auf einen Punkt oder ein Leerzeichen enden, sowie unter Windows reservierte Namen (CON, NUL, COM1, …).

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

joinPaths (string …$segments): string

Fügt alle Pfadsegmente zusammen und normalisiert das Ergebnis.

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

Normalisiert .., . und die Verzeichnistrenner im Pfad auf den Standard des Systems.

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

unixSlashes (string $path): string

Wandelt die Schrägstriche in das auf Unix-Systemen verwendete / um.

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

platformSlashes (string $path): string

Wandelt die Schrägstriche in die Zeichen um, die für die aktuelle Plattform typisch sind, also \ unter Windows und / anderswo.

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

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

Ermittelt den endgültigen Pfad aus $path relativ zum Basisverzeichnis $basePath. Absolute Pfade (/foo, C:/foo) bleiben unverändert (nur die Schrägstriche werden normalisiert), relative Pfade werden an den Basispfad angehängt.

// Unter Windows wären die Schrägstriche in der Ausgabe umgedreht (\)
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'

Statischer vs. nicht statischer Ansatz

Damit sich die Klasse für Tests leicht durch eine andere (etwa einen Mock) ersetzen lässt, verwenden Sie sie nicht statisch:

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

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

	// ...
}