fgetcsv()

Introduction à la fonction PHP fgetcsv()

La fonction fgetcsv() en PHP lit une seule ligne depuis un fichier ouvert et l'analyse en tant que CSV (valeurs séparées par des virgules), retournant les champs sous forme d'un array. C'est l'outil standard pour importer des exports de tableurs, des flux de données et des fichiers texte tabulaires dans PHP.

La raison pour laquelle on préfère fgetcsv() à fgets() suivi de explode(',', ...) est que le CSV est plus subtil qu'une simple division sur les virgules. Un champ peut contenir une virgule s'il est entouré de guillemets ("Doe, John"), un champ peut s'étendre sur plusieurs lignes, et les guillemets à l'intérieur d'un champ entre guillemets sont doublés (""). fgetcsv() gère toutes ces règles pour vous, vous retournant des champs propres sans avoir à écrire un analyseur.

Cette page couvre la signature et les paramètres, les valeurs de retour, et des exemples complets et exécutables — lire un fichier entier, utiliser un délimiteur personnalisé, et mapper une ligne d'en-tête vers des lignes associatives.

Syntaxe

La syntaxe de la fonction fgetcsv() est la suivante :

La syntaxe de PHP fgetcsv()

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

• stream : le pointeur de fichier à partir duquel lire
• length : la longueur maximale de la ligne à lire
• delimiter : le caractère délimiteur pour les données CSV
• enclosure : le caractère d'enclosure pour les données CSV
• escape : le caractère d'échappement pour les données CSV

Paramètres

La fonction fgetcsv() prend un paramètre obligatoire et quatre paramètres optionnels :

1. $stream : Le pointeur de fichier depuis lequel vous souhaitez lire. Ce paramètre peut être une ressource créée à l'aide de la fonction fopen() ou d'une fonction similaire.
2. $length : La longueur maximale de la ligne à lire. Ce paramètre est optionnel et vaut par défaut 0, ce qui signifie que la ligne entière sera lue.
3. $delimiter : Le caractère délimiteur pour les données CSV. Ce paramètre est optionnel et vaut par défaut ','.
4. $enclosure : Le caractère d'enclosure pour les données CSV. Ce paramètre est optionnel et vaut par défaut '"'.
5. $escape : Le caractère d'échappement pour les données CSV. Ce paramètre est optionnel et vaut par défaut '\'. Remarque : Ce paramètre est déprécié à partir de PHP 8.1.

Valeurs de retour

En cas de succès, fgetcsv() retourne un array indexé contenant les champs lus depuis la ligne. Une ligne vide retourne un array avec un seul champ null. À la fin du fichier, elle retourne false, ce qui indique quand arrêter la lecture. Si le flux n'est pas valide, elle retourne également false.

Étant donné que « fin de fichier » et « erreur » retournent tous deux false, la façon idiomatique de boucler est d'appeler fgetcsv() jusqu'à ce qu'elle retourne false — généralement dans une condition while.

Exemples

Exemple 1 : Lire une seule ligne de données CSV

L'exemple suivant ouvre un fichier, lit une ligne de données CSV, et ferme correctement le handle de fichier. Vérifiez toujours que fopen() a réussi avant de lire :

Lire une seule ligne de données CSV

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

Pour un fichier dont la première ligne est John,Doe,42, cela affiche :

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

Exemple 2 : Parcourir toutes les lignes d'un fichier

Dans du code réel, on lit rarement une seule ligne. Appelez fgetcsv() dans une boucle while jusqu'à ce qu'elle retourne false pour traiter le fichier entier :

Lire toutes les lignes d'un fichier CSV

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

La comparaison stricte !== false est importante : une ligne valide telle que ["0"] est « falsy » en PHP, donc un while ($row = fgetcsv(...)) souple s'arrêterait prématurément sur des données légitimes.

Exemple 3 : Utiliser un délimiteur personnalisé

De nombreux fichiers « CSV » sont en réalité séparés par des points-virgules ou des tabulations. Passez le délimiteur comme troisième argument (le deuxième argument, $length, peut rester à 0 pour aucune limite) :

Lire des données CSV avec un délimiteur personnalisé

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

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

Exemple 4 : Mapper une ligne d'en-tête vers des arrays associatifs

Les fichiers CSV ont généralement une ligne d'en-tête. Lisez-la une fois, puis combinez-la avec chaque ligne de données en utilisant array_combine() pour accéder aux champs par nom plutôt que par index numérique :

Transformer un fichier CSV en lignes associatives

$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);
}

Pièges courants

• Le paramètre $escape est déprécié. À partir de PHP 8.1, passer un $escape non vide déclenche un avertissement de dépréciation, et PHP 9 changera la valeur par défaut en "". Pour un CSV conforme aux normes (où les guillemets sont échappés par doublement, ""), passez explicitement escape: "".
• BOM UTF-8 sur le premier champ. Les fichiers exportés depuis Excel peuvent commencer par une marque d'ordre des octets, de sorte que le premier champ d'en-tête peut ressembler à "\u{FEFF}id". Supprimez-la avec ltrim($header[0], "\u{FEFF}") si les comparaisons échouent.
• auto_detect_line_endings. Les fins de ligne Mac (\r) anciennes pouvaient perturber l'analyseur sur les anciennes versions de PHP ; ce paramètre ini a été supprimé dans PHP 8.1 car l'analyseur les gère désormais nativement.

Fonctions associées

• fopen() — ouvrir le fichier avant la lecture.
• fgets() — lire une ligne brute sans analyse CSV.
• fputcsv() — l'inverse : écrire un array sous forme de ligne CSV.
• fclose() — fermer le handle une fois terminé.
• Gestion des fichiers PHP — la vue d'ensemble de la manipulation des fichiers.

Conclusion

fgetcsv() lit une ligne depuis un fichier ouvert et l'analyse en tant que CSV, retournant un array indexé de champs et false en fin de fichier. Bouclez avec une vérification stricte !== false, utilisez array_combine() pour mapper une ligne d'en-tête vers des champs nommés, et souvenez-vous que le paramètre $escape est déprécié — passez escape: "" pour un parsing moderne et conforme aux normes.

Pratique