filectime()

Cos'è la funzione filectime()?

La funzione filectime() è una funzione PHP integrata che restituisce il tempo di modifica dell'inode di un file — un timestamp Unix (il numero di secondi trascorsi dal 1° gennaio 1970) che rappresenta il momento in cui i metadati del file sono stati modificati per l'ultima volta. L'"inode" è la struttura dati utilizzata dai filesystem di tipo Unix per memorizzare le informazioni sul file (permessi, proprietario, dimensione e posizione dei blocchi dati) separatamente dal contenuto effettivo del file.

Un punto di confusione comune: filectime() non è il tempo di creazione del file. La "c" sta per change (modifica), non per create (creazione). Il tempo di modifica dell'inode si aggiorna ogni volta che i metadati del file cambiano — ad esempio quando si esegue chmod, chown, si rinomina il file, o persino quando se ne modifica il contenuto (il che aggiorna anche i metadati). PHP non dispone di una funzione portabile per ottenere il vero tempo di creazione.

Usa la funzione giusta in base alle tue necessità:

• filectime() — quando l'inode (metadati) è stato modificato per l'ultima volta (permessi, proprietario, conteggio dei link, rinomina).
• filemtime() — quando il contenuto del file è stato modificato per l'ultima volta.
• fileatime() — quando il file è stato acceduto (letto) per l'ultima volta.

Ecco la sintassi di base della funzione filectime():

La sintassi PHP di filectime()

filectime(string $filename): int|false

Dove $filename è il percorso del file da verificare. La funzione restituisce il tempo di modifica dell'inode come timestamp Unix, oppure false (con un E_WARNING) se il file non esiste o non è accessibile. Poiché false e un timestamp possono entrambi sembrare "falsy" nei confronti non stretti (un timestamp non è mai 0 nella pratica, ma il codice difensivo è importante), verifica sempre il risultato con l'operatore rigoroso !== false.

Come utilizzare la funzione filectime()?

Utilizzare la funzione filectime() è semplice. Ecco i passaggi da seguire:

1. Chiama la funzione filectime(), passando il nome del file che vuoi verificare.
2. La funzione restituirà un timestamp Unix che rappresenta il tempo di modifica dell'inode, oppure false in caso di errore.
3. Puoi formattare il timestamp Unix usando la funzione date() per visualizzare l'orario in un formato più leggibile.

Ecco un esempio di codice che mostra come utilizzare la funzione filectime():

Come utilizzare la funzione filectime()?

<?php

$filename = 'myfile.txt';
$last_change_time = filectime($filename);

if ($last_change_time !== false) {
    $change_time_string = date('F d Y H:i:s', $last_change_time);
    echo "The file $filename had its inode changed on $change_time_string";
} else {
    echo "Could not retrieve inode change time for $filename.";
}

Nota: il parametro filename accetta sia percorsi relativi che assoluti. Se si usa un percorso relativo, viene risolto rispetto alla directory di lavoro corrente.

In questo esempio, verifichiamo il tempo di modifica dell'inode di myfile.txt utilizzando la funzione filectime(). Salviamo il timestamp Unix restituito nella variabile $last_change_time. Il codice verifica innanzitutto che la funzione non abbia restituito false, quindi formatta il timestamp usando date(). Tieni presente che date() si basa sul fuso orario predefinito del server; usa date_default_timezone_set() se hai bisogno di un output con un fuso orario specifico. Infine, viene mostrato un messaggio che indica quando i metadati del file sono stati modificati per l'ultima volta.

Un esempio autonomo ed eseguibile

Lo snippet precedente dipende dall'esistenza di un file su disco. L'esempio seguente crea un file temporaneo, ne modifica i permessi per forzare una modifica dell'inode, quindi legge il timestamp — così puoi eseguirlo così com'è e vedere un output reale:

<?php

// Create a temporary file
$path = tempnam(sys_get_temp_dir(), 'demo');
file_put_contents($path, 'hello');

// Changing permissions updates the inode change time (ctime)
chmod($path, 0644);

$ctime = filectime($path);
echo "ctime: " . date('Y-m-d H:i:s', $ctime) . PHP_EOL;
echo "Is it a Unix timestamp (integer)? " . (is_int($ctime) ? 'yes' : 'no') . PHP_EOL;

unlink($path); // clean up

Questo stampa il tempo di modifica formattato seguito da Is it a Unix timestamp (integer)? yes, confermando che filectime() restituisce un timestamp intero.

Attenzione alla cache delle stat

PHP memorizza nella cache il risultato delle funzioni di stat del filesystem come filectime(), filemtime() e fileperms() per la durata di una singola richiesta, al fine di migliorare le prestazioni. Se modifichi un file e chiami immediatamente filectime() su di esso nello stesso script, potresti ottenere il valore obsoleto della cache. Chiama prima clearstatcache() per ottenere una lettura aggiornata:

<?php

$path = tempnam(sys_get_temp_dir(), 'demo');
$first = filectime($path);

sleep(1);
chmod($path, 0600); // changes the inode

clearstatcache();   // discard the cached stat result
$second = filectime($path);

echo ($second >= $first) ? "ctime updated\n" : "still cached\n";

unlink($path);

Questo stampa ctime updated. Rimuovi la riga clearstatcache() e PHP potrebbe riportare il valore precedente.

Conclusione

La funzione filectime() è uno strumento utile in PHP per verificare quando l'inode (metadati) di un file è stato modificato per l'ultima volta — permessi, proprietario o una rinomina. Ricorda che nonostante la "c", non è una funzione per il tempo di creazione: usa filemtime() quando hai bisogno dell'ultima ora di modifica del contenuto, fileatime() per l'ultimo tempo di accesso, e chiama clearstatcache() quando hai bisogno di una lettura garantita aggiornata all'interno della stessa richiesta. Abbinala a file_exists() per evitare avvisi su file mancanti.

Esercizio