fstat()

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

La fonction fstat() renvoie des métadonnées sur un fichier à partir d'un handle de fichier déjà ouvert — sa taille, son propriétaire, ses permissions et ses horodatages. Le préfixe "f" indique qu'elle fonctionne avec un pointeur de fichier (une ressource retournée par fopen()), contrairement à stat(), qui prend un chemin de fichier.

Utilisez fstat() lorsque vous avez déjà un flux ouvert (en lecture ou en écriture) et que vous souhaitez obtenir ses détails sans rouvrir le fichier par son nom. Cette page couvre la syntaxe, la structure complète du tableau retourné, un exemple exécutable et les pièges courants.

Syntaxe

fstat(resource $stream): array|false

$stream est le pointeur de fichier retourné par fopen(). En cas de succès, fstat() renvoie un array associatif ; en cas d'échec, il renvoie false et émet un avertissement.

Le tableau retourné par fstat()

fstat() renvoie un array contenant 26 entrées : chaque valeur apparaît deux fois — une fois sous un index numérique (0–12) et une fois sous une clé nommée. Les clés nommées sont celles que vous utilisez habituellement :

Les deux formes étant présentes, $info[7] et $info['size'] donnent la même valeur. Préférez les clés nommées — elles sont plus lisibles et ne dépendent pas de l'ordre.

Comment utiliser la fonction fstat()

Le schéma est toujours le même : ouvrir un flux, appeler fstat(), utiliser les données, puis fermer le flux.

<?php

$path = 'example.txt';
file_put_contents($path, "Line one\nLine two\n");

// fstat() needs an open file handle, not a filename.
$handle = fopen($path, 'r');
$info   = fstat($handle);

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

fclose($handle);

L'exécution de ce code affiche quelque chose comme :

Size:     18 bytes
Modified: 2026-06-21 07:49:12
Permissions: 644

La taille est 18 car "Line one\nLine two\n" fait exactement 18 octets. Les horodatages sont retournés sous forme de timestamps Unix, donc date() les convertit en quelque chose de lisible. $info['mode'] & 0777 masque les bits de type de fichier et ne conserve que les chiffres de permission.

fstat() vs. stat() vs. filesize()

Ces trois fonctions se recoupent, il est donc utile de savoir laquelle choisir :

• fstat() — vous disposez déjà d'un handle ouvert (par exemple, un fichier que vous lisez ou écrivez). Aucune recherche de chemin supplémentaire n'est nécessaire.
• stat() — vous n'avez qu'un chemin et souhaitez obtenir le même array de métadonnées sans ouvrir le fichier.
• filesize() — vous n'avez besoin que du nombre d'octets et de rien d'autre ; c'est la plus simple des trois.

Pièges courants

• Passez une ressource, pas une string. fstat('file.txt') échoue — vous devez passer le handle de fopen(), pas le nom de fichier. Utilisez stat() si vous n'avez qu'un chemin.
• Les résultats stat sont mis en cache. PHP met en cache les métadonnées de fichier par requête. Si un fichier change en cours d'exécution du script et que vous le relisez, appelez clearstatcache() d'abord pour éviter des valeurs obsolètes.
• Certains champs dépendent de la plateforme. Sous Windows, blksize et blocks valent -1, et uid/gid sont généralement 0.
• Fermez toujours le handle avec fclose() lorsque vous avez terminé pour libérer la ressource.

Conclusion

fstat() est l'outil approprié lorsque vous détenez déjà un pointeur de fichier ouvert et avez besoin de ses métadonnées — taille, horodatages, propriétaire et permissions — sans rouvrir le fichier par son nom. N'oubliez pas qu'il retourne un array de 26 éléments (clés numériques et nommées), que les champs size/mtime sont ceux que vous utiliserez le plus souvent, et que clearstatcache() existe pour les cas où les résultats semblent obsolètes. Si vous n'avez qu'un chemin, utilisez stat() à la place.

Pratique