filemtime()

La funzione filemtime() è una funzione PHP integrata che restituisce l'ora in cui i contenuti di un file sono stati modificati per l'ultima volta, come timestamp Unix. È una delle funzioni di ispezione del filesystem di PHP ed è comunemente usata per l'invalidazione della cache, le etichette "ultimo aggiornamento" e per rilevare se un file è cambiato dall'ultima lettura.

Questo capitolo tratta la sintassi, il valore restituito e la differenza tra filemtime() e le funzioni correlate filectime() / fileatime(), la formattazione del risultato per gli esseri umani, la gestione degli errori e il problema della cache dei risultati che crea difficoltà a quasi tutti.

Sintassi

filemtime(string $filename): int|false

• $filename — percorso del file (o directory) da ispezionare.
• Valore restituito — l'ora di modifica come timestamp Unix (secondi dal 1° gennaio 1970 UTC) in caso di successo, oppure false in caso di errore.

Il "tempo di modifica" (mtime) cambia ogni volta che il contenuto del file viene scritto. Non cambia quando il file viene semplicemente letto, né quando cambia solo il suo metadato (permessi, proprietario) — quello è il tempo di modifica dell'inode, riportato da filectime().

Un esempio di base

Poiché un timestamp Unix è semplicemente un grande intero, di solito lo si passa a date() per produrre una stringa leggibile:

<?php

$filename = __FILE__; // inspect this script itself

$timestamp = filemtime($filename);
$readable  = date('F d Y H:i:s', $timestamp);

echo "The file was last modified on $readable";

__FILE__ è una costante magica che punta sempre allo script corrente, quindi questo snippet funziona senza dover creare un file separato. filemtime() restituisce il timestamp, e date() lo formatta (qui: nome del mese completo, giorno, anno, poi ora in formato 24 ore).

Gestire sempre i fallimenti

filemtime() restituisce false quando il file non esiste o non può essere letto, ed emette anche un avviso. Poiché false è liberamente uguale a 0, non passare mai il risultato grezzo direttamente a date() — verificarlo prima, idealmente dopo aver confermato l'esistenza del file con file_exists():

<?php

$filename = 'does-not-exist.txt';

if (!file_exists($filename)) {
    echo "File not found.";
} else {
    $timestamp = filemtime($filename);

    if ($timestamp === false) {
        echo "Could not read the modification time.";
    } else {
        echo "Last modified: " . date('Y-m-d H:i:s', $timestamp);
    }
}

Usare il confronto rigoroso === false: un timestamp legittimo non è mai false, ma == false catturerebbe anche il timestamp (impossibile in pratica) 0.

mtime vs. ctime vs. atime

PHP espone tre diversi timestamp di file. Sapere quale usare evita bug sottili:

Per "mostrami quando è stato modificato per l'ultima volta", si vuole quasi sempre filemtime().

Il problema della cache: clearstatcache()

PHP memorizza nella cache i risultati delle funzioni del filesystem come filemtime() per la durata di una richiesta. Se si modifica un file e poi si chiama nuovamente filemtime() nello stesso script, si potrebbe ottenere il valore obsoleto. Chiamare clearstatcache() per forzare una nuova lettura:

<?php

$filename = tempnam(sys_get_temp_dir(), 'demo');

file_put_contents($filename, 'first write');
$first = filemtime($filename);

sleep(1);
touch($filename);          // bump the mtime

clearstatcache();          // without this, you may still see $first
$second = filemtime($filename);

echo $second > $first ? "mtime updated\n" : "mtime unchanged (cached)\n";

unlink($filename);

Qui touch() aggiorna il tempo di modifica, e clearstatcache() garantisce che il secondo filemtime() lo rifletta.

Un uso pratico: cache busting

Un utilizzo reale comune è aggiungere l'mtime del file a un URL di asset in modo che i browser lo scarichino di nuovo solo quando il file cambia effettivamente:

<?php

$cssPath = __FILE__; // pretend this is 'styles.css'
$version = filemtime($cssPath);

echo "/assets/styles.css?v=$version";

Ogni volta che il CSS viene modificato, $version cambia, invalidando automaticamente la cache del browser.

Conclusione

filemtime() riporta quando i contenuti di un file sono stati modificati per l'ultima volta, come timestamp Unix, e restituisce false in caso di errore. Combinarlo con date() per formattare il risultato, proteggersi da false, ricordare clearstatcache() quando si rilegge un file appena modificato, e usare filectime() o fileatime() quando si ha bisogno del tempo di modifica dell'inode o del tempo di accesso. Per un set completo di statistiche sui file in una sola chiamata, vedere stat().

Pratica