fstat()

Cos'è la funzione fstat()?

La funzione fstat() restituisce metadati su un file a partire da un handle di file già aperto — dimensione, proprietario, permessi e timestamp. Il prefisso "f" indica che lavora su un puntatore a file (una risorsa restituita da fopen()), a differenza di stat(), che accetta un percorso del file.

Usa fstat() quando hai già uno stream aperto (per lettura o scrittura) e vuoi i suoi dettagli senza riaprire il file per nome. Questa pagina tratta la sintassi, la struttura completa dell'array restituito, un esempio eseguibile e le insidie più comuni.

Sintassi

fstat(resource $stream): array|false

$stream è il puntatore al file restituito da fopen(). In caso di successo fstat() restituisce un array associativo; in caso di errore restituisce false ed emette un avviso.

L'array restituito da fstat()

fstat() restituisce un array con 26 voci: ogni valore appare due volte — una volta con un indice numerico (0–12) e una volta con una chiave nominativa. Le chiavi nominative sono quelle che di solito si usano:

Poiché entrambe le forme sono presenti, $info[7] e $info['size'] restituiscono lo stesso valore. Preferisci le chiavi nominative — si leggono meglio e non dipendono dall'ordine.

Come usare la funzione fstat()

Il pattern è sempre lo stesso: apri uno stream, chiama fstat(), usa i dati, poi chiudi lo stream.

<?php

$path = 'example.txt';
file_put_contents($path, "Line one\nLine two\n");

// fstat() needs an open file handle, not a filename.
$handle = fopen($path, 'r');
$info   = fstat($handle);

echo "Size:     " . $info['size'] . " bytes\n";
echo "Modified: " . date('Y-m-d H:i:s', $info['mtime']) . "\n";
echo "Permissions: " . decoct($info['mode'] & 0777) . "\n";

fclose($handle);

L'esecuzione produce un output simile a:

Size:     18 bytes
Modified: 2026-06-21 07:49:12
Permissions: 644

La dimensione è 18 perché "Line one\nLine two\n" è esattamente 18 byte. I timestamp vengono restituiti come timestamp Unix, quindi date() li converte in un formato leggibile. $info['mode'] & 0777 maschera i bit del tipo di file e lascia solo le cifre dei permessi.

fstat() vs. stat() vs. filesize()

Queste tre funzioni si sovrappongono, quindi è utile sapere quando scegliere ciascuna:

• fstat() — hai già un handle aperto (ad esempio un file che stai leggendo o scrivendo). Non è necessaria nessuna ricerca aggiuntiva per percorso.
• stat() — hai solo un percorso e vuoi lo stesso array di metadati senza aprire il file.
• filesize() — hai bisogno solo del numero di byte e nient'altro; è la più semplice delle tre.

Insidie Comuni

• Passa una risorsa, non una stringa. fstat('file.txt') fallisce — devi passare l'handle da fopen(), non il nome del file. Usa stat() se hai solo un percorso.
• I risultati di stat sono memorizzati nella cache. PHP memorizza i metadati dei file per richiesta. Se un file cambia durante l'esecuzione dello script e lo rileggi, chiama prima clearstatcache() per evitare valori obsoleti.
• Alcuni campi dipendono dalla piattaforma. Su Windows, blksize e blocks vengono riportati come -1, e uid/gid sono tipicamente 0.
• Chiudi sempre l'handle con fclose() quando hai finito per liberare la risorsa.

Conclusione

fstat() è lo strumento giusto quando hai già un puntatore a file aperto e hai bisogno dei suoi metadati — dimensione, timestamp, proprietario e permessi — senza riaprire il file per nome. Ricorda che restituisce un array di 26 elementi (chiavi sia numeriche che nominative), che i campi size/mtime sono quelli che utilizzerai più spesso, e che clearstatcache() esiste per quando i risultati sembrano obsoleti. Se hai solo un percorso, usa invece stat().

Esercitazione