rewinddir()

Lorsque vous lisez un répertoire en PHP, un pointeur interne suit votre progression. Une fois arrivé à la fin, ce pointeur reste en place — appelez à nouveau readdir() et vous obtenez false sans aucune entrée. rewinddir() ramène le pointeur à la première entrée afin de pouvoir relire le répertoire une seconde fois sans le rouvrir. Cette page explique ce que fait la fonction, sa syntaxe, un exemple fonctionnel multi-passes, les erreurs courantes, et quand l'utiliser (ou non).

Syntaxe

rewinddir(?resource $dir_handle = null): void

• $dir_handle — un handle de répertoire précédemment retourné par opendir(). Si omis, PHP utilise le handle du dernier appel à opendir().
• Valeur de retour — rewinddir() retourne void (dans les anciennes versions de PHP, null). Elle ne signale pas le succès ou l'échec ; si vous passez un handle invalide, PHP lève une TypeError ou un avertissement.

Elle est presque toujours utilisée conjointement avec opendir(), readdir() et closedir().

Fonctionnement de rewinddir()

Un handle de répertoire se comporte comme un curseur sur les entrées du répertoire. readdir() avance ce curseur d'une entrée par appel et retourne false lorsqu'il n'y en a plus. rewinddir() repositionne simplement le curseur au début, de sorte que le prochain appel à readdir() reparte de la première entrée.

Lire un répertoire deux fois

Il s'agit du cas d'utilisation canonique : lister un répertoire, puis le lister à nouveau avec le même handle. Notez que readdir($h) ne retourne aucune entrée lors du second passage tant que rewinddir() n'a pas été appelée.

<?php
$h = opendir(__DIR__);
if ($h === false) {
    die("Failed to open directory\n");
}

echo "First pass:\n";
while (($file = readdir($h)) !== false) {
    echo "  $file\n";
}

// Without rewinddir(), this loop would print nothing.
rewinddir($h);

echo "Second pass:\n";
while (($file = readdir($h)) !== false) {
    echo "  $file\n";
}

closedir($h);
?>

Les deux passages affichent le même ensemble d'entrées (y compris les pseudo-répertoires . et .. que readdir() retourne toujours).

Un piège courant : la vérification stricte de false

Comparez toujours le résultat de readdir() avec !== false, et non avec != ou un test de véracité. Un répertoire peut légitimement contenir une entrée nommée "0", qui est fausse en PHP — une vérification souple arrêterait la boucle prématurément et ignorerait silencieusement des fichiers.

<?php
// Wrong: stops as soon as it hits a file named "0" (or an empty name)
while ($file = readdir($h)) { /* ... */ }

// Correct: only stops at the genuine end of the stream
while (($file = readdir($h)) !== false) { /* ... */ }
?>

Quand utiliser rewinddir() — et quand ne pas le faire

Utilisez rewinddir() lorsque vous avez besoin de plus d'un passage sur le même handle ouvert, par exemple pour calculer un total lors du premier passage (compter des fichiers, additionner des tailles) et agir sur chaque entrée lors du second. C'est moins coûteux qu'appeler closedir() puis opendir() à nouveau, car cela évite de rouvrir le descripteur de fichier sous-jacent.

Si vous n'avez besoin des entrées qu'une seule fois, ou si vous les voulez triées, préférez scandir(), qui retourne l'intégralité du listing sous forme de tableau en un seul appel — sans pointeur à gérer. Pour un aperçu de toutes les fonctions de répertoire, consultez le chapitre PHP Directory.

Conclusion

rewinddir() réinitialise le pointeur interne d'un flux de répertoire au début, vous permettant de relire le répertoire sans la surcharge de fermeture et de réouverture du handle. Associée à opendir(), readdir() et closedir(), elle rend le parcours multi-passes de répertoire simple et efficace. Préférez scandir() lorsqu'un seul listing trié est tout ce dont vous avez besoin.

graph TD
    A[opendir] --> B[readdir]
    B --> C{More items?}
    C -->|Yes| B
    C -->|No| D[rewinddir]
    D --> B
    B --> E[closedir]

Pratique