FileSystem

1. Einleitung

Die Filesystem-Komponente bietet Funktionalität, um auf das Dateisystem zuzugreifen und es zu modifizieren. Dateien und Verzeichnisse werden dabei durch die Klassen File und Folder repräsentiert, welche - gemäß des Domain-Object-Patterns - nicht nur Daten, sondern auch Verarbeitungslogik beinhalten.

2. API für Dateien

2.1. Dateien erstellen

Um eine neue Datei zu erstellen, muss die Klasse File erst in das aktuelle Script importiert werden. Dies kann entweder über die import()-Funktion oder über den (DI)ServiceManager geschehen.

PHP-Code
import('tools::filesystem', 'File'); $file = new File(); $file->create('path/to/my/new/file/filename.txt');

2.2. Dateien öffnen

Möchten Sie das File-Domänen-Objekt mit den Daten einer bereits existierenden Datei füllen, genügt ein Aufruf der Methode open().

PHP-Code
import('tools::filesystem', 'File'); $file = new File(); $file->open('path/to/an/existing/file/filename.php');

2.3. Dateien löschen

Vor dem Löschen einer Datei, muss diese erst mit create() erstellt oder mit open() geöffnet werden. Anschliessend kann die Datei mit delete() entfernt werden.

PHP-Code
import('tools::filesystem', 'File'); $file = new File(); $file->create('path/to/my/new/file/filename.html'); $file->delete(); // oder $file = new File(); $file->open('path/to/my/existing/file/filename.txt'); $file->delete();

2.4. Dateien kopieren

Über die Methode createCopy() können Sie von der aktuell geöffneten Datei eine Kopie erstellen.
Die Funktion erwartet als ersten Parameter eine Instanz der Klasse Folder, welche als Zielverzeichnis der Kopie dient.

PHP-Code
import('tools::filesystem', 'Folder'); import('tools::filesystem', 'File'); // Erstellen des Zielverzeichnisses $targetFolder = new Folder(); $targetFolder->create('target/folder/of/my/copy'); // oder alternativ ein bereits existierendes Verzeichnis öffnen $targetFolder = new Folder(); $targetFolder->open('target/folder/of/my/copy'); // Datei öffnen und Kopie erstellen $file = new File(); $file->open('path/to/an/existing/file/filename.php'); $file->createCopy($targetFolder);

Standardmäßig wird die Dateikopie wie die originale Datei benannt. Durch die Übergabe des 2. optionalen Parameters kann der Name aber beeinflusst werden:

PHP-Code
// ... $file->createCopy($targetFolder, 'NewNameOfTheCopy.php');

Der Rückgabewert der createCopy()-Methode ist ein File-Objekt, welches sich auf die Dateikopie referenziert.
In dem folgenden Beispiel wird zuerst eine neue Datei erstellt, anschließend wird diese kopiert und am Ende wird der Inhalt der Kopie mit der writeContent()-Methode geändert.

PHP-Code
$file = new File(); $file->create('folder/another/myFile.php'); ->createCopy($targetFolder) ->writeContent('Ich bin eine Kopie.');

Wird der 3. und letzte Parameter der createCopy()-Methode auf false gesetzt, wird anstatt des File-Objektes ein Boolean zurückgegeben.

2.5. Dateien verschieben

Die moveTo()-Methode ermöglicht das Verschieben einer Datei in ein anderes Verzeichnis. Sie verfügt lediglich über einen Parameter, welcher, wie bei der createCopy()-Methode das Zielverzeichnis definiert.

PHP-Code
$targetFolder = new Folder(); $targetFolder->open('my/target/folder'); $file = new File(); $file->open('path/to/my/file.php')->moveTo($targetFolder);

2.6. Dateien umbenennen

Über die Funktion renameTo() lassen sich Dateien umbenennen – zurückgegeben wird ein boolescher Wert.

PHP-Code
$file = new File(); $file->create('path/to/my/file.txt')->renameTo('myNewName.txt');

2.7. Den Inhalt einer Datei modifizieren

Zur Bearbeitung des Inhaltes einer Datei stehen drei Methoden zur Verfügung:

  • writeContent($content) – überschreibt den kompletten Inhalt
  • appendContent($content) – hängt Inhalt an den Aktuellen an
  • prependContent($content) – stellt Inhalt dem Aktuellen voran
PHP-Code
$file = new File(); $file->open('path/to/my/file.txt') ->writeContent('PHP'); ->prependContent('Adventure ') ->appendContent(' Framework!'); echo $file->getContent(); // Resultat: Adventure PHP Framework!

2.8. Dateidownload erzeugen

Mit der Methode makeDownload() kann von der aktuell geöffneten Datei ein Download erstellt werden:

PHP-Code
$file = new File(); $file->create('path/to/my/downloadable/file.pdf')->makeDownload();

Übergibt man den optionalen Parameter $filename, kann der Name der Datei geändert werden. In dem folgenden Beispiel wird ein Download der Datei filesystem.pdf mit dem Inhalt der Datei file.pdf erzeugt.

PHP-Code
$file = new File(); $file->open('path/to/my/downloadable/file.pdf')->makeDownload('filesystem.pdf');

2.9. Weitere Methoden

  • changeOwnerTo($owner)
  • Erwartet als Parameter den Namen des neuen Eigentümers der Datei.
  • changeModeTo($mode)
  • Ändert die Zugriffsrechte zu den in $mode (bspw. 0755) definierten.
  • isWritable()
  • Gibt true zurück, sofern die Datei beschreibbar ist – andernfalls false.
  • isReadable()
  • Gibt true zurück, sofern die Datei lesbar ist – andernfalls false.
  • getParentFolder()
  • Gibt das Elternverzeichnis in Form eines Folder-Objektes zurück.
  • getOwner()
  • Gibt den Eigentümer der Datei zurück.
  • getPermissions()
  • Gibt die Zugriffsrechte der Datei zurück.
  • getName()
  • Gibt den Namen der Datei zurück (Bsp: filename.txt).
  • getBasePath()
  • Gibt den Pfad zur Datei zurück. Bei der Datei my/folder/file.txt würde diese Funktion my/folder zurückgeben.
  • getPath()
  • Gibt den kompletten Pfad der Datei zurück (Bsp: my/folder/file.txt).
  • getSize()
  • Gibt die Größe der Datei (in Bytes) zurück.
  • getContent()
  • Liefert den Inhalt der Datei.
  • getMimeType()
  • Gibt den Mime-Type der Datei zurück. Ist die PHP-Erweiterung fileinfo nicht installiert, liefert diese Methode stets null.
  • getExtension()
  • Liefert die Dateiendung der aktuellen Datei – bei filename.txt wäre das txt.

3. API für Verzeichnisse

3.1. Verzeichnisse erstellen

Um ein neues Verzeichnis zu erstellen, muss die Klasse Folder erst in das aktuelle Script importiert werden. Dies kann entweder über die import()-Funktion oder über den (DI)ServiceManager geschehen.

PHP-Code
import('tools::filesystem', 'Folder'); $folder = new Folder(); $folder->create('path/to/my/new/folder');

3.2. Verzeichnisse öffnen

Möchten Sie das Folder-Domänen-Objekt mit den Daten eines bereits existierenden Verzeichnisses füllen, genügt ein Aufruf der Methode open().

PHP-Code
import('tools::filesystem', 'Folder'); $folder = new Folder(); $folder->open('path/to/an/existing/folder');

Beim Versuch ein nicht existentes Verzeichnis zu öffnen, wird eine Exception vom Typ FilesystemException geworfen.

3.3. Verzeichnisse löschen

Vor dem Löschen eines Verzeichnisses muss eines erst mit create() erstellt oder ein bereits existierendes mit open() geöffnet werden.

PHP-Code
import('tools::filesystem', 'Folder'); $folder = new Folder(); $folder->create('path/to/my/new/folder'); $folder->delete(); // oder $folder = new Folder(); $folder->open('path/to/my/existing/folder'); $folder->delete();

Die Methoden create() und open() implementieren das Fluent-Interface - es kann somit alternativ zur gerade gezeigten Schreibweise direkt die delete()-Methode auf dem Rückgabewert aufgerufen werden:

PHP-Code
import('tools::filesystem', 'Folder'); $folder = new Folder(); $folder->create('path/to/my/new/folder')->delete(); // oder $folder = new Folder(); $folder->open('path/to/my/existing/folder')->delete();

3.4. Verzeichnisse kopieren

Über die Methode createCopy() können Sie von dem aktuellen Verzeichnis eine Kopie erstellen.
Die Funktion erwartet als ersten Parameter eine Instanz der Klasse Folder, welche als Zielverzeichnis der Kopie dient.

PHP-Code
import('tools::filesystem', 'Folder'); // Erstellen des Zielverzeichnisses $targetFolder = new Folder(); $targetFolder->create('target/folder/of/my/copy'); // ...oder alternativ ein bereits existierendes Verzeichnis öffnen $targetFolder = new Folder(); $targetFolder->open('target/folder/of/my/copy'); $folder->createCopy($targetFolder);

Standardmäßig wird die Kopie wie das originale Verzeichnis benannt. Durch die Übergabe des 2. optionalen Parameters kann der Name aber beeinflusst werden:

PHP-Code
$folder->open('path/to/my/folder') ->createCopy($targetFolder, 'NewNameForTheCopy');

Der Rückgabewert der createCopy()-Methode ist ein Folder-Objekt, welches auf die Verzeichnis-Kopie referenziert.
In dem folgenden Beispiel wird zuerst ein neues Verzeichnis erstellt, anschließend wird dieses kopiert und am Ende wird die Kopie wieder gelöscht.

PHP-Code
$targetFolder = new Folder(); $targetFolder->open('target/folder/of/my/copy'); $folder = new Folder(); $folder->create('path/to/my/folder'); ->createCopy($targetFolder) ->delete();

Wird der 3. und letzte Parameter der createCopy()-Methode auf false gesetzt, wird anstelle des Folder-Objektes ein Boolean zurückgegeben.

3.5. Verzeichnisse verschieben

Die moveTo()-Methode ermöglicht das Verschieben eines Verzeichnisses in ein anderes Verzeichnis. Sie verfügt lediglich über einen Parameter, welcher, wie bei der createCopy()-Methode das Zielverzeichnis definiert.

PHP-Code
$targetFolder = new Folder(); $targetFolder->open('my/target/folder'); $folder = new Folder(); $folder->open('path/to/my/folder')->moveTo($targetFolder);

3.6. Verzeichnisse umbenennen

Über die Funktion renameTo() lassen sich Verzeichnisse umbenennen – zurückgegeben wird ein boolescher Wert.

PHP-Code
$folder = new Folder(); $folder->create('path/to/my/folder')->renameTo('myNewFolderName');

3.7. Inhalte eines Verzeichnisses auslesen

Mittels getContent() lassen sich alle Verzeichnisse und Dateien, die sich im aktuellen Verzeichnis befinden, auslesen. Rückgabewert dieser Funktion ist ein Array, gefüllt mit File- und Folder-Objekten, die den Inhalt des Verzeichnisses repräsentieren.

PHP-Code
$folder = new Folder(); $children = $folder->open('path/to/my/folder')->getContent();

3.8. Weitere Methoden

  • changeOwnerTo($owner)
  • Erwartet als Parameter den Namen des neuen Eigentümers des Verzeichnisses.
  • changeModeTo($mode)
  • Ändert die Zugriffsrechte zu den in $mode (bspw. 0755) definierten.
  • isWritable()
  • Gibt true zurück, sofern das Verzeichnis beschreibbar ist – andernfalls false.
  • isReadable()
  • Gibt true zurück, sofern das Verzeichnis lesbar ist – andernfalls false.
  • getParentFolder()
  • Gibt das Elternverzeichnis in Form eines Folder-Objektes zurück.
  • getOwner()
  • Gibt den Eigentümer des Verzeichnisses zurück.
  • getPermissions()
  • Gibt die Zugriffsrechte des Verzeichnisses zurück.
  • getName()
  • Gibt den Namen des Verzeichnisses zurück.
  • getBasePath()
  • Gibt den Pfad zum Verzeichnis zurück. Bei dem Verzeichnis path/to/my/folder würde diese Funktion path/to/my zurückgeben.
  • getPath()
  • Gibt den kompletten Pfad des Verzeichnisses zurück.
  • getSize()
  • Gibt die Größe des Verzeichnisses (in Bytes) zurück.