lstat()

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

lstat() collecte des statistiques (taille, horodatages, propriétaire, permissions, etc.) sur un fichier désigné par $filename. Le « l » signifie link (lien) : contrairement à stat(), qui suit un lien symbolique et renvoie des informations sur la cible vers laquelle il pointe, lstat() renvoie des informations sur le lien lui-même.

Cette distinction n'est importante que pour les liens symboliques. Lorsque $filename est un fichier ordinaire, lstat() et stat() retournent des données identiques.

Cette page couvre la syntaxe, le tableau retourné, un exemple exécutable qui la compare à stat(), ainsi que les pièges courants à éviter.

Syntaxe

lstat(string $filename): array|false

• $filename — chemin vers le fichier ou le lien symbolique à inspecter.
• Retourne un tableau associatif de statistiques en cas de succès, ou false en cas d'échec (par exemple, si le chemin n'existe pas).

Un exemple exécutable

Le script ci-dessous crée un vrai fichier et un lien symbolique qui pointe vers lui, puis inspecte les deux avec lstat() et stat() afin de visualiser la différence :

<?php

$target = sys_get_temp_dir() . '/lstat_target.txt';
$link   = sys_get_temp_dir() . '/lstat_link';

file_put_contents($target, 'hello');   // 5-byte target file
@unlink($link);
symlink($target, $link);

$linkInfo   = lstat($link);   // the link itself
$targetInfo = stat($link);    // follows the link to the target

echo "Link size (lstat):  {$linkInfo['size']} bytes\n";
echo "Target size (stat): {$targetInfo['size']} bytes\n";
echo "Link modified:      " . date('Y-m-d', $linkInfo['mtime']) . "\n";

unlink($link);
unlink($target);

Sortie typique :

Link size (lstat):  65 bytes
Target size (stat): 5 bytes
Link modified:      2026-06-20

La taille retournée par lstat() correspond à la longueur des données de chemin du lien symbolique, et non à la taille du fichier vers lequel il pointe — c'est précisément l'information que stat() vous cacherait.

Le tableau retourné

lstat() retourne la même structure que stat() : un tableau de 26 éléments où chaque valeur apparaît deux fois — une fois sous un index numérique et une fois sous une clé de chaîne lisible. Préférez toujours les clés nommées pour plus de clarté :

Comme les clés nommées et numériques contiennent les mêmes valeurs, $info['size'] et $info[7] sont interchangeables — mais la forme nommée est bien plus facile à lire.

Quand utiliser lstat() plutôt que stat() ?

• Utilisez stat() lorsque vous vous intéressez au contenu du fichier et souhaitez que les liens soient résolus de manière transparente.
• Utilisez lstat() lorsque vous auditez le système de fichiers lui-même — par exemple, pour distinguer les vrais fichiers des liens symboliques, ou pour détecter un lien brisé dont la cible a été supprimée.

Pour vérifier si un chemin est un lien symbolique avant d'appeler lstat(), associez-le à is_link(). Pour lire vers où pointe un lien, utilisez readlink(), et pour en créer un, utilisez symlink().

Pièges courants

• Cache stat obsolète. PHP met en cache les résultats de stat/lstat par requête. Si un fichier change pendant l'exécution, appelez clearstatcache(true, $filename) avant de le relire.
• Windows. Les liens symboliques existent sous Windows, mais nécessitent des privilèges élevés pour être créés ; leur comportement peut différer des systèmes POSIX.
• Permissions. Votre processus PHP doit avoir accès en lecture au répertoire contenant le lien. Sur les systèmes renforcés, les modules de sécurité (comme SELinux ou les restrictions open_basedir) peuvent bloquer l'accès même si les permissions de fichier semblent correctes.

Conclusion

lstat() vous fournit les métadonnées d'un lien symbolique sans le suivre — ce que stat() ne peut pas faire. Utilisez-la chaque fois que vous devez inspecter les liens eux-mêmes plutôt que leurs cibles, lisez les valeurs par leurs clés nommées, et vérifiez toujours si le retour est false avant de faire confiance au résultat.

Pratique