fileinode()

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

La fonction PHP fileinode() retourne le numéro d'inode d'un fichier. Un inode (nœud d'index) est l'identifiant que le système de fichiers utilise en interne pour suivre les métadonnées et les blocs de données d'un fichier sur le disque — l'entrée réelle vers laquelle pointe le nom du fichier. Deux noms de fichiers qui partagent le même numéro d'inode sont des liens physiques vers le même fichier physique, donc fileinode() est la méthode standard pour détecter cela.

Cette page couvre la syntaxe, la valeur de retour, la gestion des fichiers manquants, le cache de stat qui l'affecte, ainsi que les raisons pratiques pour lesquelles vous pourriez l'utiliser.

Syntaxe

fileinode(string $filename): int|false

• $filename — le chemin vers le fichier que vous souhaitez inspecter.
• Valeur de retour — le numéro d'inode sous forme d'entier en cas de succès, ou false en cas d'échec (par exemple, lorsque le fichier n'existe pas). Sur la plupart des systèmes 64 bits, la valeur est un grand entier.

Exemple de base

L'exemple ci-dessous utilise __FILE__ (la constante magique pour le chemin du script en cours d'exécution) afin qu'il pointe toujours vers un fichier qui existe réellement :

<?php

$filename = __FILE__;
$inode = fileinode($filename);

echo "The inode number of $filename is $inode";

Sortie (le nombre exact dépend de votre système de fichiers) :

The inode number of /path/to/script.php is 326428208

Nous passons le chemin à fileinode(), stockons l'entier retourné dans $inode et l'affichons.

Gestion des échecs

Lorsque le fichier n'existe pas (ou n'est pas accessible), fileinode() retourne false et émet un E_WARNING. Utilisez la comparaison stricte (===) pour qu'un inode légitime de valeur 0 ne soit jamais confondu avec un échec :

<?php

$filename = 'does-not-exist.txt';
$inode = @fileinode($filename); // @ suppresses the warning

if ($inode === false) {
    echo "Could not read the inode for $filename — it may not exist.";
} else {
    echo "Inode: $inode";
}

Sortie :

Could not read the inode for does-not-exist.txt — it may not exist.

Une approche plus sûre consiste à vérifier l'existence du fichier en premier avec file_exists() plutôt que de supprimer les avertissements.

Détection des liens physiques

L'utilisation la plus courante de fileinode() dans le monde réel consiste à comparer deux chemins : si ceux-ci rapportent le même numéro d'inode sur le même système de fichiers, il s'agit du même fichier accessible via des noms différents.

<?php

$a = fileinode('/path/to/original.txt');
$b = fileinode('/path/to/hardlink.txt');

if ($a !== false && $a === $b) {
    echo "Both names point to the same file (hard link).";
} else {
    echo "These are distinct files.";
}

Le cache de stat

PHP met en cache le résultat des appels stat du système de fichiers (fileinode(), filesize(), filemtime(), et autres) pour des raisons de performance. Si un fichier est remplacé ou relié pendant l'exécution de votre script, vous pourriez obtenir un inode périmé. Appelez clearstatcache() pour forcer PHP à lire des métadonnées fraîches :

<?php

$first = fileinode(__FILE__);
clearstatcache();            // discard cached stat data
$second = fileinode(__FILE__);

var_dump($first === $second); // bool(true) — unchanged file

Quand l'utiliser ?

• Déduplication — regroupez les fichiers qui sont des liens physiques vers les mêmes données plutôt que de les copier.
• Détection des renommages vs nouveaux fichiers — un nom modifié avec le même inode indique un renommage, pas un nouveau fichier.
• Diagnostics et outillage — s'associe naturellement aux autres fonctions stat lors de l'audit d'un répertoire.

Pour obtenir l'ensemble complet des métadonnées en une seule fois, voir stat(). Pour des attributs spécifiques, il existe des fonctions dédiées : filesize(), filemtime(), fileatime(), filetype() et fileperms().

Conclusion

fileinode() retourne le numéro d'inode du système de fichiers d'un fichier sous forme d'entier, ou false en cas d'échec. Au-delà de la simple lecture du numéro, sa vraie valeur réside dans l'identification de deux chemins faisant référence au même fichier sous-jacent. Comparez toujours avec ===, protégez-vous contre les fichiers manquants et appelez clearstatcache() lorsqu'un fichier peut avoir changé en cours d'exécution du script.

Pratique