stat()

Introduzione

La funzione stat() restituisce un singolo array contenente metadati di basso livello su un file: dimensione, permessi, proprietario, inode, conteggio dei link e tre timestamp (accesso, modifica e modifica dell'inode). È il wrapper PHP attorno alla chiamata di sistema C stat(), quindi fornisce in un'unica chiamata le stesse informazioni che altrimenti si raccoglierebbero da molte funzioni separate come filesize(), filemtime() e fileperms().

Questo articolo copre la sintassi, il significato completo di ogni valore restituito da stat(), i problemi comuni che si incontrano (la cache di stat, i link simbolici e gli indici stringa vs. numerici) e esempi eseguibili.

Sintassi

stat(string $filename): array|false

• $filename — il percorso del file di cui si vogliono ottenere informazioni.
• Valore restituito — un array che descrive il file, o false in caso di errore (ad esempio, il file non esiste o non è leggibile). Poiché può restituire false, verificare sempre il risultato prima di accedere ai suoi elementi.

stat() segue i link simbolici e riporta informazioni sul file di destinazione. Se si necessitano metadati sul link stesso, usare lstat(). Per ottenere i dati di un file di cui si possiede già un handle aperto, usare fstat().

Cosa restituisce stat()

L'array restituito è insolito: ogni valore appare due volte — una volta con un indice numerico e una volta con una chiave stringa descrittiva. Quindi $info[7] e $info['size'] hanno lo stesso valore. Questa doppia indicizzazione esiste per compatibilità con le versioni precedenti; per un codice leggibile, preferire le chiavi con nome.

Alcune note:

• mode combina sia il tipo di file che i bit di permesso. Per ottenere solo i bit di permesso Unix (come 0644), usare la maschera & 0777; per visualizzarli in ottale, racchiuderli in decoct().
• ctime è l'ora di modifica dell'inode (l'ultima volta che sono cambiati permessi, proprietà o link) — non è l'ora di creazione del file. La maggior parte dei filesystem Unix non memorizza affatto un'ora di creazione.
• I valori rdev, blksize e blocks non hanno significato su Windows.

Esempio: Lettura dei metadati di un file

Questo esempio crea un file temporaneo, ne legge i dati con stat() e stampa dimensione, permessi e ora di modifica:

<?php

// Create a small file to inspect.
$path = tempnam(sys_get_temp_dir(), 'demo');
file_put_contents($path, "Hello, stat()!");

$info = stat($path);
if ($info === false) {
    echo "Could not stat the file.";
    exit;
}

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

unlink($path); // clean up

Output (il permesso esatto e l'ora dipendono dal sistema in uso):

Size: 14 bytes
Permissions: 600
Modified: 2026-06-21 12:00:00

Proteggere sempre il codice dal caso false: passare un percorso inesistente produce un avviso e false, e accedere agli indici di false genererebbe un errore.

Attenzione: la cache di stat

Per prestazioni ottimali, PHP memorizza nella cache i risultati di stat() e delle funzioni file correlate. Se un file cambia durante la stessa esecuzione dello script e lo si rilegge con stat(), si potrebbero ottenere dati obsoleti. Cancellare la cache con clearstatcache() prima di rileggere:

<?php

$path = tempnam(sys_get_temp_dir(), 'demo');
file_put_contents($path, "first");
echo stat($path)['size'], "\n"; // 5

file_put_contents($path, "much longer content");
clearstatcache(true, $path);    // refresh cached metadata
echo stat($path)['size'], "\n"; // 19

unlink($path);

stat() vs. le funzioni monoscopo

Se si ha bisogno di una sola informazione, le funzioni dedicate sono più chiare e leggermente più efficienti:

• Dimensione del file → filesize()
• Ora di modifica → filemtime()
• Ora dell'ultimo accesso → fileatime()
• Permessi → fileperms()
• Tipo di file → filetype()

Usare stat() quando si hanno bisogno di più informazioni contemporaneamente, poiché effettua una singola chiamata di sistema invece di molte. Prima di eseguire stat(), si potrebbe anche voler verificare che il percorso sia un file reale con is_file() o file_exists().

Conclusione

La funzione stat() fornisce in un'unica chiamata uno snapshot completo e di basso livello dei metadati di un file. Ricordarsi di verificare il ritorno false, usare le chiavi dell'array con nome per la leggibilità, applicare la maschera & 0777 su mode per i permessi e cancellare la cache di stat se si rilegge un file che è cambiato durante l'esecuzione dello script. Quando si ha bisogno di un solo attributo, preferire la corrispondente funzione monoscopo.

Esercitazione