fgetcsv()

Introduzione alla funzione PHP fgetcsv()

La funzione fgetcsv() in PHP legge una singola riga da un file aperto e la analizza come CSV (Comma-Separated Values), restituendo i campi come array. È lo strumento standard per importare esportazioni da fogli di calcolo, feed di dati e file di testo tabulari in PHP.

Il motivo per cui si preferisce fgetcsv() a fgets() più explode(',', ...) è che il formato CSV è più complesso di una semplice divisione sulle virgole. Un campo può contenere una virgola se è racchiuso tra virgolette ("Doe, John"), un campo può occupare più righe e le virgolette all'interno di un campo tra virgolette vengono raddoppiate (""). fgetcsv() gestisce tutte queste regole automaticamente, restituendo campi puliti senza dover scrivere un parser.

Questa pagina tratta la firma e i parametri della funzione, i valori restituiti ed esempi completi eseguibili — lettura di un intero file, utilizzo di un delimitatore personalizzato e mappatura di una riga di intestazione su righe associative.

Sintassi

La sintassi della funzione fgetcsv() è la seguente:

La sintassi di PHP fgetcsv()

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

• stream: il puntatore al file da cui leggere
• length: la lunghezza massima della riga da leggere
• delimiter: il carattere delimitatore per i dati CSV
• enclosure: il carattere di delimitazione dei campi per i dati CSV
• escape: il carattere di escape per i dati CSV

Parametri

La funzione fgetcsv() accetta un parametro obbligatorio e quattro parametri opzionali:

1. $stream: Il puntatore al file da cui si desidera leggere. Questo parametro può essere una risorsa creata tramite la funzione fopen() o una funzione simile.
2. $length: La lunghezza massima della riga da leggere. Questo parametro è opzionale e ha come valore predefinito 0, il che significa che verrà letta l'intera riga.
3. $delimiter: Il carattere delimitatore per i dati CSV. Questo parametro è opzionale e ha come valore predefinito ','.
4. $enclosure: Il carattere di delimitazione dei campi per i dati CSV. Questo parametro è opzionale e ha come valore predefinito '"'.
5. $escape: Il carattere di escape per i dati CSV. Questo parametro è opzionale e ha come valore predefinito '\'. Nota: questo parametro è deprecato a partire da PHP 8.1.

Valori restituiti

In caso di successo, fgetcsv() restituisce un array indicizzato contenente i campi letti dalla riga. Una riga vuota restituisce un array con un singolo campo null. Alla fine del file restituisce false, che segnala quando interrompere la lettura. Se il flusso non è valido restituisce anch'esso false.

Poiché sia "fine del file" che "errore" restituiscono false, il modo idiomatico per eseguire il ciclo è continuare a chiamare fgetcsv() finché non restituisce false — solitamente come condizione di un ciclo while.

Esempi

Esempio 1: Leggere una singola riga di dati CSV

L'esempio seguente apre un file, legge una riga di dati CSV e chiude correttamente l'handle del file. Verificare sempre che fopen() abbia avuto successo prima di leggere:

Leggere una singola riga di dati CSV

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

Per un file la cui prima riga è John,Doe,42, questo stampa:

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

Esempio 2: Iterare su ogni riga di un file

Nel codice reale raramente si legge una sola riga. Chiamare fgetcsv() in un ciclo while finché non restituisce false per elaborare l'intero file:

Leggere ogni riga di un file CSV

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

Il confronto rigoroso !== false è importante: una riga valida come ["0"] è "falsy" in PHP, quindi un while ($row = fgetcsv(...)) generico si interromperebbe prematuramente su dati legittimi.

Esempio 3: Utilizzare un delimitatore personalizzato

Molti file "CSV" sono in realtà separati da punto e virgola o da tabulazioni. Passare il delimitatore come terzo argomento (il secondo argomento, $length, può rimanere 0 senza limite):

Leggere dati CSV con un delimitatore personalizzato

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

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

Esempio 4: Mappare una riga di intestazione su array associativi

I file CSV di solito hanno una riga di intestazione. Leggerla una volta, poi combinarla con ogni riga di dati usando array_combine() per accedere ai campi per nome anziché per indice numerico:

Trasformare un file CSV in righe associative

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

Problemi comuni

• Il parametro $escape è deprecato. A partire da PHP 8.1, passare un $escape non vuoto genera un avviso di deprecazione, e PHP 9 cambierà il valore predefinito in "". Per un CSV conforme agli standard (dove le virgolette vengono gestite tramite raddoppio, ""), passare esplicitamente escape: "".
• BOM UTF-8 nel primo campo. I file esportati da Excel possono iniziare con un byte-order mark, quindi il primo campo dell'intestazione può apparire come "\u{FEFF}id". Rimuoverlo con ltrim($header[0], "\u{FEFF}") se i confronti falliscono.
• auto_detect_line_endings. Le terminazioni di riga dei vecchi Mac (\r) potevano confondere il parser sulle versioni precedenti di PHP; questa impostazione ini è stata rimossa in PHP 8.1 perché il parser le gestisce ora nativamente.

Funzioni correlate

• fopen() — apre il file prima della lettura.
• fgets() — legge una riga grezza senza analisi CSV.
• fputcsv() — l'inverso: scrive un array come riga CSV.
• fclose() — chiude l'handle al termine.
• Gestione dei file PHP — il quadro generale del lavoro con i file.

Conclusione

fgetcsv() legge una riga da un file aperto e la analizza come CSV, restituendo un array indicizzato di campi e false alla fine del file. Eseguire il ciclo con un controllo rigoroso !== false, usare array_combine() per mappare una riga di intestazione su campi denominati e ricordare che il parametro $escape è deprecato — passare escape: "" per un'analisi moderna e conforme agli standard.

Pratica