Capire file_get_contents in PHP

file_get_contents è una funzione PHP utilizzata per leggere il contenuto di un file in una string. Questa funzione è particolarmente utile quando si lavora con file di testo e può essere usata per recuperare il contenuto di un file da un server remoto o dal file system locale.

Sintassi

La sintassi della funzione file_get_contents è la seguente:

Sintassi della funzione PHP file_get_contents

file_get_contents(
    string $filename,
    bool $use_include_path = false,
    ?resource $context = null,
    int $offset = 0,
    ?int $maxlen = null
): string|false

• $filename: Il percorso del file o l'URL da leggere.
• $use_include_path: (opzionale) Se impostato a TRUE, la funzione cercherà il file nel percorso di include.
• $context: (opzionale) Una risorsa di contesto valida creata con stream_context_create().
• $offset: (opzionale) Specifica da dove iniziare a leggere nel file. Se $offset è negativo, la funzione inizierà a leggere dalla fine del file.
• $maxlen: (opzionale) Specifica il numero massimo di byte da leggere.

Come funziona file_get_contents

La funzione file_get_contents() accetta un percorso file o un URL come primo argomento e restituisce l'intero contenuto del file come una singola string. Poiché carica tutto in memoria in una volta sola, è il modo più semplice per leggere un intero file, ma anche lo strumento sbagliato per file più grandi della memoria disponibile.

Il valore restituito è il contenuto del file in caso di successo, o false in caso di errore. Poiché un file vuoto restituisce legittimamente una string vuota "" (che è falsy), confronta sempre con l'operatore stretto !== false anziché con un controllo di veridicità generico.

Lettura di un file locale

L'uso più comune è la lettura di un piccolo file locale, come un file di configurazione o un template:

$content = file_get_contents('config.txt');

if ($content !== false) {
    echo $content;
} else {
    echo "Error: could not read the file.";
}

file_get_contents() restituisce false in caso di errore — ad esempio, quando il file non esiste o il processo non ha i permessi di lettura — ed emette anche un avviso PHP. Per sopprimere l'avviso e gestire l'errore autonomamente, anteponi alla chiamata l'operatore di controllo degli errori @:

$content = @file_get_contents('missing.txt');

if ($content === false) {
    echo "File is unavailable.";
}

Lettura parziale di un file con offset e maxlen

Non è necessario leggere l'intero file. I parametri $offset e $maxlen consentono di leggere una porzione, utile per esaminare intestazioni o file molto grandi:

// File contains: "Hello, World!"
// Read 5 bytes starting at offset 7
echo file_get_contents('greeting.txt', false, null, 7, 5); // World

Un pattern comune nel mondo reale è leggere solo i primi byte per rilevare il tipo di un file, senza caricare l'intero file in memoria.

Recupero di un URL remoto

Quando l'impostazione allow_url_fopen di PHP è abilitata, è possibile passare un URL http:// o https:// e file_get_contents() scaricherà il corpo della risposta:

$html = file_get_contents('https://example.com');

if ($html !== false) {
    echo substr($html, 0, 100); // first 100 characters
}

Questo è comodo per script rapidi, ma per le chiamate HTTP in produzione — dove servono timeout, intestazioni personalizzate, corpi POST o codici di errore dettagliati — l'estensione cURL è la scelta più robusta.

Utilizzo di un'API JSON

Un'operazione frequente è recuperare JSON da un'API e decodificarlo in un array PHP. Combina file_get_contents() con json_decode():

$json = file_get_contents('https://api.example.com/data.json');
$data = json_decode($json, true); // true => associative array

echo $data['name'];

Invio di intestazioni con un contesto stream

Per inviare intestazioni HTTP personalizzate, impostare un timeout o effettuare una richiesta POST, passa un contesto stream creato con stream_context_create() come terzo argomento:

$context = stream_context_create([
    'http' => [
        'method'  => 'POST',
        'header'  => "Content-Type: application/json\r\n",
        'content' => json_encode(['key' => 'value']),
        'timeout' => 5,
    ],
]);

$response = file_get_contents('https://api.example.com/submit', false, $context);

Vantaggi

• Semplicità: recupera un intero file in una singola riga, senza dover aprire, leggere e chiudere manualmente un handle.
• Veloce per file piccoli: efficiente per la lettura di file di configurazione, template o dati di piccole e medie dimensioni.
• Versatilità: funziona su percorsi locali e, con allow_url_fopen, su URL remoti http/https/ftp tramite la stessa API.

Limitazioni e insidie

• Utilizzo della memoria: l'intero file viene caricato in memoria, quindi la lettura di un file da diversi gigabyte può superare il memory_limit di PHP. Per file grandi, usa lo streaming con fopen() e fread() oppure leggi riga per riga con fgets().
• Nessun dettaglio sugli errori HTTP: in caso di risposta remota 404 o 500, la chiamata restituisce false (o contenuto parziale) senza un codice di stato accessibile. Usa l'estensione cURL quando hai bisogno di ispezionare lo stato della risposta.
• allow_url_fopen deve essere attivo: gli URL remoti falliscono silenziosamente se questa direttiva php.ini è disabilitata, cosa comune su server con configurazioni di sicurezza rigide.
• File vuoto vs. errore: un file vuoto restituisce "", non false — un altro motivo per testare con !== false.

Funzioni correlate

• file_put_contents() — la controparte per la scrittura; salva una string in un file con una sola chiamata.
• file() — legge un file in un array di righe anziché in una singola string.
• readfile() — legge un file e lo scrive direttamente nel buffer di output (utile per servire download).
• fopen() — apre un handle per la lettura e scrittura incrementale in streaming.

Conclusione

file_get_contents() è una funzione semplice e versatile per leggere il contenuto di file locali e URL remoti in una string. La sua comodità la rende la scelta ideale per file piccoli, dati di configurazione e chiamate API rapide. Per file molto grandi, preferisci lo streaming con fopen()/fread(); per richieste HTTP in produzione, preferisci cURL. Usata con un controllo stretto !== false sul valore restituito, rimane una delle funzioni I/O più pratiche in PHP.

Esercitazione