fgetcsv()

Einführung in die PHP-Funktion fgetcsv()

Die Funktion fgetcsv() in PHP liest eine einzelne Zeile aus einer geöffneten Datei und parst sie als CSV (Comma-Separated Values). Die Felder werden dabei als array zurückgegeben. Sie ist das Standardwerkzeug zum Importieren von Tabellenkalkulationsexporten, Daten-Feeds und tabellarischen Textdateien in PHP.

Der Grund, warum man fgetcsv() statt fgets() plus explode(',', ...) verwendet, liegt darin, dass CSV komplexer ist als das einfache Aufteilen an Kommas. Ein Feld kann ein Komma enthalten, wenn es in Anführungszeichen eingeschlossen ist ("Doe, John"), ein Feld kann sich über mehrere Zeilen erstrecken, und Anführungszeichen innerhalb eines zitierten Feldes werden verdoppelt (""). fgetcsv() übernimmt all diese Regeln für Sie, sodass Sie saubere Felder zurückbekommen, ohne einen eigenen Parser schreiben zu müssen.

Diese Seite behandelt die Signatur und Parameter, die Rückgabewerte sowie vollständige ausführbare Beispiele — das Lesen einer ganzen Datei, die Verwendung eines benutzerdefinierten Trennzeichens und das Zuordnen einer Kopfzeile zu assoziativen Zeilen.

Syntax

Die Syntax der Funktion fgetcsv() lautet wie folgt:

Die Syntax von PHP fgetcsv()

array fgetcsv ( resource $stream [, int $length = 0 [, string $delimiter = ',' [, string $enclosure = '"' [, string $escape = '\\' ]]]] )

• stream: der Dateizeiger, aus dem gelesen wird
• length: die maximale Länge der zu lesenden Zeile
• delimiter: das Trennzeichen für CSV-Daten
• enclosure: das Begrenzungszeichen für CSV-Daten
• escape: das Escape-Zeichen für CSV-Daten

Parameter

Die Funktion fgetcsv() akzeptiert einen erforderlichen Parameter und vier optionale Parameter:

1. $stream: Der Dateizeiger, aus dem gelesen werden soll. Dieser Parameter kann eine Ressource sein, die mit der Funktion fopen() oder einer ähnlichen Funktion erstellt wurde.
2. $length: Die maximale Länge der zu lesenden Zeile. Dieser Parameter ist optional und hat den Standardwert 0, was bedeutet, dass die gesamte Zeile gelesen wird.
3. $delimiter: Das Trennzeichen für CSV-Daten. Dieser Parameter ist optional und hat den Standardwert ','.
4. $enclosure: Das Begrenzungszeichen für CSV-Daten. Dieser Parameter ist optional und hat den Standardwert '"'.
5. $escape: Das Escape-Zeichen für CSV-Daten. Dieser Parameter ist optional und hat den Standardwert '\'. Hinweis: Dieser Parameter ist seit PHP 8.1 veraltet.

Rückgabewerte

Bei Erfolg gibt fgetcsv() ein indiziertes array zurück, das die aus der Zeile gelesenen Felder enthält. Eine leere Zeile gibt ein array mit einem einzigen null-Feld zurück. Am Ende der Datei gibt die Funktion false zurück — so erkennt man, wann das Lesen beendet werden soll. Wenn der Stream ungültig ist, wird ebenfalls false zurückgegeben.

Da sowohl „Dateiende" als auch „Fehler" false zurückgeben, ist der idiomatische Weg zur Iteration, fgetcsv() so lange aufzurufen, bis es false zurückgibt — üblicherweise als while-Bedingung.

Beispiele

Beispiel 1: Eine einzelne Zeile CSV-Daten lesen

Das folgende Beispiel öffnet eine Datei, liest eine Zeile CSV-Daten und schließt den Datei-Handle ordnungsgemäß. Prüfen Sie immer, ob fopen() erfolgreich war, bevor Sie lesen:

Eine einzelne Zeile CSV-Daten lesen

$fileHandle = fopen('data.csv', 'r');
if ($fileHandle !== false) {
    $row = fgetcsv($fileHandle);
    print_r($row);
    fclose($fileHandle);
}

Bei einer Datei, deren erste Zeile John,Doe,42 lautet, gibt dies aus:

Array
(
    [0] => John
    [1] => Doe
    [2] => 42
)

Beispiel 2: Alle Zeilen einer Datei durchlaufen

In der Praxis liest man selten nur eine Zeile. Rufen Sie fgetcsv() in einer while-Schleife auf, bis es false zurückgibt, um die gesamte Datei zu verarbeiten:

Alle Zeilen einer CSV-Datei lesen

$fileHandle = fopen('data.csv', 'r');
if ($fileHandle !== false) {
    while (($row = fgetcsv($fileHandle)) !== false) {
        echo implode(' | ', $row), PHP_EOL;
    }
    fclose($fileHandle);
}

Der strikte Vergleich !== false ist wichtig: Eine gültige Zeile wie ["0"] ist in PHP „falsy", sodass eine lose while ($row = fgetcsv(...))-Schleife bei legitimen Daten vorzeitig abbrechen würde.

Beispiel 3: Ein benutzerdefiniertes Trennzeichen verwenden

Viele „CSV"-Dateien sind tatsächlich semikolon- oder tabstoppgetrennt. Übergeben Sie das Trennzeichen als drittes Argument (das zweite Argument, $length, kann auf 0 gesetzt bleiben, um kein Limit zu setzen):

CSV-Daten mit einem benutzerdefinierten Trennzeichen lesen

// Semicolon-separated values
$row = fgetcsv($fileHandle, 0, ';');

// Tab-separated values
$row = fgetcsv($fileHandle, 0, "\t");

Beispiel 4: Kopfzeile auf assoziative Arrays abbilden

CSV-Dateien haben üblicherweise eine Kopfzeile. Lesen Sie diese einmal ein und kombinieren Sie sie dann mit jeder Datenzeile mithilfe von array_combine(), sodass Sie auf Felder nach Namen statt nach numerischem Index zugreifen können:

Eine CSV-Datei in assoziative Zeilen umwandeln

$fileHandle = fopen('users.csv', 'r');
if ($fileHandle !== false) {
    $header = fgetcsv($fileHandle); // e.g. ['id', 'name', 'email']
    while (($data = fgetcsv($fileHandle)) !== false) {
        $row = array_combine($header, $data);
        echo $row['name'], ' <', $row['email'], '>', PHP_EOL;
    }
    fclose($fileHandle);
}

Häufige Fallstricke

• Der Parameter $escape ist veraltet. Ab PHP 8.1 löst die Übergabe eines nicht leeren $escape-Werts einen Deprecation-Hinweis aus, und PHP 9 wird den Standardwert auf "" ändern. Für standardkonformes CSV (bei dem Anführungszeichen durch Verdopplung, "", escaped werden) sollte escape: "" explizit übergeben werden.
• UTF-8 BOM beim ersten Feld. Aus Excel exportierte Dateien können mit einem Byte-Order-Mark beginnen, sodass das erste Kopfzeilenfeld wie "\u{FEFF}id" aussehen kann. Entfernen Sie es mit ltrim($header[0], "\u{FEFF}"), wenn Vergleiche fehlschlagen.
• auto_detect_line_endings. Alte Mac-Zeilenenden (\r) konnten den Parser auf älteren PHP-Versionen verwirren; diese ini-Einstellung wurde in PHP 8.1 entfernt, da der Parser sie nun nativ verarbeitet.

Verwandte Funktionen

• fopen() — die Datei vor dem Lesen öffnen.
• fgets() — eine rohe Zeile ohne CSV-Parsing lesen.
• fputcsv() — das Gegenstück: ein array als CSV-Zeile schreiben.
• fclose() — den Handle nach dem Lesen schließen.
• PHP File Handling — das größere Bild der Dateiverarbeitung.

Fazit

fgetcsv() liest eine Zeile aus einer geöffneten Datei und parst sie als CSV, gibt ein indiziertes array der Felder zurück und gibt false am Dateiende zurück. Verwenden Sie eine strikte !== false-Prüfung in der Schleife, nutzen Sie array_combine(), um eine Kopfzeile auf benannte Felder abzubilden, und bedenken Sie, dass der Parameter $escape veraltet ist — übergeben Sie escape: "" für modernes, standardkonformes Parsing.

Übungen