Das Erstellen und Entpacken von ZIP-Archiven ist eine häufige Anforderung in PHP-Projekten. Ob Backup-Systeme, Download-Bereiche oder Dateiimporte: Die eingebaute Klasse ZipArchive stellt alle nötigen Methoden bereit, um ZIP-Dateien programmatisch zu erzeugen, zu bearbeiten und zu entpacken. Sie ist Teil der ZIP-Extension und bietet eine objektorientierte Schnittstelle, die sich intuitiv einsetzen lässt. In diesem Tutorial werden alle wichtigen Methoden Schritt für Schritt erklärt, von der Erstellung eines Archivs über das Hinzufügen und Entpacken von Dateien bis hin zur Fehlerbehandlung und einem vollständigen Praxisbeispiel.
Vor dem ersten Codebeispiel steht die Frage, ob die benötigte ZIP-Extension in der eigenen PHP-Installation verfügbar ist.
Voraussetzungen: Die ZIP-Extension
Bevor ZipArchive genutzt werden kann, muss die ZIP-Extension in PHP aktiviert sein. In den meisten PHP-Installationen ist sie bereits standardmäßig verfügbar.
Ob die Extension geladen ist, lässt sich mit der Funktion extension_loaded() prüfen. Alternativ zeigt ein Aufruf von phpinfo() alle aktiven Extensions an.
<?php
/* Prüfen, ob die ZIP-Extension geladen ist */
if (extension_loaded('zip')) {
echo 'ZIP-Extension ist verfügbar.';
} else {
echo 'ZIP-Extension ist nicht installiert.';
}
Falls die Extension fehlt, kann sie unter Linux mit dem Paketmanager nachinstalliert werden. Unter Debian und Ubuntu lautet der Befehl sudo apt install php-zip, gefolgt von einem Neustart des Webservers. Bei Windows-Installationen genügt es, die Zeile extension=zip in der php.ini zu aktivieren.
Ein ZIP-Archiv erstellen
Das Erstellen eines neuen ZIP-Archivs beginnt mit der Instanziierung der Klasse ZipArchive und dem Aufruf der Methode open(). Diese Methode akzeptiert den Dateipfad des Archivs sowie ein Flag, das das Verhalten steuert.
<?php
$zip = new ZipArchive();
/* Neues Archiv erstellen (OVERWRITE überschreibt vorhandene Dateien) */
$ergebnis = $zip->open('archiv.zip', ZipArchive::CREATE | ZipArchive::OVERWRITE);
if ($ergebnis === true) {
echo 'Archiv erfolgreich geöffnet.';
} else {
echo 'Fehler beim Öffnen: Code ' . $ergebnis;
}
Die wichtigsten Flags für open() sind ZipArchive::CREATE, das ein neues Archiv anlegt, falls es noch nicht existiert, ZipArchive::OVERWRITE, das ein bestehendes Archiv überschreibt, und ZipArchive::EXCL, das einen Fehler auslöst, wenn die Datei bereits vorhanden ist. Die Flags lassen sich mit dem Pipe-Operator kombinieren, um das gewünschte Verhalten zu erzielen.
Das folgende Diagramm veranschaulicht den typischen Ablauf beim Arbeiten mit ZipArchive.
flowchart TD
A["ZipArchive instanziieren"] --> B["open() mit Flags aufrufen"]
B --> C{"Erfolgreich geöffnet?"}
C -- "Ja" --> D["Dateien hinzufügen / entpacken / lesen"]
D --> E["close() aufrufen"]
E --> F["Archiv wird auf die Festplatte geschrieben"]
C -- "Nein" --> G["Fehlercode auswerten"]
G --> H["Fehlerbehandlung durchführen"]
Dateien zum Archiv hinzufügen
Nachdem das Archiv geöffnet wurde, können Dateien auf verschiedene Arten hinzugefügt werden. Die Klasse ZipArchive bietet dafür mehrere Methoden, die sich je nach Anwendungsfall eignen.
Einzelne Dateien mit addFile()
Die Methode addFile() fügt eine existierende Datei aus dem Dateisystem zum Archiv hinzu. Der erste Parameter ist der Pfad zur Datei, der zweite Parameter bestimmt den Namen und Pfad innerhalb des Archivs.
<?php
$zip = new ZipArchive();
$zip->open('projekt.zip', ZipArchive::CREATE | ZipArchive::OVERWRITE);
/* Datei mit gleichem Namen hinzufügen */
$zip->addFile('dokument.pdf');
/* Datei mit anderem Namen im Archiv ablegen */
$zip->addFile('bilder/foto.jpg', 'medien/foto.jpg');
/* Datei in einem Unterverzeichnis im Archiv platzieren */
$zip->addFile('config.ini', 'einstellungen/config.ini');
$zip->close();
Der zweite Parameter von addFile() ist besonders nützlich, um die Ordnerstruktur innerhalb des Archivs frei zu gestalten. Wird er weggelassen, verwendet ZipArchive den vollständigen Pfad der Quelldatei als Namen im Archiv.
Inhalte direkt mit addFromString()
Nicht immer liegen die Inhalte als Datei auf der Festplatte vor. Mit addFromString() lassen sich Strings direkt als Datei in das Archiv schreiben. Das ist ideal für dynamisch generierte Inhalte wie Berichte, Log-Dateien oder Konfigurationen.
<?php
$zip = new ZipArchive();
$zip->open('export.zip', ZipArchive::CREATE | ZipArchive::OVERWRITE);
/* CSV-Inhalt direkt erzeugen und hinzufügen */
$csvDaten = "Name;Alter;Stadt\n";
$csvDaten .= "Max;28;Berlin\n";
$csvDaten .= "Anna;34;Hamburg\n";
$zip->addFromString('export.csv', $csvDaten);
/* JSON-Daten hinzufügen */
$meta = json_encode([
'erstellt' => date('Y-m-d H:i:s'),
'version' => '1.0'
]);
$zip->addFromString('meta.json', $meta);
$zip->close();
Der Vorteil von addFromString() liegt darin, dass keine temporären Dateien auf der Festplatte angelegt werden müssen. Der Inhalt wird direkt aus dem Speicher in das Archiv geschrieben.
Ganze Verzeichnisse hinzufügen
Die Klasse ZipArchive bietet keine eigene Methode, um ein komplettes Verzeichnis rekursiv hinzuzufügen. Diese Funktionalität lässt sich jedoch mit einem RecursiveDirectoryIterator umsetzen.
<?php
$zip = new ZipArchive();
$zip->open('backup.zip', ZipArchive::CREATE | ZipArchive::OVERWRITE);
$verzeichnis = 'uploads';
/* Rekursiv alle Dateien im Verzeichnis durchlaufen */
$iterator = new RecursiveIteratorIterator(
new RecursiveDirectoryIterator($verzeichnis, RecursiveDirectoryIterator::SKIP_DOTS)
);
foreach ($iterator as $datei) {
if ($datei->isFile()) {
$pfad = $datei->getRealPath();
$relativerPfad = substr($pfad, strlen(realpath($verzeichnis)) + 1);
$zip->addFile($pfad, $verzeichnis . '/' . $relativerPfad);
}
}
$zip->close();
echo 'Backup erstellt.';
Der RecursiveDirectoryIterator durchläuft alle Unterverzeichnisse und liefert jede einzelne Datei. Mit SKIP_DOTS werden die Einträge . und .. ignoriert. Der relative Pfad wird berechnet, damit die Ordnerstruktur im Archiv erhalten bleibt.
Ein ZIP-Archiv entpacken
Das Entpacken eines ZIP-Archivs erfolgt über die Methode extractTo(). Sie akzeptiert als ersten Parameter das Zielverzeichnis. Optional kann ein zweiter Parameter angegeben werden, um nur bestimmte Dateien zu extrahieren.
<?php
$zip = new ZipArchive();
if ($zip->open('archiv.zip') === true) {
/* Alle Dateien entpacken */
$zip->extractTo('zielverzeichnis');
$zip->close();
echo 'Archiv entpackt.';
} else {
echo 'Archiv konnte nicht geöffnet werden.';
}
Um nur bestimmte Dateien zu entpacken, wird ein Array mit den gewünschten Dateinamen als zweiter Parameter übergeben. Die Namen müssen exakt mit den im Archiv gespeicherten Pfaden übereinstimmen.
<?php
$zip = new ZipArchive();
if ($zip->open('archiv.zip') === true) {
/* Nur bestimmte Dateien entpacken */
$zip->extractTo('zielverzeichnis', ['dokument.pdf', 'medien/foto.jpg']);
$zip->close();
}
Das Zielverzeichnis wird von extractTo() automatisch angelegt, sofern es noch nicht existiert. Es empfiehlt sich, den Pfad vorab zu validieren, um sicherzustellen, dass keine Dateien außerhalb des gewünschten Verzeichnisses landen.
Den Inhalt eines ZIP-Archivs lesen
Bevor ein Archiv entpackt wird, kann es sinnvoll sein, zunächst den Inhalt zu inspizieren. Die Eigenschaft numFiles gibt die Anzahl der enthaltenen Einträge zurück, und die Methode statIndex() liefert Details zu einer bestimmten Datei.
<?php
$zip = new ZipArchive();
if ($zip->open('archiv.zip') === true) {
echo 'Anzahl Dateien: ' . $zip->numFiles . "\n";
/* Alle Einträge auflisten */
for ($i = 0; $i < $zip->numFiles; $i++) {
$info = $zip->statIndex($i);
echo $info['name'] . ' (' . $info['size'] . ' Bytes)' . "\n";
}
$zip->close();
}
Die Methode statIndex() gibt ein assoziatives Array zurück, das unter anderem den Dateinamen, die unkomprimierte Größe, die komprimierte Größe und den Zeitstempel der letzten Änderung enthält. So lässt sich der Inhalt eines Archivs vollständig analysieren, ohne eine einzige Datei extrahieren zu müssen.
Dateien aus einem Archiv löschen
Einzelne Dateien lassen sich mit der Methode deleteName() aus einem bestehenden Archiv entfernen. Das Archiv muss dafür mit open() ohne das Flag OVERWRITE geöffnet werden, da dieses den gesamten Inhalt ersetzen würde.
<?php
$zip = new ZipArchive();
if ($zip->open('archiv.zip') === true) {
/* Eine bestimmte Datei entfernen */
$zip->deleteName('veraltete-datei.txt');
/* Eine Datei in einem Unterverzeichnis entfernen */
$zip->deleteName('logs/debug.log');
$zip->close();
echo 'Dateien entfernt.';
}
Nach dem Aufruf von deleteName() muss close() aufgerufen werden, damit die Änderungen tatsächlich in die ZIP-Datei geschrieben werden. Ohne close() gehen alle Änderungen verloren.
Fehlerbehandlung und Best Practices
Eine zuverlässige Fehlerbehandlung ist beim Arbeiten mit ZIP-Archiven besonders wichtig, da Dateioperationen aus vielen Gründen fehlschlagen können.
Rückgabewerte von open() prüfen
Die Methode open() gibt bei Erfolg true zurück, bei einem Fehler hingegen einen ganzzahligen Fehlercode. Dieser Code kann mit den Klassenkonstanten von ZipArchive verglichen werden, um die genaue Fehlerursache zu ermitteln.
<?php
$zip = new ZipArchive();
$ergebnis = $zip->open('archiv.zip', ZipArchive::CREATE);
if ($ergebnis !== true) {
switch ($ergebnis) {
case ZipArchive::ER_EXISTS:
echo 'Archiv existiert bereits.';
break;
case ZipArchive::ER_NOENT:
echo 'Datei nicht gefunden.';
break;
case ZipArchive::ER_OPEN:
echo 'Datei konnte nicht geöffnet werden.';
break;
case ZipArchive::ER_READ:
echo 'Lesefehler.';
break;
default:
echo 'Unbekannter Fehler: ' . $ergebnis;
}
}
Durch die Auswertung der Fehlercodes lässt sich gezielt auf unterschiedliche Problemsituationen reagieren. Das ist besonders bei serverseitigen Anwendungen wichtig, in denen Berechtigungsprobleme oder fehlende Verzeichnisse auftreten können.
Das Archiv korrekt schließen
Der Aufruf von close() ist nicht nur guter Stil, sondern zwingend erforderlich. Erst beim Schließen wird das Archiv tatsächlich auf die Festplatte geschrieben. Wird close() vergessen, gehen alle hinzugefügten Dateien und Änderungen verloren.
Ein typisches Muster ist daher, alle Operationen innerhalb eines if-Blocks auszuführen und close() am Ende dieses Blocks aufzurufen. So ist sichergestellt, dass das Archiv nur geschlossen wird, wenn es zuvor erfolgreich geöffnet wurde. Zusätzlich sollte geprüft werden, ob close() selbst erfolgreich war, da auch dieser Aufruf false zurückgeben kann, etwa wenn nicht genügend Speicherplatz vorhanden ist.
Praxisbeispiel: Download-Archiv erstellen
Das folgende Beispiel zeigt ein vollständiges Skript, das mehrere Dateien zu einem ZIP-Archiv zusammenfasst und dieses als Download an den Browser sendet. Dieses Muster findet sich häufig in Content-Management-Systemen oder Dateimanagern.
<?php
$dateien = [
'uploads/bericht-2025.pdf',
'uploads/tabelle.xlsx',
'uploads/praesentation.pptx'
];
$archivName = 'download_' . date('Y-m-d_His') . '.zip';
$archivPfad = sys_get_temp_dir() . '/' . $archivName;
$zip = new ZipArchive();
$ergebnis = $zip->open($archivPfad, ZipArchive::CREATE | ZipArchive::OVERWRITE);
if ($ergebnis !== true) {
http_response_code(500);
echo 'Archiv konnte nicht erstellt werden.';
exit;
}
foreach ($dateien as $datei) {
if (file_exists($datei)) {
/* Nur den Dateinamen ohne Pfad im Archiv verwenden */
$zip->addFile($datei, basename($datei));
}
}
/* Archiv muss vor dem Senden geschlossen werden */
$zip->close();
/* HTTP-Header für den Download setzen */
header('Content-Type: application/zip');
header('Content-Disposition: attachment; filename="' . $archivName . '"');
header('Content-Length: ' . filesize($archivPfad));
/* Datei an den Browser senden */
readfile($archivPfad);
/* Temporäre Datei aufräumen */
unlink($archivPfad);
exit;
Das Skript erzeugt das Archiv im temporären Verzeichnis des Systems, sendet es als Download an den Browser und löscht die temporäre Datei anschließend mit unlink(). Durch die Verwendung von basename() wird sichergestellt, dass im Archiv nur die Dateinamen ohne Verzeichnisstruktur gespeichert werden. Die Funktion sys_get_temp_dir() liefert einen plattformunabhängigen Pfad zum temporären Verzeichnis, sodass das Skript auf verschiedenen Betriebssystemen funktioniert.
Fazit
Die Klasse ZipArchive bietet eine leistungsfähige und gut strukturierte Schnittstelle für alle Operationen rund um ZIP-Dateien in PHP. Mit open() und den Flags CREATE, OVERWRITE und EXCL lässt sich das Verhalten beim Erstellen und Öffnen präzise steuern. Die Methoden addFile() und addFromString() decken sowohl das Hinzufügen vorhandener Dateien als auch dynamisch erzeugter Inhalte ab. Zum Entpacken steht extractTo() bereit, das wahlweise alle oder nur ausgewählte Dateien extrahiert. Mit numFiles, statIndex() und deleteName() lassen sich Archivinhalte lesen und gezielt bearbeiten. Entscheidend ist dabei, close() stets aufzurufen, da erst dieser Schritt die Änderungen auf die Festplatte schreibt. Die Kombination aus objektorientierter API und umfassender Fehlerbehandlung macht ZipArchive zur ersten Wahl für die Arbeit mit ZIP-Dateien in PHP-Projekten.
