# str_getcsv

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

str_getcsv — Analyse une chaîne de caractères CSV dans un tableau

### Description

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

Analyse une chaîne de caractères représentant des champs au format CSV et retourne un tableau contenant tous les champs lus.

> Note: Les paramètres de locale sont pris en compte par cette fonction. Par exemple, les données encodées dans certains encodages à un octet peuvent être analysées incorrectement si `LC_CTYPE` est `en_US.UTF-8`.

### Liste de paramètres

`string`

  La chaîne à analyser.

`separator`

  Le paramètre `separator` définit le séparateur de champ. Il doit s'agir d'un caractère d'un seul octet.

`enclosure`

  Le paramètre `enclosure` définit le caractère d'encadrement des champs. Il doit s'agir d'un caractère d'un seul octet.

`escape`

  Le paramètre `escape` définit le caractère d'échappement. Il doit s'agir d'un caractère d'un seul octet ou d'une chaîne vide. La chaîne vide (`""`) désactive le mécanisme d'échappement propriétaire.

  > Note: En général un caractère d'encadrement `enclosure` est échappé à l'intérieur d'un champ en le dédoublant ; Cependant, le caractère d'échappement `escape` peut être utilisé comme une alternative. Donc pour la valeur par défaut `""` et `\"` ont la même signification. Outre échapper le caractère d'encadrement `enclosure` le caractère d'échappement `escape` n'a pas de signification spéciale ; même pas de s'échapper lui-même.

  Avertissement

  À partir de PHP 8.4.0, l'utilisation de la valeur par défaut de `escape` est dépréciée. Elle doit être fournie explicitement soit par position, soit par l'utilisation des arguments nommés.

Avertissement

Lorsque le `escape` est défini sur autre chose qu'une chaîne vide (`""`), cela peut entraîner un CSV qui n'est pas conforme à » RFC 4180 ou incapable de survivre à un aller-retour à travers les fonctions CSV de PHP. La valeur par défaut pour `escape` est `"\\"`, il est donc recommandé de la définir explicitement sur une chaîne vide. La valeur par défaut changera dans une future version de PHP, au plus tôt dans PHP 9.0.

### Valeurs de retour

Retourne un tableau contenant les champs lus.

### Erreurs / Exceptions

Lève une ValueError si `separator` ou `enclosure` n'a pas une longueur de un octet.

Lève une ValueError si `escape` n'a pas une longueur de un octet ou est une chaîne vide.

### Historique

Version | Description
--- | ---
8.4.0 | Se fier à la valeur par défaut de `escape` est désormais déprécié.
8.4.0 | Lève désormais une ValueError si `separator`, `enclosure`, ou `escape` est invalide. Cela imite le comportement de fgetcsv() et fputcsv().
8.3.0 | Une chaîne vide est renvoyée au lieu d'une chaîne contenant un seul octet nul pour le dernier champ si celui-ci contient uniquement une délimitation non terminée.
7.4.0 | Le paramètre `escape` interprète désormais une chaîne vide en tant que signal de désactiver le mécanisme d'échappement propriétaire. Auparavant, une chaîne vide était traité comme la valeur par défaut du paramètre.

### Exemples

Exemple #1 Exemple avec str_getcsv()

`<?php
$string = 'PHP,Java,Python,Kotlin,Swift';
$data = str_getcsv($string, escape: '\\');
var_dump($data);
?>`

L'exemple ci-dessus va afficher :

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

Exemple #2 Exemple de str_getcsv() avec une chaîne vide

Attention

Avec une chaîne vide, cette fonction retourne `[null]` plutôt qu'un tableau vide.

`<?php
$string = '';
$data = str_getcsv($string, escape: '\\');
var_dump($data);
?>`

L'exemple ci-dessus va afficher :

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

### Voir aussi

- fputcsv() - Formate une ligne en CSV et l'écrit dans un fichier
- fgetcsv() - Obtient une ligne depuis un pointeur de fichier et l'analyse pour des champs CSV
- SplFileObject::fgetcsv() - Récupère une ligne depuis le fichier et l'analyse comme étant des données CSV
- SplFileObject::fputcsv() - Écrit un tableau sous la forme d'une ligne CSV
- SplFileObject::setCsvControl() - Définit les options CSV
- SplFileObject::getCsvControl() - Récupère les options pour CSV