stat()

Introduction

La fonction stat() retourne un tableau unique contenant des métadonnées de bas niveau sur un fichier : sa taille, ses permissions, son propriétaire, son inode, le nombre de liens et trois horodatages (accès, modification et changement d'inode). Il s'agit du wrapper PHP autour de l'appel système C stat(), qui vous donne en un seul appel les mêmes informations que vous obtiendriez autrement de nombreuses fonctions séparées telles que filesize(), filemtime() et fileperms().

Cet article couvre la syntaxe, la signification complète de chaque valeur retournée par stat(), les pièges courants (le cache stat, les liens symboliques et les indices string vs. numériques) ainsi que des exemples exécutables.

Syntaxe

stat(string $filename): array|false

• $filename — le chemin vers le fichier dont vous souhaitez obtenir des informations.
• Valeur de retour — un tableau décrivant le fichier, ou false en cas d'échec (par exemple, si le fichier n'existe pas ou n'est pas lisible). Étant donné qu'elle peut retourner false, vérifiez toujours le résultat avant d'indexer dedans.

stat() suit les liens symboliques et rapporte sur le fichier cible. Si vous avez besoin des métadonnées sur le lien lui-même, utilisez lstat(). Pour obtenir des informations sur un fichier dont vous possédez déjà un descripteur ouvert, utilisez fstat().

Ce que stat() retourne

Le tableau retourné est inhabituel : chaque valeur apparaît deux fois — une fois sous un index numérique et une fois sous une clé string descriptive. Ainsi, $info[7] et $info['size'] désignent la même valeur. Ce double indexage existe pour la compatibilité ascendante ; préférez les clés nommées pour un code lisible.

Quelques remarques :

• mode regroupe à la fois le type de fichier et les bits de permissions. Pour obtenir uniquement les bits de permissions Unix (comme 0644), appliquez un masque avec & 0777 ; pour les afficher en octal, utilisez decoct().
• ctime correspond à l'heure de changement d'inode (la dernière fois que les permissions, la propriété ou les liens ont changé) — ce n'est pas l'heure de création du fichier. La plupart des systèmes de fichiers Unix ne stockent pas du tout une heure de création.
• Les valeurs rdev, blksize et blocks n'ont pas de signification sous Windows.

Exemple : lecture des métadonnées d'un fichier

Cet exemple crée un fichier temporaire, obtient ses informations avec stat() et affiche la taille, les permissions et l'heure de modification :

<?php

// Create a small file to inspect.
$path = tempnam(sys_get_temp_dir(), 'demo');
file_put_contents($path, "Hello, stat()!");

$info = stat($path);
if ($info === false) {
    echo "Could not stat the file.";
    exit;
}

echo "Size: {$info['size']} bytes\n";
echo "Permissions: " . decoct($info['mode'] & 0777) . "\n";
echo "Modified: " . date('Y-m-d H:i:s', $info['mtime']) . "\n";

unlink($path); // clean up

Sortie (la permission et l'heure exactes dépendent de votre système) :

Size: 14 bytes
Permissions: 600
Modified: 2026-06-21 12:00:00

Protégez-vous toujours contre false : passer un chemin inexistant produit un avertissement et false, et indexer false lèverait sinon une erreur.

Piège : le cache stat

Pour des raisons de performances, PHP met en cache les résultats de stat() et des fonctions de fichiers associées. Si un fichier change pendant l'exécution du même script et que vous l'interrogez à nouveau, vous risquez d'obtenir des données obsolètes. Videz le cache avec clearstatcache() avant de relire :

<?php

$path = tempnam(sys_get_temp_dir(), 'demo');
file_put_contents($path, "first");
echo stat($path)['size'], "\n"; // 5

file_put_contents($path, "much longer content");
clearstatcache(true, $path);    // refresh cached metadata
echo stat($path)['size'], "\n"; // 19

unlink($path);

stat() vs. les fonctions à usage unique

Si vous n'avez besoin que d'une seule information, les fonctions dédiées sont plus claires et légèrement moins coûteuses :

• Taille du fichier → filesize()
• Heure de modification → filemtime()
• Dernier accès → fileatime()
• Permissions → fileperms()
• Type de fichier → filetype()

Utilisez stat() lorsque vous avez besoin de plusieurs de ces informations à la fois, car il effectue un seul appel système au lieu de plusieurs. Avant d'appeler stat, vous pouvez également vérifier que le chemin est bien un fichier réel avec is_file() ou file_exists().

Conclusion

La fonction stat() vous donne un instantané complet et de bas niveau des métadonnées d'un fichier en un seul appel. N'oubliez pas de vérifier le retour false, d'utiliser les clés nommées du tableau pour la lisibilité, de masquer mode avec & 0777 pour les permissions, et de vider le cache stat si vous relisez un fichier modifié en cours de script. Lorsque vous n'avez besoin que d'un seul attribut, préférez la fonction dédiée correspondante.

Pratique