fputcsv()

La fonction fputcsv() formate une seule ligne de données — fournie sous forme de tableau PHP — en une ligne CSV (valeurs séparées par des virgules) et l'écrit dans un fichier ouvert. C'est la méthode standard pour exporter des données tabulaires telles que des rapports, des exports de bases de données ou des feuilles de calcul que les utilisateurs ouvriront dans Excel, Google Sheets ou LibreOffice.

Cette page couvre la syntaxe et les paramètres, la boucle d'écriture typique, la façon dont fputcsv() gère automatiquement les guillemets et l'échappement des caractères spéciaux, le contrôle du délimiteur et du caractère d'encadrement, ainsi que les erreurs les plus courantes (le saut de ligne final, l'UTF-8 dans Excel et la modification de la valeur par défaut du paramètre $escape).

Syntaxe

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

Valeur de retour : le nombre d'octets écrits, ou false en cas d'échec.

Le paramètre $eol est disponible à partir de PHP 8.1, et PHP 9.0 modifie la valeur par défaut de $escape de "\\" à "". Si vous souhaitez une sortie stable et portable dès aujourd'hui, passez escape: "" explicitement.

Fonctionnement de fputcsv()

fputcsv() prend un tableau et écrit exactement une ligne. Pour exporter une table, vous l'appelez une fois par ligne dans une boucle. La fonction gère les guillemets à votre place : tout champ contenant le séparateur, le caractère d'encadrement ou un saut de ligne est automatiquement encadré par le caractère d'encadrement, et les guillemets intégrés sont doublés.

Le flux de travail de base est le suivant :

1. Construire un tableau (ou un tableau de tableaux) contenant les données à exporter.
2. Ouvrir le fichier cible en écriture avec fopen().
3. Appeler fputcsv() une fois par ligne.
4. Fermer le fichier avec fclose().

Exemple de base : écriture d'un fichier CSV

<?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');

Résultat :

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

Le premier tableau est écrit comme ligne d'en-tête, puis chaque tableau suivant devient une ligne de données.

Mise entre guillemets et échappement automatiques

Vous n'avez pas besoin de mettre les champs entre guillemets vous-même — fputcsv() décide quand les guillemets sont nécessaires. Un champ n'est encadré que s'il contient le délimiteur, un saut de ligne ou le caractère d'encadrement.

<?php

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

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

fclose($file);

Résultat :

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

Notez que Plain est laissé tel quel, le champ contenant une virgule est mis entre guillemets, les guillemets doubles intégrés sont doublés (""), et la valeur avec un saut de ligne est encadrée pour que le saut de ligne survive. Le flux php://output est pratique pour les tests ou pour diffuser un téléchargement sans fichier temporaire.

Délimiteur et caractère d'encadrement personnalisés

Pour produire un fichier séparé par des tabulations ou des points-virgules, passez l'argument $separator. De nombreuses locales européennes ouvrent les fichiers délimités par des points-virgules plus proprement dans Excel.

<?php

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

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

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

fclose($file);

Résultat :

John;Doe;30
Jane	Doe	25

Pièges courants

• Saut de ligne final. fputcsv() ajoute toujours une fin de ligne, de sorte que le fichier se termine par une ligne vide. Lorsque vous le lisez ensuite avec fgetcsv(), cela est sans conséquence, mais peut surprendre lors de comparaisons exactes octet par octet.
• UTF-8 dans Excel. Excel a besoin d'un BOM UTF-8 pour afficher correctement les caractères accentués. Écrivez-en un avant la première ligne : fwrite($file, "\xEF\xBB\xBF");. Voir fwrite().
• Le paramètre $escape. L'échappement par barre oblique inversée hérité peut corrompre des champs contenant légitimement \. Passez escape: "" (PHP 7.4+) pour une sortie RFC 4180 propre ; cela correspond également au nouveau comportement par défaut de PHP 9.
• Vérifiez toujours la valeur de retour. fputcsv() retourne false en cas d'échec (par exemple, disque plein ou flux en lecture seule). Encadrez les écritures d'une gestion d'erreurs pour les exports en production.
• Alternative pratique. Pour écrire une chaîne entière dans un fichier en un seul appel, consultez file_put_contents() ; utilisez fputcsv() quand vous avez besoin d'un échappement CSV approprié par ligne.

Relecture du fichier

Le pendant naturel de fputcsv() est fgetcsv(), qui analyse une ligne CSV et la reconvertit en tableau :

<?php

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

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

fclose($file);

Si vous disposez déjà d'une chaîne CSV en mémoire plutôt que d'un fichier, utilisez plutôt str_getcsv().

Conclusion

fputcsv() est la méthode idiomatique pour exporter des données de tableau en CSV en PHP : elle gère automatiquement les guillemets de délimiteur et l'échappement des guillemets, prend en charge les séparateurs personnalisés et se couple naturellement avec fopen() et fclose(). Pour une sortie portable, passez escape: "", et ajoutez un BOM UTF-8 lorsque le fichier est destiné à Excel. Pour relire les données, utilisez fgetcsv().

Pratique