fseek()

Quando PHP legge o scrive un file, mantiene un cursore interno — l'indicatore di posizione del file — che segna dove avverrà la prossima lettura o scrittura. Normalmente quel cursore si sposta in avanti automaticamente man mano che chiami fread() o fwrite(). La funzione fseek() ti permette di spostarlo manualmente a qualsiasi posizione in byte, così puoi tornare indietro, saltare avanti o rileggere una parte di un file senza chiuderlo e riaprirlo.

Questo capitolo tratta la sintassi di fseek(), le tre modalità di whence, il suo valore di ritorno e i pattern pratici come la lettura di un record a un offset noto e lo spostamento oltre la fine di un file.

Sintassi

fseek(resource $stream, int $offset, int $whence = SEEK_SET): int

fseek() restituisce 0 in caso di successo e -1 in caso di errore. Non restituisce la nuova posizione — usa ftell() per ottenere quella.

Le tre modalità di whence

La costante $whence determina da dove viene contato l'offset:

<?php
fseek($file, 10);            // 10 bytes from the start (SEEK_SET is implied)
fseek($file, 5, SEEK_CUR);   // 5 bytes forward from where we are now
fseek($file, -4, SEEK_END);  // 4 bytes before the end of the file

Un esempio pratico

Creiamo un file, poi saltiamo al byte 6 e leggiamo da lì. Poiché scriviamo e leggiamo nello stesso script, l'esempio è completamente autonomo:

<?php

$filename = 'demo.txt';

// Create a file with known contents.
file_put_contents($filename, 'Hello, World!');

$file = fopen($filename, 'r');

fseek($file, 7, SEEK_SET);   // move the cursor to byte 7
$data = fread($file, 5);     // read 5 bytes: W, o, r, l, d
echo $data;                  // World

fclose($file);

La stringa 'Hello, World!' è memorizzata come byte H(0) e(1) l(2) l(3) o(4) ,(5) (6) W(7) o(8) r(9) l(10) d(11) !(12). Spostandosi al byte 7 si atterra sulla W, e leggendo 5 byte viene stampato World.

Verifica sempre il valore di ritorno

Poiché fseek() restituisce 0 per il successo e -1 per il fallimento, confrontalo esplicitamente. Un controllo di veridicità generico è sbagliato qui — 0 è falsy:

<?php

$file = fopen('demo.txt', 'r');

if (fseek($file, 7) === -1) {
    echo "Seek failed";
} else {
    echo "Seek succeeded";   // Seek succeeded
}

fclose($file);

Aspetti da tenere a mente

• Non tutti gli stream sono ricercabili. Pipe, socket di rete e lo stream php://stdin non possono essere cercati; fseek() restituisce -1 su di essi.
• Cercare oltre la fine è consentito. Con un file aperto in scrittura, puoi usare fseek() oltre la fine corrente e poi scrivere — il gap viene riempito con byte \0 (null), creando una regione sparsa.
• Usa SEEK_CUR con cautela in modalità append. I file aperti con modalità 'a' scrivono sempre alla fine indipendentemente dal cursore; fseek() influisce solo sulle letture in quella modalità.
• fseek() azzera il flag di fine file, quindi tornare indietro con seek ti permette di leggere dati già superati senza riaprire il file.

Funzioni correlate

• ftell() — riporta la posizione corrente del cursore (il complemento di fseek()).
• rewind() — scorciatoia per fseek($file, 0).
• fread() / fwrite() — legge o scrive a partire dalla posizione del cursore.
• fopen() / fclose() — apre e chiude lo stream.

Consulta il capitolo Gestione dei file PHP per il quadro completo.

Conclusione

fseek() ti offre accesso casuale a un file: sposta il cursore con un $offset misurato da SEEK_SET, SEEK_CUR o SEEK_END, quindi leggi o scrivi dalla nuova posizione. Ricorda di verificare il valore di ritorno -1, abbinalo a ftell() per sapere dove ti trovi, e tieni presente che non tutti gli stream supportano la ricerca.

Esercizio