Répertoires PHP

PHP intègre un ensemble de fonctions de répertoire qui permettent à vos scripts d'inspecter, de créer, de lire et de supprimer des dossiers sur le système de fichiers du serveur — sans faire appel au système d'exploitation. Cette page explique ce que fait chaque fonction principale, quand l'utiliser et les erreurs courantes à éviter.

Cette page est un complément à PHP File Handling et à la référence plus complète de PHP Filesystem : les fichiers se trouvent à l'intérieur des répertoires, donc les deux sujets sont presque toujours utilisés ensemble.

Pourquoi les opérations sur les répertoires sont importantes

Presque toute application non triviale touche au système de fichiers. Vous avez besoin des fonctions de répertoire pour :

• Organiser les fichiers téléversés — trier les fichiers des utilisateurs dans des dossiers par utilisateur ou par date (voir PHP File Upload).
• Créer une structure de projet à la volée — générer des dossiers de cache, de logs ou d'export la première fois qu'ils sont nécessaires.
• Parcourir le contenu — lister chaque template, image ou fichier de données dans un dossier pour les traiter en lot.
• Nettoyer — supprimer les répertoires temporaires une fois une tâche terminée.

Ces fonctions faisant partie du cœur de PHP, elles fonctionnent de la même manière sur Linux, macOS et Windows (/ est accepté comme séparateur partout), ce qui les rend plus portables que l'exécution de mkdir ou ls via exec().

Fonctions principales de répertoire

scandir() vs. opendir()

Ces deux fonctions listent le contenu d'un répertoire, mais elles conviennent à des besoins différents :

• scandir() charge toutes les entrées dans un tableau en une seule fois. C'est concis et facile à trier, mais utilise une mémoire proportionnelle au nombre de fichiers. Idéal pour les dossiers de petite à moyenne taille.
• opendir() / readdir() diffuse les entrées une par une. La mémoire reste constante même pour des répertoires contenant des dizaines de milliers de fichiers. Idéal pour les très grands dossiers.

Les deux incluent les entrées spéciales . (courant) et .. (parent) — vous voudrez presque toujours les ignorer.

Exemple : créer un répertoire et le lister

Ce script vérifie si un répertoire existe, le crée (ainsi que les dossiers parents manquants) s'il n'existe pas, puis affiche son contenu :

<?php
$dir = 'uploads/images';

// Create the directory and any missing parents if it doesn't exist
if (!is_dir($dir)) {
    mkdir($dir, 0755, true);
    echo "Directory created: $dir\n";
}

// List directory contents, skipping the . and .. entries
$files = scandir($dir);
echo "Contents of $dir:\n";
foreach ($files as $file) {
    if ($file !== '.' && $file !== '..') {
        echo "- $file\n";
    }
}
?>

Le troisième argument de mkdir() (true) est le drapeau récursif : sans lui, mkdir('uploads/images') échoue si uploads n'existe pas déjà. 0755 est un mode de permission octal (le propriétaire peut lire/écrire/exécuter, les autres peuvent lire/exécuter) et est ignoré sous Windows.

Exemple : diffusion avec opendir()

Pour les grands répertoires, lisez les entrées une par une au lieu de construire un tableau complet :

<?php
$dir = __DIR__;

if ($handle = opendir($dir)) {
    while (($entry = readdir($handle)) !== false) {
        if ($entry !== '.' && $entry !== '..') {
            $type = is_dir("$dir/$entry") ? 'dir ' : 'file';
            echo "[$type] $entry\n";
        }
    }
    closedir($handle);
}
?>

Notez la comparaison stricte !== false : un fichier littéralement nommé "0" est falsy, donc une boucle while ($entry = readdir(...)) s'arrêterait prématurément. Comparez toujours explicitement avec false.

Supprimer des répertoires

rmdir() ne supprime qu'un répertoire vide. Pour en supprimer un qui contient encore des fichiers, supprimez d'abord le contenu — généralement avec un helper récursif :

<?php
function removeDir(string $dir): void {
    foreach (scandir($dir) as $entry) {
        if ($entry === '.' || $entry === '..') {
            continue;
        }
        $path = "$dir/$entry";
        is_dir($path) ? removeDir($path) : unlink($path);
    }
    rmdir($dir);
}
?>

Cette fonction parcourt chaque entrée, entre récursivement dans les sous-répertoires et appelle unlink() sur les fichiers, de sorte que le répertoire est vide au moment où rmdir() s'exécute.

Pièges courants

• mkdir() sans le drapeau récursif échoue si un dossier parent est manquant. Passez true lors de la création de chemins imbriqués.
• Les permissions sont soustraites par umask — le mode réel est $mode & ~umask(), donc 0777 peut donner 0755.
• rmdir() sur un dossier non vide retourne false et émet un avertissement. Videz-le d'abord.
• scandir() inclut . et .. — filtrez-les avant de traiter le contenu.
• Les chemins relatifs dépendent de getcwd(), qui est le répertoire de travail du script, pas l'emplacement du fichier. Utilisez __DIR__ pour ancrer les chemins au fichier courant.

Flux de travail des répertoires en un coup d'œil

graph TD
A[Check Directory] --> B{Exists?}
B -->|No| C[mkdir]
B -->|Yes| D[scandir / opendir]
C --> E[Create Subdirectories]
D --> F[Read Entries]
F --> G[Process Files]
G --> H[close / rmdir]

Résumé

Les fonctions de répertoire de PHP offrent un moyen portable et intégré de gérer les dossiers : mkdir() et rmdir() les créent et les suppriment, is_dir() les vérifie, et scandir() ou opendir()/readdir() en liste le contenu. Utilisez scandir() sur les petits dossiers pour sa simplicité, et la diffusion opendir() sur les grands pour maintenir la mémoire constante. Combinez ces fonctions avec les fonctions de fichiers PHP et la gestion des fichiers pour créer des fonctionnalités robustes d'upload, de cache et d'export.

Pratique