rewinddir()

Quando você lê um diretório em PHP, um ponteiro interno rastreia até onde você chegou. Ao atingir o fim, esse ponteiro permanece lá — chame readdir() novamente e você obterá false sem nenhuma entrada. rewinddir() move o ponteiro de volta para a primeira entrada, permitindo que você leia o diretório uma segunda vez sem reabri-lo. Esta página aborda o que a função faz, sua sintaxe, um exemplo funcional de múltiplas passagens, armadilhas comuns e quando (e quando não) utilizá-la.

Sintaxe

rewinddir(?resource $dir_handle = null): void

• $dir_handle — um handle de diretório previamente retornado por opendir(). Se omitido, o PHP usa o handle da chamada opendir() mais recente.
• Valor de retorno — rewinddir() retorna void (em versões mais antigas do PHP, null). Não sinaliza sucesso ou falha; se você passar um handle inválido, o PHP lança um TypeError ou aviso.

Ela é quase sempre usada em conjunto com opendir(), readdir() e closedir().

Como o rewinddir() funciona

Um handle de diretório se comporta como um cursor sobre as entradas do diretório. readdir() avança esse cursor uma entrada por chamada e retorna false quando se esgota. rewinddir() simplesmente reposiciona o cursor no início, de modo que a próxima chamada a readdir() comece novamente a partir da primeira entrada.

Lendo um diretório duas vezes

Este é o caso de uso canônico: listar um diretório e depois listá-lo novamente a partir do mesmo handle. Observe como readdir($h) não retorna entradas na segunda passagem até que rewinddir() seja chamado.

<?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);
?>

Ambas as passagens imprimem o mesmo conjunto de entradas (incluindo os pseudodiretórios . e .. que readdir() sempre retorna).

Uma armadilha comum: a verificação estrita com false

Sempre compare o resultado de readdir() com !== false, não apenas com != ou um teste de veracidade. Um diretório pode legitimamente conter uma entrada chamada "0", que é falsa em PHP — uma verificação solta interromperia o loop prematuramente e ignoraria arquivos silenciosamente.

<?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) { /* ... */ }
?>

Quando usar rewinddir() — e quando não usar

Use rewinddir() quando precisar de mais de uma passagem sobre o mesmo handle aberto, por exemplo, para calcular um total na primeira passagem (contar arquivos, somar tamanhos) e agir sobre cada entrada na segunda. É mais barato do que chamar closedir() e opendir() novamente, pois evita reabrir o descritor de arquivo subjacente.

Se você precisar das entradas apenas uma vez, ou se quiser que estejam ordenadas, prefira scandir(), que retorna toda a listagem como um array em uma única chamada — sem ponteiro para gerenciar. Para uma visão geral de todas as funções de diretório, veja o capítulo PHP Directory.

Conclusão

rewinddir() redefine o ponteiro interno de um stream de diretório ao início, permitindo que você releia o diretório sem o custo de fechar e reabrir o handle. Em conjunto com opendir(), readdir() e closedir(), torna a travessia de diretório em múltiplas passagens simples e eficiente. Recorra a scandir() quando uma única listagem ordenada for tudo o que você precisa.

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

Prática