dir()

Introduction

Ce chapitre explique comment travailler avec les répertoires en PHP : les ouvrir, les lire, les créer et les supprimer, ainsi que la fonction dir() désormais supprimée et ses remplaçants modernes. PHP intègre un ensemble complet de fonctions natives pour ces tâches, ce qui vous permet de lister le contenu d'un dossier, de parcourir une arborescence de répertoires ou de nettoyer des fichiers sans faire appel au système d'exploitation.

Vous aurez le plus souvent besoin de fonctions de répertoire lors de la création d'un gestionnaire de téléchargement, de la génération d'une liste de fichiers pour une page de téléchargement, du nettoyage de fichiers temporaires ou de l'analyse d'un dossier de modèles ou d'images au moment de l'exécution.

Comprendre les fonctions de répertoire en PHP

PHP regroupe les opérations sur les répertoires dans quelques fonctions procédurales, ainsi qu'une classe orientée objet DirectoryIterator. Les plus courantes sont :

• opendir() — ouvre un répertoire et retourne un handle (une ressource depuis laquelle vous lisez)
• readdir() — lit l'entrée suivante depuis un handle de répertoire ouvert
• closedir() — ferme un handle de répertoire et libère la ressource
• scandir() — lit toutes les entrées dans un array en un seul appel
• glob() — retourne les chemins correspondant à un motif de caractères génériques shell
• mkdir() — crée un nouveau répertoire
• rmdir() — supprime un répertoire vide
• is_dir() — vérifie si un chemin est un répertoire

Chaque liste de répertoires en PHP inclut les entrées spéciales . (le répertoire lui-même) et .. (son parent). Vous voudrez presque toujours les ignorer — oublier de le faire est une source courante de bogues.

Utiliser opendir() et readdir() pour lire un répertoire

opendir() ouvre un répertoire et retourne un handle de répertoire. Vous passez ensuite ce handle à readdir(), qui retourne le nom de l'entrée suivante à chaque appel, et false quand il n'y a plus d'entrées. Fermez toujours le handle avec closedir() lorsque vous avez terminé.

Comme readdir() peut légitimement retourner "0" (un fichier littéralement nommé 0), comparez son résultat avec !== false plutôt qu'une vérification souple, afin qu'un nom de fichier faux ne soit pas pris pour la fin de la liste.

Exemple de opendir() et readdir() en PHP

<?php

$dir = "/path/to/directory";
if (is_dir($dir)) {
    if ($dh = opendir($dir)) {
        while (($file = readdir($dh)) !== false) {
            if ($file === "." || $file === "..") {
                continue; // skip self and parent
            }
            echo "filename: " . $file . PHP_EOL;
        }
        closedir($dh);
    }
}

Pour un répertoire contenant a.txt, b.log et report.csv, cela affiche :

filename: b.log
filename: report.csv
filename: a.txt

L'ordre n'est pas alphabétique — readdir() retourne les entrées dans l'ordre où le système de fichiers les stocke. Si vous avez besoin d'un ordre prévisible, utilisez scandir() (qui trie) ou triez les résultats vous-même.

Utiliser scandir() pour lister un répertoire en une seule fois

scandir() lit l'intégralité du contenu d'un répertoire dans un array en un seul appel, et — contrairement à readdir() — il trie le résultat alphabétiquement par défaut. C'est la façon la plus pratique d'obtenir une liste triée de fichiers. Il inclut toujours . et .., donc filtrez-les lorsque vous ne voulez que les vrais fichiers.

Utilisation de la fonction scandir() en PHP

<?php

$dir = "/path/to/directory";
$files = scandir($dir);
print_r($files);

Pour un répertoire contenant a.txt, b.log et report.csv, la sortie est :

Array
(
    [0] => .
    [1] => ..
    [2] => a.txt
    [3] => b.log
    [4] => report.csv
)

Passez SCANDIR_SORT_DESCENDING comme troisième argument pour inverser l'ordre, ou SCANDIR_SORT_NONE pour ignorer le tri (ce qui est plus rapide pour les très grands répertoires).

Filtrer des fichiers avec glob()

Lorsque vous ne voulez que les fichiers correspondant à un motif — tous les fichiers .txt, ou tout ce qui commence par report — glob() est l'option la plus claire. Elle accepte un motif de caractères génériques shell et retourne un array de chemins correspondants :

<?php

foreach (glob("/path/to/directory/*.txt") as $file) {
    echo $file . PHP_EOL;
}

Si seul a.txt correspond dans notre exemple de répertoire, cela affiche :

/path/to/directory/a.txt

Contrairement à scandir(), glob() n'inclut pas . et .., et retourne des chemins complets plutôt que de simples noms de fichiers.

Créer des répertoires avec mkdir()

La fonction mkdir() crée un nouveau répertoire. Son premier argument est le chemin, le second définit les permissions (une valeur octale comme 0755), et le troisième argument optionnel, lorsqu'il vaut true, crée récursivement tous les répertoires parents manquants.

Utilisation de la fonction mkdir() en PHP

mkdir("/path/to/my/new/directory", 0755, true);

Sans le drapeau true, mkdir() échoue avec un avertissement si un répertoire parent n'existe pas encore. Sur les systèmes de type Unix, les permissions réelles sont également affectées par le umask du processus.

Supprimer des répertoires avec rmdir()

La fonction rmdir() supprime un répertoire. Elle prend le chemin du répertoire que vous souhaitez supprimer.

Utilisation de la fonction rmdir() en PHP

rmdir("/path/to/my/new/directory");

Remarque : rmdir() ne supprime que les répertoires vides. Pour supprimer un répertoire qui contient encore des fichiers, supprimez d'abord les fichiers (et les sous-répertoires) — par exemple en itérant le contenu avec scandir() et en appelant unlink() sur chaque fichier.

Le remplaçant moderne : DirectoryIterator

Pour le code orienté objet, la classe SPL DirectoryIterator est la méthode recommandée pour parcourir un répertoire. Elle est itérable avec foreach et vous fournit des informations complètes sur chaque entrée — son nom, sa taille, son type et sa date de modification — sans appels de fonctions séparés :

<?php

foreach (new DirectoryIterator("/path/to/directory") as $entry) {
    if ($entry->isDot()) {
        continue; // skip "." and ".."
    }
    echo $entry->getFilename() . PHP_EOL;
}

Pour un répertoire contenant a.txt, b.log et report.csv, cela affiche :

b.log
report.csv
a.txt

isDot() ignore pratiquement . et .. en une seule vérification. Pour parcourir une arborescence de répertoires entière, y compris les sous-dossiers, utilisez RecursiveDirectoryIterator avec RecursiveIteratorIterator.

La fonction dir() héritée

Déprécié : La fonction dir() a été dépréciée dans PHP 7.4 et supprimée dans PHP 8.0. Utilisez DirectoryIterator ou scandir() à la place. L'exemple ci-dessous est fourni uniquement pour la maintenance de code ancien.

La fonction dir() retourne un objet Directory qui fournit une manière orientée objet de lire le contenu d'un répertoire. Contrairement à scandir(), qui retourne un simple array, dir() retourne un object avec des méthodes comme read(), rewind() et close(). Notez que dir() n'est pas un alias de scandir() — elles servent des objectifs différents et retournent des types de données différents.

Utilisation de la fonction dir() en PHP (héritage)

<?php
$dir = dir("/path/to/directory");
while (($file = $dir->read()) !== false) {
    echo "filename: " . $file . PHP_EOL;
}
$dir->close();

Conclusion

PHP offre plusieurs façons de travailler avec les répertoires. Utilisez scandir() ou glob() pour des listes rapides et triées, le trio opendir()/readdir()/closedir() lorsque vous souhaitez diffuser les entrées une par une, et DirectoryIterator pour une traversée orientée objet propre. Créez et supprimez des dossiers avec mkdir() et rmdir(), et faites appel à RecursiveDirectoryIterator lorsque vous devez descendre dans des sous-répertoires. Pour une vue plus large du travail avec le système de fichiers, consultez les chapitres PHP Directory et PHP Filesystem.

Pratique