scandir()

Introduction

La gestion des répertoires est une partie essentielle de la programmation PHP — presque chaque script de sauvegarde, téléchargeur de fichiers ou processeur de ressources doit lister le contenu d'un dossier. Cet article explore en profondeur la fonction PHP scandir(), qui lit le contenu d'un répertoire en un seul appel. Vous apprendrez ce qu'elle retourne, comment trier et filtrer le résultat, en quoi elle diffère de glob(), et comment gérer les erreurs en toute sécurité.

Qu'est-ce que scandir ?

scandir() lit un répertoire et retourne les noms de toutes les entrées qu'il contient — fichiers et sous-répertoires — sous forme d'un tableau plat de chaînes de caractères. Le tableau inclut toujours les deux entrées spéciales . (le répertoire courant) et .. (le répertoire parent), que vous devrez presque toujours filtrer avant d'utiliser le résultat.

Si le répertoire ne peut pas être lu, scandir() retourne false et émet un avertissement. La fonction est disponible depuis PHP 4.3.0 et fonctionne sur les systèmes Unix et Windows.

Syntaxe

scandir(string $directory, int $sorting_order = SCANDIR_SORT_ASCENDING, ?resource $context = null): array|false

La fonction retourne un tableau de noms de fichiers en cas de succès, ou false en cas d'échec.

Les noms sont retournés sans le chemin du répertoire. Pour obtenir un chemin utilisable, préfixez le répertoire vous-même : $directory . '/' . $entry.

Comment fonctionne scandir ?

Dans sa forme la plus simple, vous passez uniquement le chemin du répertoire. Le contenu est retourné trié par ordre alphabétique (croissant) car c'est le $sorting_order par défaut. L'exemple ci-dessous filtre . et .. avec array_diff() afin que seules les vraies entrées restent :

Exemple de la fonction scandir() en PHP

<?php

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

// Filter out the current and parent directory entries
$filtered = array_diff($files, ['.', '..']);

foreach ($filtered as $file) {
    echo $file . "<br>";
}

Ce code affiche une liste de fichiers et de sous-répertoires dans le répertoire spécifié, en excluant . et ...

Trier le contenu du répertoire

Passez un second argument pour contrôler l'ordre du résultat. Les trois options sont :

• SCANDIR_SORT_ASCENDING — alphabétique A→Z (valeur par défaut).
• SCANDIR_SORT_DESCENDING — alphabétique Z→A.
• SCANDIR_SORT_NONE — aucun tri ; les entrées sont retournées dans l'ordre fourni par le système de fichiers. C'est l'option la plus rapide, utile lorsque vous allez trier la liste vous-même, ou lorsque l'ordre n'a pas d'importance.

Par exemple, pour un répertoire contenant archive.txt, data.csv, report.txt, notes.md, image.png et un sous-répertoire backups :

Comment trier la sortie de scandir() par ordre décroissant

<?php

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

print_r($files);
// Array
// (
//     [0] => report.txt
//     [1] => notes.md
//     [2] => image.png
//     [3] => data.csv
//     [4] => backups
//     [5] => ..
//     [6] => .
// )

Les mêmes données avec SCANDIR_SORT_NONE sont retournées sans tri (l'ordre exact dépend du système de fichiers), ce qui évite le léger surcoût du tri.

Lister uniquement les fichiers (ou uniquement les répertoires)

scandir() retourne les fichiers et les dossiers mélangés. Pour ne conserver que les fichiers, testez chaque entrée avec is_file() ; pour ne conserver que les répertoires, utilisez is_dir(). Pensez à construire le chemin complet en premier :

<?php

$dir = "/path/to/directory";
$entries = array_diff(scandir($dir), ['.', '..']);

$filesOnly = array_filter($entries, fn($entry) => is_file($dir . '/' . $entry));

print_r(array_values($filesOnly));
// Array
// (
//     [0] => archive.txt
//     [1] => data.csv
//     [2] => image.png
//     [3] => notes.md
//     [4] => report.txt
// )

Filtrer par extension de fichier

Une tâche courante consiste à récupérer uniquement les fichiers d'un type donné. Combinez scandir() avec pathinfo() pour lire l'extension de chaque entrée :

<?php

$dir = "/path/to/directory";
$entries = array_diff(scandir($dir), ['.', '..']);

$textFiles = array_filter(
    $entries,
    fn($entry) => pathinfo($entry, PATHINFO_EXTENSION) === 'txt'
);

print_r(array_values($textFiles));
// Array
// (
//     [0] => archive.txt
//     [1] => report.txt
// )

Si vous avez seulement besoin de faire correspondre des fichiers par un motif, glob() peut le faire en une étape — par exemple glob("$dir/*.txt") — et retourne les chemins complets. Utilisez glob() pour la correspondance de motifs et scandir() lorsque vous voulez toutes les entrées et un contrôle total sur le filtrage.

Gestion des erreurs

La fonction scandir peut échouer si le chemin du répertoire spécifié est invalide ou si le répertoire ne dispose pas des permissions appropriées. En cas d'échec, elle retourne false et déclenche un avertissement. Elle ne lève pas d'exceptions, vous devez donc vérifier directement la valeur de retour. Voici un exemple :

Exemple de la fonction scandir() en PHP avec gestion des erreurs

<?php

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

if ($files === false) {
    echo "Error: Could not read the directory.";
} else {
    foreach ($files as $file) {
        echo $file . "<br>";
    }
}

Ce code vérifie la valeur de retour de scandir() et affiche un message d'erreur si le répertoire ne peut pas être lu. Comme scandir() émet un avertissement (et non une exception) en cas d'échec, la vérification stricte === false est ce qui protège réellement votre code — et la suppression de l'avertissement avec @scandir() est déconseillée, car vous perdez le message de diagnostic.

Pour éviter complètement l'avertissement, confirmez que le chemin est un répertoire lisible avant d'appeler scandir() :

<?php

$dir = "/path/to/directory";

if (is_dir($dir)) {
    $files = scandir($dir);

    foreach (array_diff($files, ['.', '..']) as $file) {
        echo $file . "<br>";
    }
} else {
    echo "Error: '$dir' is not a valid directory.";
}

scandir() vs autres fonctions de répertoire

Pour un aperçu de l'ensemble des outils disponibles, consultez Travailler avec les répertoires en PHP.

Conclusion

La fonction scandir() est un moyen pratique et simple de lire le contenu d'un répertoire en PHP en un seul appel. Vous avez vu comment lister les entrées, les trier avec les trois constantes SCANDIR_SORT_*, ne conserver que les fichiers ou uniquement les répertoires, filtrer par extension et gérer les échecs en toute sécurité. Utilisez scandir() lorsque vous voulez la liste complète et un contrôle total ; utilisez glob() lorsqu'une simple correspondance de motif suffit.

Pratique