filemtime()

La fonction filemtime() est une fonction PHP intégrée qui retourne l'heure à laquelle le contenu d'un fichier a été modifié pour la dernière fois, sous forme d'horodatage Unix. Elle fait partie des fonctions d'inspection du système de fichiers de PHP et est couramment utilisée pour l'invalidation du cache, les étiquettes « dernière mise à jour » et pour détecter si un fichier a changé depuis sa dernière lecture.

Ce chapitre couvre la syntaxe, la valeur de retour et la différence entre filemtime() et les fonctions associées filectime() / fileatime(), le formatage du résultat pour les humains, la gestion des erreurs, et le piège de la mise en cache des résultats qui surprend presque tout le monde.

Syntaxe

filemtime(string $filename): int|false

• $filename — chemin vers le fichier (ou répertoire) à inspecter.
• Valeur de retour — l'heure de modification sous forme d'horodatage Unix (secondes depuis le 1er janvier 1970 UTC) en cas de succès, ou false en cas d'échec.

Le « temps de modification » (mtime) change chaque fois que le contenu du fichier est écrit. Il ne change pas lorsque le fichier est simplement lu, ni lorsque seules ses métadonnées (permissions, propriétaire) changent — c'est le temps de modification de l'inode, signalé par filectime().

Un exemple de base

Comme un horodatage Unix est simplement un grand entier, vous le passez généralement à date() pour produire une chaîne lisible :

<?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__ est une constante magique qui pointe toujours vers le script actuel, donc cet extrait s'exécute sans que vous ayez à créer un fichier séparé. filemtime() retourne l'horodatage, et date() le formate (ici : nom complet du mois, jour, année, puis heure au format 24 heures).

Toujours gérer les échecs

filemtime() retourne false lorsque le fichier n'existe pas ou ne peut pas être lu, et émet également un avertissement. Comme false est approximativement égal à 0, ne passez jamais le résultat brut directement à date() — vérifiez-le d'abord, idéalement après avoir confirmé l'existence du fichier avec 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);
    }
}

Utilisez la comparaison stricte === false : un horodatage légitime ne sera jamais false, mais == false intercepterait aussi l'horodatage (impossible en pratique) 0.

mtime vs. ctime vs. atime

PHP expose trois horodatages de fichier différents. Savoir lequel utiliser évite des bugs subtils :

Pour « montrer quand cela a été modifié pour la dernière fois », vous voudrez presque toujours filemtime().

Le piège de la mise en cache : clearstatcache()

PHP met en cache les résultats des fonctions du système de fichiers comme filemtime() pour la durée d'une requête. Si vous modifiez un fichier puis appelez filemtime() à nouveau dans le même script, vous risquez d'obtenir la valeur périmée. Appelez clearstatcache() pour forcer une nouvelle lecture :

<?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);

Ici, touch() met à jour le temps de modification, et clearstatcache() garantit que le second appel à filemtime() le reflète.

Une utilisation pratique : le cache busting

Une utilisation courante en situation réelle consiste à ajouter le mtime du fichier à une URL d'asset afin que les navigateurs le retéléchargent uniquement lorsque le fichier change réellement :

<?php

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

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

Chaque fois que le CSS est modifié, $version change, invalidant automatiquement le cache du navigateur.

Conclusion

filemtime() indique quand le contenu d'un fichier a été modifié pour la dernière fois, sous forme d'horodatage Unix, et retourne false en cas d'échec. Associez-la à date() pour formater le résultat, protégez-vous contre false, pensez à clearstatcache() lorsque vous relisez un fichier que vous venez de modifier, et utilisez filectime() ou fileatime() lorsque vous avez besoin du temps de modification ou d'accès. Pour un ensemble complet de statistiques de fichier en un seul appel, voir stat().

Pratique