is_dir()

O que é a Função is_dir()?

A função is_dir() é uma função PHP integrada que informa se um determinado caminho existe e aponta para um diretório (pasta). Ela retorna true quando o caminho é um diretório existente e false para tudo o mais — um arquivo regular, um caminho que não existe ou um caminho para o qual você não tem permissão de leitura.

É uma das funções de "verificação de tipo" do sistema de arquivos do PHP, ao lado de is_file(), is_link() e file_exists(). Use is_dir() sempre que precisar confirmar que um diretório está lá antes de lê-lo, escrever nele ou criá-lo.

Sintaxe

is_dir(string $filename): bool

• $filename — o caminho a ser testado. Pode ser absoluto (/var/www/uploads) ou relativo ao diretório de trabalho atual do script (uploads). Uma barra final é permitida.
• Valor de retorno — true se $filename existir e for um diretório, caso contrário false.

Exemplo Básico

__DIR__ é uma constante mágica que sempre resolve para um diretório existente, portanto este exemplo imprime de forma confiável o ramo "is a directory".

Distinguindo um Diretório de um Arquivo

O uso mais comum de is_dir() é ramificar com base no que um caminho realmente é. Compare com is_file():

<?php

$paths = [__DIR__, __FILE__, '/path/that/does/not/exist'];

foreach ($paths as $path) {
    if (is_dir($path)) {
        echo "$path -> directory\n";
    } elseif (is_file($path)) {
        echo "$path -> file\n";
    } else {
        echo "$path -> missing\n";
    }
}

__FILE__ é o caminho completo do script atual, portanto é reportado como arquivo, enquanto o caminho inventado é reportado como ausente.

Um Uso Prático: Criar o Diretório Somente se Estiver Ausente

Proteger mkdir() com is_dir() evita um aviso quando a pasta já existe:

<?php

$dir = sys_get_temp_dir() . '/my_app_cache';

if (!is_dir($dir)) {
    mkdir($dir, 0755, true); // true = create parent dirs too
    echo "Created: $dir";
} else {
    echo "Already exists: $dir";
}

Erros Comuns

• is_dir() retorna false, não um erro, quando o caminho não existe. Um resultado false não significa "isso é um arquivo" — pode simplesmente estar ausente. Use file_exists() se você só se importa que algo esteja lá.
• Links simbólicos são seguidos. Se o caminho for um symlink que aponta para um diretório, is_dir() retorna true. Para detectar o próprio link, use is_link().
• Os resultados são armazenados em cache. O PHP armazena em cache os resultados de stat(), portanto, se um diretório for criado ou excluído por outro processo durante a execução do script, você poderá ver uma resposta desatualizada. Chame clearstatcache() para forçar uma verificação atualizada.
• Caminhos relativos dependem do diretório de trabalho. is_dir('data') é resolvido em relação ao diretório de trabalho atual (getcwd()), não à localização do script. Use __DIR__ . '/data' quando quiser dizer "ao lado deste script."

Funções Relacionadas

Conclusão

is_dir() é a maneira segura e padrão de confirmar que um caminho é um diretório existente antes de agir sobre ele. Lembre-se de que ela segue symlinks, armazena em cache seu resultado e resolve caminhos relativos em relação ao diretório de trabalho atual — combiná-la com file_exists(), is_file() e mkdir() cobre praticamente todas as situações de manipulação de diretórios que você encontrará.

Prática