fputcsv()

Die Funktion fputcsv() formatiert eine einzelne Datenzeile — übergeben als PHP-array — in eine CSV-Zeile (kommagetrennte Werte) und schreibt sie in eine geöffnete Datei. Sie ist der Standardweg zum Exportieren tabellarischer Daten wie Berichte, Datenbankexporte oder Tabellenkalkulationen, die Benutzer in Excel, Google Sheets oder LibreOffice öffnen werden.

Diese Seite behandelt die Syntax und Parameter, die typische Schreibschleife, wie fputcsv() Sonderzeichen automatisch in Anführungszeichen setzt und maskiert, wie Trennzeichen und Begrenzungszeichen gesteuert werden, sowie die häufigsten Fallstricke (das abschließende Zeilenende, UTF-8 in Excel und den geänderten Standardwert des Parameters $escape).

Syntax

fputcsv(
    resource $stream,
    array $fields,
    string $separator = ",",
    string $enclosure = "\"",
    string $escape = "\\",
    string $eol = "\n"
): int|false

Rückgabewert: die Anzahl der geschriebenen Bytes oder false bei einem Fehler.

Der Parameter $eol ist ab PHP 8.1 verfügbar, und PHP 9.0 ändert den Standardwert von $escape von "\\" auf "". Wenn Sie heute eine stabile, portable Ausgabe wünschen, übergeben Sie escape: "" explizit.

So funktioniert fputcsv()

fputcsv() nimmt ein array und schreibt genau eine Zeile. Um eine Tabelle zu exportieren, rufen Sie die Funktion einmal pro Zeile innerhalb einer Schleife auf. Die Funktion übernimmt das Setzen von Anführungszeichen für Sie: Jedes Feld, das das Trennzeichen, das Begrenzungszeichen oder einen Zeilenumbruch enthält, wird automatisch in das Begrenzungszeichen eingeschlossen, und eingebettete Anführungszeichen werden verdoppelt.

Der grundlegende Ablauf ist:

1. Ein array (oder ein array von arrays) aufbauen, das die zu exportierenden Daten enthält.
2. Die Zieldatei zum Schreiben mit fopen() öffnen.
3. fputcsv() einmal pro Zeile aufrufen.
4. Die Datei mit fclose() schließen.

Grundlegendes Beispiel: Eine CSV-Datei schreiben

<?php

$data = [
    ['Name', 'Surname', 'Age', 'Gender'], // header row
    ['John', 'Doe', '30', 'Male'],
    ['Jane', 'Doe', '25', 'Female'],
    ['Bob', 'Smith', '40', 'Male'],
];

$file = fopen('people.csv', 'w');

foreach ($data as $row) {
    fputcsv($file, $row);
}

fclose($file);

// Show what was written:
echo file_get_contents('people.csv');

Ausgabe:

Name,Surname,Age,Gender
John,Doe,30,Male
Jane,Doe,25,Female
Bob,Smith,40,Male

Das erste array wird als Kopfzeile geschrieben, dann wird jedes nachfolgende array zu einer Datenzeile.

Automatisches Anführungszeichen-Setzen und Maskieren

Sie setzen Anführungszeichen nicht selbst — fputcsv() entscheidet, wann Anführungszeichen erforderlich sind. Ein Feld wird nur dann eingeschlossen, wenn es das Trennzeichen, einen Zeilenumbruch oder das Begrenzungszeichen enthält.

<?php

$file = fopen('php://output', 'w'); // write straight to the browser/CLI

fputcsv($file, ['Plain', 'Has, comma', 'Has "quotes"', "Two\nlines"]);

fclose($file);

Ausgabe:

Plain,"Has, comma","Has ""quotes""","Two
lines"

Beachten Sie, dass Plain unverändert bleibt, das Feld mit Komma in Anführungszeichen gesetzt wird, die eingebetteten doppelten Anführungszeichen verdoppelt werden (""), und der Wert mit einem Zeilenumbruch eingeschlossen wird, damit der Zeilenumbruch erhalten bleibt. Der Stream php://output ist praktisch zum Testen oder zum Streamen eines Downloads ohne temporäre Datei.

Benutzerdefiniertes Trennzeichen und Begrenzungszeichen

Um eine tabulator- oder semikolongetrennte Datei zu erzeugen, übergeben Sie das Argument $separator. Viele europäische Gebietsschemas öffnen semikolongetrennte Dateien sauberer in Excel.

<?php

$file = fopen('php://output', 'w');

// Semicolon delimiter
fputcsv($file, ['John', 'Doe', '30'], ';');

// Tab delimiter
fputcsv($file, ['Jane', 'Doe', '25'], "\t");

fclose($file);

Ausgabe:

John;Doe;30
Jane	Doe	25

Häufige Fallstricke

• Abschließendes Zeilenende. fputcsv() hängt immer ein Zeilenende an, sodass die Datei mit einer leeren Zeile endet. Wenn Sie sie später mit fgetcsv() lesen, ist das harmlos, kann aber bei byteexakten Vergleichen überraschen.
• UTF-8 in Excel. Excel benötigt ein UTF-8-BOM, um Sonderzeichen korrekt darzustellen. Schreiben Sie es vor der ersten Zeile: fwrite($file, "\xEF\xBB\xBF");. Siehe fwrite().
• Der Parameter $escape. Die alte Backslash-Maskierung kann Felder beschädigen, die legitim \ enthalten. Übergeben Sie escape: "" (PHP 7.4+) für eine saubere RFC 4180-Ausgabe; dies entspricht auch dem neuen Standard in PHP 9.
• Rückgabewert immer prüfen. fputcsv() gibt bei einem Fehler false zurück (beispielsweise bei vollem Datenträger oder einem schreibgeschützten Stream). Schließen Sie Schreibvorgänge für Produktionsexporte in eine Fehlerbehandlung ein.
• Praktische Alternative. Um einen vollständigen string in einem Aufruf in eine Datei zu schreiben, siehe file_put_contents(); verwenden Sie fputcsv(), wenn Sie eine korrekte CSV-Maskierung pro Zeile benötigen.

Die Datei wieder einlesen

Das natürliche Gegenstück zu fputcsv() ist fgetcsv(), das eine CSV-Zeile wieder in ein array parst:

<?php

$file = fopen('people.csv', 'r');

while (($row = fgetcsv($file)) !== false) {
    echo implode(' | ', $row), PHP_EOL;
}

fclose($file);

Wenn Sie bereits einen CSV-string im Speicher haben anstatt einer Datei, verwenden Sie stattdessen str_getcsv().

Fazit

fputcsv() ist die idiomatische Methode zum Exportieren von array-Daten als CSV in PHP: Sie übernimmt das Setzen von Anführungszeichen für Trennzeichen und das Maskieren von Anführungszeichen automatisch, unterstützt benutzerdefinierte Trennzeichen und lässt sich natürlich mit fopen() und fclose() kombinieren. Für portable Ausgabe übergeben Sie escape: "", und fügen Sie ein UTF-8-BOM hinzu, wenn die Datei für Excel bestimmt ist. Um die Daten wieder einzulesen, greifen Sie auf fgetcsv() zurück.

Übungen