str_getcsv

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

str_getcsvParst einen CSV-String in ein Array

Beschreibung

str_getcsv(
    string $string,
    string $separator = ",",
    string $enclosure = "\"",
    string $escape = "\\"
): array

Parst eine Zeichenketten-Eingabe für Felder im CSV-Format und gibt ein Array mit den gelesenen Feldern zurück.

Hinweis: Die Spracheinstellung (Locale) wird von dieser Funktion beachtet. Beispielsweise können Daten, die in bestimmten Ein-Byte-Kodierungen kodiert sind, falsch interpretiert werden, wenn LC_CTYPE den Wert en_US.UTF-8 hat.

Parameter-Liste

string

Die zu parsende Zeichenkette.

separator

Der Parameter separator setzt das Feld-Trennzeichen. Es muss ein Single-Byte-Zeichen sein.

enclosure

Der Parameter enclosure setzt das Feld-Begrenzungszeichen. Es muss ein Single-Byte-Zeichen sein.

escape

Der Parameter escape setzt das Maskierungs-Zeichen. Es muss ein Single-Byte-Zeichen oder die leere Zeichenkette sein. Die leere Zeichenkette ("") deaktiviert den proprietären Maskierungsmechanismus.

Hinweis: Normalerweise wird ein enclosure-Zeichen in einem Feld maskiert, indem es verdoppelt wird; allerdings kann alternativ dazu das escape-Zeichen verwendet werden. So haben die Werte "" und \" standardmäßig dieselbe Bedeutung. Abgesehen von der Möglichkeit, das enclosure-Zeichen zu maskieren, hat das Zeichen escape keine besondere Bedeutung; es ist nicht einmal dazu geeignet, sich selbst zu maskieren.

Warnung

Seit PHP 8.4.0 ist es veraltet, sich auf den Standardwert von escape zu verlassen. Er muss explizit angegeben werden, entweder an der richtigen Stelle oder durch die Verwendung von benannten Argumenten.

Warnung

Wenn escape auf etwas anderes als eine leere Zeichenkette ("") gesetzt wird, kann dies zu einer CSV-Datei führen, die nicht mit » RFC 4180 konform ist oder die den Umlauf durch die PHP-CSV-Funktionen nicht übersteht. Der Standardwert für escape ist "\\", weshalb empfohlen wird, diesen Parameter explizit auf eine leere Zeichenkette zu setzen. Der Standardwert wird sich in einer zukünftigen Version von PHP ändern, jedoch nicht vor PHP 9.0.

Rückgabewerte

Gibt ein indexiertes Array zurück, das die eingelesenen Felder enthält.

Fehler/Exceptions

Wenn separator oder enclosure nicht ein Byte lang ist, wird ein ValueError geworfen.

Wenn escape nicht ein Byte lang oder eine leere Zeichenkette ist, wird ein ValueError geworfen.

Changelog

Version Beschreibung
8.4.0 Sich auf den Standardwert von escape zu verlassen, ist nun veraltet.
8.4.0 Ein ValueError wird nun ausgelöst, wenn separator, enclosure oder escape ungültig sind. Dies entspricht dem Verhalten von fgetcsv() und fputcsv().
8.3.0 Eine leere Zeichenkette wird anstelle einer Zeichenkette mit einem einzelnen Null-Byte für das letzte Feld zurückgegeben, wenn es nur einen nicht abgeschlossenen Feld-Begrenzer enthält.
7.4.0 Der Parameter escape interpretiert nun eine leere Zeichenkette als Signal, um den proprietären Maskierungsmechanismus zu deaktivieren. Zuvor wurde eine leere Zeichenkette wie der Vorgabewert behandelt.

Beispiele

Beispiel #1 str_getcsv()-Beispiel

<?php

$string
= 'PHP,Java,Python,Kotlin,Swift';
$data = str_getcsv($string);

var_dump($data);
?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

array(5) {
  [0]=>
  string(3) "PHP"
  [1]=>
  string(4) "Java"
  [2]=>
  string(6) "Python"
  [3]=>
  string(6) "Kotlin"
  [4]=>
  string(5) "Swift"
}

Beispiel #2 str_getcsv()-Beispiel mit einer leeren Zeichenkette

Achtung

Bei einer leeren Zeichenkette gibt diese Funktion den Wert [null] anstelle eines leeren Arrays zurück.

<?php

$string
= '';
$data = str_getcsv($string);

var_dump($data);
?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

array(1) {
  [0]=>
  NULL
}

Siehe auch