is_file()

Cos'è la funzione is_file()?

is_file() è una funzione PHP integrata che indica se un percorso punta a un file regolare — un file ordinario su disco, al contrario di una directory, del tipo di destinazione di un collegamento simbolico o di un file speciale (una pipe, un socket o un nodo dispositivo). Restituisce true solo per i file regolari e false per tutto il resto, inclusi i percorsi che non esistono.

È la funzione a cui ricorrere prima di tentare di leggere, includere o elaborare un file, quando conta sapere "questo percorso punta davvero a un file con cui posso lavorare?" più che "questo percorso esiste in qualche modo?".

Sintassi

is_file(string $filename): bool

• $filename — il percorso da controllare. Può essere relativo (risolto rispetto alla directory di lavoro corrente) o assoluto.
• Valore di ritorno — true se $filename esiste ed è un file regolare, false altrimenti. Non viene generato alcun avviso quando il file è mancante; si ottiene semplicemente false.

Esempio di base

Usando __FILE__ (il percorso assoluto dello script corrente) si garantisce che il controllo abbia successo, quindi lo script stampa un messaggio che conferma che il percorso è un file regolare. Sostituisci con qualsiasi percorso tu voglia — un percorso mancante o una directory restituisce false.

is_file() vs file_exists() vs is_dir()

Queste tre funzioni si sovrappongono e scegliere quella sbagliata è una fonte comune di bug:

La trappola principale: file_exists('/some/folder') è true per una directory. Se poi si tenta di usare fopen() o include su di essa come se fosse un file, si ottiene un errore. Usa is_file() ogni volta che il passo successivo presuppone un file reale:

<?php

$path = sys_get_temp_dir(); // a directory that definitely exists

var_dump(file_exists($path)); // bool(true)  — it exists
var_dump(is_file($path));     // bool(false) — but it is NOT a file
var_dump(is_dir($path));      // bool(true)  — it is a directory

Proteggere la lettura di un file

Un utilizzo tipico nel mondo reale: verificare che il percorso sia un file utilizzabile prima di leggerlo. Combinare is_file() con is_readable() evita sia gli errori "non è un file" sia quelli relativi ai permessi:

<?php

$path = __FILE__;

if (is_file($path) && is_readable($path)) {
    echo "Safe to read: " . basename($path);
} else {
    echo "Cannot read that path.";
}

Questo stampa un output del tipo Safe to read: is-file.mdx (il basename dello script in esecuzione), e si interrompe in modo pulito se il percorso è una directory, è mancante o non è leggibile.

Il problema della cache stat

PHP memorizza nella cache i risultati dei controlli del filesystem come is_file() per la durata di una richiesta, per evitare di accedere ripetutamente al disco. Se un file viene creato o eliminato dopo che PHP ha già controllato lo stesso percorso, una seconda chiamata a is_file() potrebbe restituire la risposta obsoleta dalla cache. Quando è necessario un risultato aggiornato — ad esempio in uno script a lunga esecuzione che crea un file e lo controlla immediatamente — svuota prima la cache:

<?php

clearstatcache();          // discard cached stat results
var_dump(is_file($path));  // now reflects the current state on disk

Problemi comuni

• Non è un controllo di sicurezza. Un percorso può superare is_file() ed essere comunque non leggibile o non scrivibile. Combinalo con is_readable() o is_writable() prima di agire.
• I collegamenti simbolici vengono seguiti. is_file() controlla la destinazione di un symlink, non il link stesso. Un symlink che punta a un file regolare restituisce true.
• Nessun avviso per i percorsi mancanti. A differenza dell'apertura di un file, un percorso inesistente restituisce semplicemente false, quindi is_file() è sicuro da chiamare senza sopprimere gli errori.

Conclusione

is_file() risponde a una domanda precisa — "questo è un file regolare?" — ed è il controllo giusto da mettere davanti a qualsiasi codice che legge, include o elabora un file. Usa file_exists() quando anche una directory sarebbe accettabile, is_dir() quando vuoi specificamente una cartella, e abbina is_file() ai controlli di leggibilità indicati sopra quando i permessi sono rilevanti.

Esercizio