fileperms()

La fonction fileperms() de PHP lit les bits de permission et de type d'un fichier depuis le système de fichiers et les retourne sous forme d'un entier unique (le mode de fichier Unix). Cette page explique ce que contient cet entier, comment le convertir en notation octale familière comme 0644, le piège qui surprend presque tout le monde la première fois, et comment le transformer en chaîne de style ls -l. Sur les systèmes non-Unix tels que Windows, la valeur est moins significative, mais la fonction fonctionne tout de même.

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

La fonction fileperms() retourne les permissions du fichier spécifié par filename sous forme d'entier, ou false en cas d'échec (par exemple, si le fichier n'existe pas). L'entier encode à la fois le type de fichier (fichier ordinaire, répertoire, lien symbolique, etc.) et les bits d'accès (lecture/écriture/exécution pour le propriétaire, le groupe et les autres).

Syntaxe

fileperms(string $filename): int|false

• $filename — chemin vers le fichier ou le répertoire à inspecter.

Comme le résultat est un entier brut, on le convertit presque toujours en octal avec sprintf() avant de l'afficher à un utilisateur :

sprintf('%o', fileperms($filename));

Le piège : la valeur n'est pas simplement 0644

La principale surprise est que fileperms() ne retourne pas 0644. Elle retourne le mode complet, qui inclut les bits de type de fichier. Un fichier ordinaire avec les permissions 0644 donne le mode octal 100644, et un répertoire avec 0755 donne 40755 :

<?php

$filename = 'demo.txt';
file_put_contents($filename, 'demo');
chmod($filename, 0644);

$perms = fileperms($filename);

echo $perms, "\n";                       // 33188  (decimal)
echo sprintf('%o', $perms), "\n";        // 100644 (octal, includes type bits)
echo sprintf('%o', $perms & 0777), "\n"; // 644    (permission bits only)
echo substr(sprintf('%o', $perms), -4);  // 0644   (last four octal digits)

Pour obtenir uniquement les bits de permission, masquez la valeur avec & 0777 (ce qui supprime tout ce qui dépasse les trois chiffres octaux inférieurs), ou prenez les derniers chiffres de la chaîne octale avec substr(). Utilisez l'approche par masquage lorsque vous souhaitez comparer à un nombre ; utilisez substr() lorsque vous voulez une chaîne imprimable complétée à quatre chiffres.

Lecture des permissions d'un fichier existant

Dans du code réel, vérifiez d'abord que le fichier existe afin de ne pas déclencher un avertissement s'il est absent :

<?php

$filename = 'demo.txt';
file_put_contents($filename, 'demo');
chmod($filename, 0644);

if (file_exists($filename)) {
    $perms = fileperms($filename);
    printf("%s -> %s\n", $filename, substr(sprintf('%o', $perms), -4));
    // demo.txt -> 0644
} else {
    echo "File not found.\n";
}

Voir file_exists() pour tester l'existence et is_readable() lorsque vous souhaitez savoir si votre processus peut réellement lire le fichier plutôt que le mode brut.

Transformer le mode en chaîne ls -l

Les bits retournés par fileperms() correspondent directement à la notation -rw-r--r-- affichée par ls -l. Les bits de poids fort sélectionnent le caractère de type ; les neuf bits de poids faible sont les triplets rwx pour le propriétaire, le groupe et les autres. Cet extrait (adapté du manuel officiel PHP) construit cette chaîne :

<?php

$filename = 'demo.txt';
file_put_contents($filename, 'demo');
chmod($filename, 0644);

$perms = fileperms($filename);

switch ($perms & 0xF000) {
    case 0xC000: $info = 's'; break; // socket
    case 0xA000: $info = 'l'; break; // symbolic link
    case 0x8000: $info = '-'; break; // regular file
    case 0x6000: $info = 'b'; break; // block special
    case 0x4000: $info = 'd'; break; // directory
    case 0x2000: $info = 'c'; break; // character special
    case 0x1000: $info = 'p'; break; // FIFO pipe
    default:     $info = 'u';        // unknown
}

// Owner
$info .= ($perms & 0x0100) ? 'r' : '-';
$info .= ($perms & 0x0080) ? 'w' : '-';
$info .= ($perms & 0x0040)
    ? (($perms & 0x0800) ? 's' : 'x')
    : (($perms & 0x0800) ? 'S' : '-');
// Group
$info .= ($perms & 0x0020) ? 'r' : '-';
$info .= ($perms & 0x0010) ? 'w' : '-';
$info .= ($perms & 0x0008)
    ? (($perms & 0x0400) ? 's' : 'x')
    : (($perms & 0x0400) ? 'S' : '-');
// Other
$info .= ($perms & 0x0004) ? 'r' : '-';
$info .= ($perms & 0x0002) ? 'w' : '-';
$info .= ($perms & 0x0001)
    ? (($perms & 0x0200) ? 't' : 'x')
    : (($perms & 0x0200) ? 'T' : '-');

echo $info; // -rw-r--r--

Quand l'utiliser ?

• Audit — journaliser ou signaler les permissions des répertoires d'upload, des fichiers de configuration ou des dossiers de cache.
• Diagnostics — confirmer qu'un script de déploiement a bien défini 0755/0644 plutôt que de supposer.
• Corrections conditionnelles — lire le mode actuel et, s'il est trop permissif, le restreindre avec chmod().

Pièges et conseils

• Masquez toujours avec & 0777 (ou découpez la chaîne) avant de comparer à un littéral comme 0644 — sinon les bits de type font échouer toute comparaison.
• Les résultats sont mis en cache. PHP met en cache les données stat ; si vous modifiez les permissions et les relisez dans la même requête, appelez d'abord clearstatcache().
• Retourne false en cas d'erreur, pas 0. Des permissions à 0 sont techniquement valides, donc testez avec === si vous devez distinguer un vrai mode 0 d'un échec.
• Windows est limité. Les bits d'exécution et de groupe/autres ne sont pas significatifs sur Windows, donc la valeur ne reflète que ce que cette plateforme expose.
• Pour l'ensemble complet des métadonnées d'un fichier (taille, propriétaire, horodatages) en un seul appel, utilisez stat() ; filetype() retourne uniquement le type sous forme de mot comme file ou dir.

Conclusion

fileperms() retourne le mode de fichier Unix complet sous forme d'entier, combinant le type de fichier avec les bits d'accès. Convertissez-le en octal avec sprintf('%o', ...), pensez à masquer avec & 0777 (ou prenez les derniers chiffres) pour isoler les bits de permission, et associez-le à chmod() lorsque vous devez modifier ces permissions plutôt que simplement les lire.

Pratique