Signatur
Beschreibung
gzwrite() schreibt den Inhalt von $data in den mit gzopen() geöffneten Datei-Stream $stream. Die Daten werden dabei transparent mit zlib komprimiert und in die Zieldatei geschrieben. Die Funktion arbeitet analog zu fwrite(), jedoch ausschließlich für gz-komprimierte Streams.
Mit dem optionalen Parameter $length kann die Anzahl der zu schreibenden Bytes begrenzt werden. Wird er weggelassen (oder als null übergeben), wird die gesamte Zeichenkette geschrieben. Diese Möglichkeit der Längenangabe ist nützlich, wenn nur ein bestimmter Teilbereich eines größeren Strings geschrieben werden soll.
Typische Einsatzgebiete sind das Erstellen von Backup-Dateien, das Exportieren großer Datensätze als komprimierte Textdateien (z. B. CSV oder Log-Dumps) sowie das Verarbeiten von Daten in Streaming-Szenarien, bei denen der gesamte Inhalt nicht auf einmal im Speicher gehalten werden soll.
Im Fehlerfall gibt die Funktion false zurück. Der Rückgabewert sollte daher stets auf false geprüft werden, da ein Rückgabewert von 0 bedeutet, dass kein Byte geschrieben wurde, aber kein Fehler aufgetreten ist.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $stream Pflicht | resource | Ein mit gzopen() geöffneter gz-Datei-Stream im Schreibmodus ('w') oder Anhängemodus ('a'). |
|
| $data Pflicht | string | Die zu schreibende Zeichenkette. Sie wird vor dem Speichern automatisch komprimiert. | |
| $length | ?int | null | Optionale maximale Anzahl von Bytes aus $data, die geschrieben werden sollen. Ist der Wert größer als die Länge von $data, wird nur strlen($data) geschrieben. Bei null wird die gesamte Zeichenkette geschrieben. |
Rückgabewert
int zurück. Im Fehlerfall wird false zurückgegeben.Beispiele
Einfaches Schreiben in eine gz-komprimierte Datei
<?php
$gz = gzopen('ausgabe.gz', 'w9'); // Komprimierungsstufe 9
if ($gz === false) {
die('Datei konnte nicht geöffnet werden.');
}
$text = "Zeile 1: Hallo Welt\nZeile 2: PHP gz-Komprimierung\n";
$geschrieben = gzwrite($gz, $text);
echo "Bytes geschrieben (unkomprimiert): " . $geschrieben . PHP_EOL;
gzclose($gz);Zeilenweises Schreiben einer CSV-Datei als gz-Archiv
<?php
$daten = [
['Name', 'Alter', 'Stadt'],
['Anna', 28, 'Berlin'],
['Bernd', 34, 'Hamburg'],
['Clara', 22, 'München'],
];
$gz = gzopen('export.csv.gz', 'w6');
if ($gz === false) {
die('Fehler beim Öffnen der Datei.');
}
foreach ($daten as $zeile) {
$csv = implode(';', $zeile) . "\n";
if (gzwrite($gz, $csv) === false) {
echo 'Schreibfehler aufgetreten!' . PHP_EOL;
break;
}
}
gzclose($gz);
echo 'CSV-Datei erfolgreich komprimiert gespeichert.';
Nur die ersten N Bytes schreiben
<?php
$gz = gzopen('teilausgabe.gz', 'w');
$text = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
// Nur die ersten 10 Zeichen schreiben
$bytes = gzwrite($gz, $text, 10);
echo "Geschrieben: " . $bytes . " Bytes" . PHP_EOL; // Schreibt 'ABCDEFGHIJ'
gzclose($gz);
// Wichtig · Fallstricke
Rückgabewert prüfen: Da gzwrite() im Fehlerfall false zurückgibt, sollte immer mit === false verglichen werden — ein einfaches if (!gzwrite(...)) würde auch bei 0 geschriebenen Bytes fälschlicherweise als Fehler interpretiert.
Komprimierungsstufe: Die Komprimierungsstufe wird bereits beim Öffnen der Datei mit gzopen() festgelegt (z. B. 'w9' für maximale Komprimierung). gzwrite() selbst kennt keine Stufe.
Binäre Daten: gzwrite() ist binärsicher und kann auch mit Binärdaten (z. B. serialisierte Objekte, Bilddaten) verwendet werden.
Speicherverbrauch: Bei sehr großen Datenmengen empfiehlt es sich, den Inhalt in Chunks zu schreiben, anstatt alles auf einmal im Speicher zu halten.