filectime()

Qu'est-ce que la fonction filectime() ?

La fonction filectime() est une fonction PHP intégrée qui retourne l'heure de changement d'inode d'un fichier — un horodatage Unix (le nombre de secondes depuis le 1er janvier 1970) représentant le moment où les métadonnées du fichier ont été modifiées pour la dernière fois. L'« inode » est la structure de données utilisée par un système de fichiers de type Unix pour stocker des informations sur un fichier (ses permissions, son propriétaire, sa taille et l'emplacement de ses blocs de données) séparément du contenu réel du fichier.

Un point de confusion courant : filectime() ne retourne pas l'heure de création du fichier. Le « c » signifie change (changement), pas create (création). L'heure de changement d'inode est mise à jour chaque fois que les métadonnées du fichier changent — par exemple lorsque vous exécutez chmod, chown, renommez le fichier, ou même lorsque vous modifiez son contenu (ce qui met également à jour les métadonnées). PHP ne dispose d'aucune fonction portable pour obtenir une véritable heure de création.

Utilisez la bonne fonction selon vos besoins :

• filectime() — quand l'inode (métadonnées) a été modifié pour la dernière fois (permissions, propriétaire, nombre de liens, renommage).
• filemtime() — quand le contenu du fichier a été modifié pour la dernière fois.
• fileatime() — quand le fichier a été consulté pour la dernière fois (lecture).

Voici la syntaxe de base de la fonction filectime() :

La syntaxe PHP de filectime()

filectime(string $filename): int|false

Où $filename est le chemin du fichier à vérifier. La fonction retourne l'heure de changement d'inode sous forme d'horodatage Unix, ou false (avec un E_WARNING) si le fichier n'existe pas ou n'est pas accessible. Puisque false et un horodatage peuvent tous deux paraître « faux » dans des comparaisons souples (un horodatage n'est jamais 0 en pratique, mais un code défensif reste important), vérifiez toujours le résultat avec l'opérateur strict !== false.

Comment utiliser la fonction filectime() ?

L'utilisation de la fonction filectime() est simple. Voici les étapes à suivre :

1. Appelez la fonction filectime() en lui passant le nom du fichier que vous souhaitez vérifier.
2. La fonction retournera un horodatage Unix représentant l'heure de changement d'inode, ou false en cas d'échec.
3. Vous pouvez formater l'horodatage Unix à l'aide de la fonction date() pour afficher l'heure dans un format plus lisible.

Voici un exemple de code qui montre comment utiliser la fonction filectime() :

Comment utiliser la fonction 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.";
}

Remarque : le paramètre filename accepte les chemins relatifs et absolus. Si vous utilisez un chemin relatif, il est résolu par rapport au répertoire de travail courant.

Dans cet exemple, nous vérifions l'heure de changement d'inode de myfile.txt à l'aide de la fonction filectime(). Nous stockons l'horodatage Unix retourné dans la variable $last_change_time. Le code vérifie d'abord que la fonction n'a pas retourné false, puis formate l'horodatage à l'aide de date(). Notez que date() s'appuie sur le fuseau horaire par défaut du serveur ; utilisez date_default_timezone_set() si vous avez besoin d'une sortie dans un fuseau horaire spécifique. Enfin, nous affichons un message indiquant quand les métadonnées du fichier ont été modifiées pour la dernière fois.

Un exemple autonome et exécutable

L'extrait ci-dessus dépend de l'existence d'un fichier sur le disque. L'exemple ci-dessous crée un fichier temporaire, modifie ses permissions pour forcer un changement d'inode, puis lit l'horodatage en retour — vous pouvez l'exécuter tel quel et voir une sortie réelle :

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

Cela affiche l'heure de changement formatée suivie de Is it a Unix timestamp (integer)? yes, confirmant que filectime() retourne un horodatage entier.

Attention au cache des stat

PHP met en cache le résultat des fonctions de stat de système de fichiers comme filectime(), filemtime() et fileperms() pendant la durée d'une seule requête pour améliorer les performances. Si vous modifiez un fichier et appelez immédiatement filectime() à nouveau dans le même script, vous risquez d'obtenir la valeur périmée en cache. Appelez clearstatcache() en premier pour obtenir une lecture fraîche :

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

Cela affiche ctime updated. Supprimez la ligne clearstatcache() et PHP risque de rapporter l'ancienne valeur à la place.

Conclusion

La fonction filectime() est un outil utile en PHP pour vérifier quand l'inode (métadonnées) d'un fichier a été modifié pour la dernière fois — permissions, propriétaire ou renommage. N'oubliez pas que malgré le « c », ce n'est pas une fonction d'heure de création : utilisez filemtime() pour l'heure de dernière modification du contenu, fileatime() pour l'heure du dernier accès, et appelez clearstatcache() lorsque vous avez besoin d'une lecture garantie fraîche dans la même requête. Associez-la à file_exists() pour éviter les avertissements sur les fichiers manquants.

Pratique