fputcsv()

La funzione fputcsv() formatta una singola riga di dati — fornita come array PHP — in una riga CSV (valori separati da virgola) e la scrive in un file aperto. È il metodo standard per esportare dati tabulari come report, esportazioni di database o fogli di calcolo che gli utenti apriranno in Excel, Google Sheets o LibreOffice.

Questa pagina tratta la sintassi e i parametri, il tipico ciclo di scrittura, come fputcsv() racchiude in virgolette ed esegue automaticamente l'escape dei caratteri speciali, come controllare il delimitatore e il carattere di racchiusura, e le insidie più comuni (la nuova riga finale, UTF-8 in Excel e il cambiamento del valore predefinito del parametro $escape).

Sintassi

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

Valore restituito: il numero di byte scritti, oppure false in caso di errore.

Il parametro $eol è disponibile da PHP 8.1, e PHP 9.0 cambia il valore predefinito di $escape da "\\" a "". Se si vuole un output stabile e portabile oggi, passare escape: "" esplicitamente.

Come funziona fputcsv()

fputcsv() prende un array e scrive esattamente una riga. Per esportare una tabella si chiama una volta per riga all'interno di un ciclo. La funzione gestisce automaticamente le virgolette: qualsiasi campo che contiene il separatore, il carattere di racchiusura o un'interruzione di riga viene automaticamente racchiuso nel carattere di racchiusura, e le virgolette incorporate vengono raddoppiate.

Il flusso di lavoro di base è:

1. Costruire un array (o un array di array) contenente i dati da esportare.
2. Aprire il file di destinazione per la scrittura con fopen().
3. Chiamare fputcsv() una volta per ogni riga.
4. Chiudere il file con fclose().

Esempio di base: scrittura di un file 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');

Output:

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

Il primo array viene scritto come riga di intestazione, quindi ogni array successivo diventa una riga di dati.

Virgolette ed escape automatici

Non è necessario racchiudere i campi tra virgolette manualmente — fputcsv() decide quando è necessario farlo. Un campo viene racchiuso solo se contiene il delimitatore, un'interruzione di riga o il carattere di racchiusura.

<?php

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

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

fclose($file);

Output:

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

Si noti che Plain viene lasciato invariato, il campo contenente la virgola viene racchiuso tra virgolette, le doppie virgolette incorporate vengono raddoppiate (""), e il valore con un'interruzione di riga viene racchiuso in modo che l'interruzione di riga venga preservata. Lo stream php://output è utile per i test o per trasmettere un download senza un file temporaneo.

Delimitatore e carattere di racchiusura personalizzati

Per produrre un file separato da tabulazioni o da punti e virgola, passare l'argomento $separator. Molte impostazioni locali europee aprono i file delimitati da punti e virgola in modo più pulito in Excel.

<?php

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

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

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

fclose($file);

Output:

John;Doe;30
Jane	Doe	25

Insidie comuni

• Nuova riga finale. fputcsv() aggiunge sempre una terminazione di riga, quindi il file termina con una riga vuota. Quando lo si legge successivamente con fgetcsv() questo è innocuo, ma può sorprendere nei confronti byte per byte.
• UTF-8 in Excel. Excel necessita di un BOM UTF-8 per visualizzare correttamente i caratteri accentati. Scriverne uno prima della prima riga: fwrite($file, "\xEF\xBB\xBF");. Vedere fwrite().
• Il parametro $escape. L'escape con barra rovesciata legacy può corrompere i campi che contengono legittimamente \. Passare escape: "" (PHP 7.4+) per un output RFC 4180 corretto; corrisponde anche al nuovo valore predefinito di PHP 9.
• Controllare sempre il valore restituito. fputcsv() restituisce false in caso di errore (ad esempio, disco pieno o stream in sola lettura). Racchiudere le scritture nella gestione degli errori per le esportazioni in produzione.
• Alternativa conveniente. Per scrivere un'intera stringa in un file con una sola chiamata, vedere file_put_contents(); usare fputcsv() quando è necessario un corretto escape CSV per ogni riga.

Lettura del file

La controparte naturale di fputcsv() è fgetcsv(), che analizza una riga CSV e la riconverte in un array:

<?php

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

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

fclose($file);

Se si dispone già di una stringa CSV in memoria anziché di un file, usare invece str_getcsv().

Conclusione

fputcsv() è il modo idiomatico per esportare dati di array in CSV in PHP: gestisce automaticamente le virgolette per i delimitatori e l'escape delle virgolette, supporta separatori personalizzati e si integra naturalmente con fopen() e fclose(). Per un output portabile, passare escape: "", e aggiungere un BOM UTF-8 quando il file è destinato a Excel. Per leggere i dati di ritorno, usare fgetcsv().

Pratica