PHP Stream

PHP Stream

Uno stream in PHP è un modo generico per leggere o scrivere un flusso di dati, indipendentemente da dove questi dati risiedano. Un file su disco, un blocco di memoria, un socket di rete e il corpo di una risposta HTTP sono cose molto diverse, eppure PHP permette di gestirle con lo stesso insieme di funzioni. Questa uniformità è il punto centrale: una volta che sai come leggere un file con fopen()/fgets(), sai già come leggere una pagina web o un buffer di memoria.

Questa pagina illustra cosa sono gli stream, le funzioni che li gestiscono, i wrapper che identificano la sorgente di uno stream e come utilizzarli in modo sicuro.

Quale problema risolvono gli stream?

Senza gli stream sarebbe necessario un'API diversa per ogni sorgente di dati — una per i file, un'altra per HTTP, un'altra ancora per i socket. Gli stream offrono una singola astrazione:

• Wrapper — un prefisso come file://, php://, http:// o php://memory che indica a PHP che tipo di risorsa si sta indirizzando.
• Resource handle — il valore restituito da fopen(); viene passato a tutte le altre funzioni stream.
• Filtri e contesti — livelli opzionali che trasformano i dati (es. gzip) o configurano la connessione (es. header HTTP, timeout).

Grazie a questo design, è possibile sostituire un percorso locale con un URL remoto e la maggior parte del codice rimane invariata.

Funzioni stream principali

Queste funzioni costituiscono la base dell'API Streams:

Il parametro $mode controlla l'accesso: 'r' (lettura), 'w' (scrittura, troncamento), 'a' (aggiunta in coda), e le varianti '+' per lettura e scrittura.

Per letture e scritture singole di solito non è necessario gestire un handle — gli helper di alto livello file_get_contents() e file_put_contents() aprono, trasferiscono e chiudono uno stream per te in una singola chiamata.

Wrapper e tipi di stream

Il wrapper all'inizio della stringa target determina il tipo di stream:

• Stream su file (file://, o semplicemente un percorso) — leggono e scrivono dati nel filesystem. Vedi PHP File Handling e Open and Read a File.
• Stream in memoria (php://memory, php://temp) — un buffer di lettura/scrittura che risiede in RAM; ideale per costruire dati nei test senza toccare il disco.
• Stream I/O (php://stdin, php://stdout, php://input) — input/output standard e il corpo grezzo della richiesta.
• Stream di rete / socket (tcp://, ssl://) — lettura e scrittura su una connessione di rete.
• Stream HTTP/FTP (http://, https://, ftp://) — recuperano documenti remoti come se fossero file (richiede che allow_url_fopen sia abilitato).

Lettura di un file riga per riga

Questo esempio minimale e autonomo scrive un piccolo file, lo rilegge tramite uno stream una riga alla volta, poi esegue la pulizia:

<?php

$path = sys_get_temp_dir() . '/stream-demo.txt';

// Write three lines using the high-level helper.
file_put_contents($path, "alpha\nbeta\ngamma\n");

// Read them back through a stream handle.
$handle = fopen($path, 'r');
if ($handle === false) {
    exit("Could not open the stream.\n");
}

while (!feof($handle)) {
    $line = fgets($handle);
    if ($line !== false) {
        echo "Line: " . trim($line) . PHP_EOL;
    }
}

fclose($handle);
unlink($path);

Output:

Line: alpha
Line: beta
Line: gamma

Apriamo il file in modalità lettura, eseguiamo un ciclo finché feof() non segnala la fine, e leggiamo ogni riga con fgets(). Verifica sempre che fopen() non abbia restituito false prima di utilizzare l'handle, e chiama fclose() quando hai finito.

Utilizzo di uno stream in memoria

Gli stream in memoria si comportano come i file ma non accedono mai al disco — utili per assemblare output o per i test unitari:

<?php

$handle = fopen('php://memory', 'r+');

fwrite($handle, "buffered data");

// Rewind to the start before reading what we wrote.
rewind($handle);

echo fread($handle, 1024);

fclose($handle);

Output:

buffered data

Dopo la scrittura, è necessario eseguire rewind() del puntatore all'inizio prima di leggere, poiché la posizione interna si trova alla fine di ciò che è stato appena scritto.

Lettura di uno stream remoto

Poiché HTTP è solo un altro wrapper, lo stesso ciclo funziona su un URL quando allow_url_fopen è abilitato:

<?php

$handle = fopen('https://www.example.com', 'r');
if ($handle === false) {
    exit("Failed to open the remote stream.\n");
}

while (!feof($handle)) {
    echo fgets($handle);
}

fclose($handle);

Questo esempio richiede l'accesso alla rete e l'impostazione allow_url_fopen attivata, quindi non funzionerà in un ambiente sandbox offline. Per le applicazioni reali, un client HTTP dedicato come cURL offre un controllo migliore su header, timeout ed errori.

Gestione degli errori

Le funzioni stream segnalano i fallimenti restituendo false anziché lanciare eccezioni, quindi è necessario verificare ogni chiamata:

• Controlla il valore restituito da fopen() prima di leggere o scrivere.
• Racchiudi le operazioni rischiose in try/catch se converti i warning in eccezioni — vedi PHP Exceptions.
• Chiudi sempre gli handle con fclose() per liberare le risorse.

Conclusione

Gli stream offrono a PHP un'interfaccia singola e coerente per ogni tipo di flusso di dati — file, buffer di memoria, socket e risposte HTTP. Impara il piccolo insieme di funzioni principali (fopen, fread/fgets, fwrite, feof, fclose), comprendi i wrapper come file:// e php://memory, e affidati agli helper di alto livello file_get_contents()/file_put_contents() per i casi semplici. Per approfondire, esplora la creazione e scrittura di file e la corretta gestione degli errori.

Esercitazione