fgetc()

Introduzione alla funzione PHP fgetc()

La funzione fgetc() in PHP legge esattamente un carattere da un file aperto e avanza il puntatore al file di un byte in avanti. Il nome sta per "file get character". Ogni chiamata restituisce il carattere successivo, quindi chiamandola ripetutamente è possibile scorrere un file un carattere alla volta.

Si ricorre a fgetc() quando si ha bisogno di un controllo preciso, carattere per carattere — ad esempio per costruire un piccolo parser, contare caratteri specifici o fermarsi non appena si incontra un byte particolare. Per la maggior parte delle letture di file quotidiane, fgets() basato sulle righe o fread()/file_get_contents() per l'intero file sono più veloci e semplici, poiché ogni chiamata a fgetc() comporta l'overhead di una chiamata di funzione. Sapere quando non usarla è importante quanto sapere come usarla.

Questa pagina tratta la sintassi, i parametri, il valore restituito, esempi eseguibili e le insidie più comuni (in particolare la trappola del "0" a fine file).

Sintassi

fgetc(resource $stream): string|false

La funzione accetta un singolo argomento e restituisce il carattere letto oppure false.

Parametri

Il tipo resource rimane pienamente supportato in PHP 8+. Non sono necessarie modifiche per la compatibilità moderna.

Valori restituiti

• In caso di successo, restituisce una string contenente un singolo carattere letto dal file.
• Restituisce false quando viene raggiunta la fine del file (EOF) o in caso di errore.

Esempi

Esempio 1: Leggere un singolo carattere da un file

Questo codice legge solo il primo carattere del file. Verificare sempre che fopen() abbia avuto successo prima di usare l'handle e chiamare fclose() al termine.

<?php

$fileHandle = fopen('example.txt', 'r');
if ($fileHandle) {
    echo fgetc($fileHandle); // prints the first character
    fclose($fileHandle);
}

Esempio 2: Leggere un intero file carattere per carattere

Per leggere l'intero file, chiamare fgetc() in un ciclo e fermarsi quando restituisce false (EOF).

<?php

$fileHandle = fopen('example.txt', 'r');
if ($fileHandle) {
    while (($char = fgetc($fileHandle)) !== false) {
        echo $char;
    }
    fclose($fileHandle);
}

Questo stampa ogni carattere del file fino a EOF.

Perché !== false è importante (la trappola dello "0")

Un errore molto comune è scrivere il ciclo con un confronto non stretto:

// BUGGED: stops early on the first "0" or "" it reads
while ($char = fgetc($fileHandle)) {
    echo $char;
}

PHP tratta le stringhe "0" e "" come falsy. Se il file contiene un carattere 0, questo ciclo termina lì invece che a EOF. Usare sempre il confronto stretto di identità !== false in modo che solo il vero valore EOF interrompa il ciclo. La stessa regola vale per fgets() e fread().

Esempio 3: Contare le occorrenze di un carattere

Poiché fgetc() restituisce un carattere alla volta, è utile per conteggi in streaming senza caricare l'intero file in memoria:

<?php

$fileHandle = fopen('example.txt', 'r');
$vowels = 0;
if ($fileHandle) {
    while (($char = fgetc($fileHandle)) !== false) {
        if (str_contains('aeiouAEIOU', $char)) {
            $vowels++;
        }
    }
    fclose($fileHandle);
    echo "Vowels: $vowels";
}

fgetc() vs fgets() vs fread()

Per i file binari, preferire fread() — usare fgetc() in un ciclo funziona ma è molto più lento per ogni byte.

Note e insidie

• fgetc() funziona su stream binary-safe: restituisce un byte anche per caratteri non testuali. I caratteri UTF-8 multi-byte si estendono su più byte, quindi una singola chiamata a fgetc() può restituire solo una parte di tale carattere.
• Aprire il file con la modalità corretta ('r', 'rb', ecc.) tramite fopen() e ricordarsi di chiuderlo con fclose().
• È anche possibile verificare esplicitamente la fine del file con feof(), anche se il confronto di fgetc() con false è di solito sufficiente.

Conclusione

fgetc() legge un carattere alla volta da un puntatore a file aperto e restituisce false a fine file, il che la rende ideale per il parsing e il conteggio a livello di carattere. Basta ricordare i due elementi essenziali: passare una risorsa aperta da fopen() e terminare il ciclo di lettura con il controllo stretto !== false in modo che un letterale 0 non lo interrompa prematuramente. Per lavori basati su righe o blocchi, preferire fgets() o fread().

Per ulteriori informazioni sulla gestione dei file in PHP, consultare la guida Gestione dei file PHP.

Pratica