rmdir()

Introdução

Em PHP, a função rmdir() é usada para remover um diretório. É uma função útil para gerenciar o seu sistema de arquivos. Neste artigo, abordaremos tudo o que você precisa saber sobre a função rmdir(), incluindo sua sintaxe, parâmetros e exemplos de uso.

Entendendo a Função rmdir()

A função rmdir() remove um diretório do sistema de arquivos. Há uma regra importante a lembrar: rmdir() só exclui diretórios vazios. Se o diretório ainda contiver arquivos ou subdiretórios, a chamada falha e o PHP emite um E_WARNING.

Isso é proposital — evita que você apague uma árvore inteira com uma única chamada equivocada. Para excluir um diretório que possui conteúdo, você deve remover o conteúdo primeiro (veja o Exemplo 2 abaixo).

Outras situações que fazem rmdir() falhar e retornar false:

• O caminho não existe ou é um arquivo em vez de um diretório.
• O usuário do script não possui permissão de escrita/execução no diretório pai.
• Em alguns sistemas, o diretório é o diretório de trabalho atual do processo ou está em uso de alguma forma.

Funções relacionadas que você frequentemente usará junto com rmdir(): mkdir() para criar diretórios, is_dir() para verificar se um caminho é um diretório, scandir() para listar seu conteúdo, e unlink() para excluir os arquivos individuais dentro dele.

Sintaxe da Função rmdir()

rmdir(string $directory, ?resource $context = null): bool

A função retorna true em caso de sucesso e false em caso de falha.

Nota sobre cache: O PHP armazena em cache os resultados das verificações de status de arquivos. Após criar ou excluir diretórios em um loop apertado, chame clearstatcache() antes de retestar o mesmo caminho com is_dir() ou file_exists(), caso contrário você pode ler um resultado desatualizado.

Exemplos de Uso do rmdir()

Exemplo 1: Removendo um Diretório

Este exemplo verifica se o caminho existe com is_dir() antes de tentar removê-lo, e relata se a chamada foi bem-sucedida:

<?php

$directory = 'example_directory';

if (is_dir($directory)) {
    if (rmdir($directory)) {
        echo "Directory removed successfully.";
    } else {
        echo "Failed to remove directory. It may not be empty or lack permissions.";
    }
} else {
    echo "Directory does not exist.";
}

Se example_directory existir e estiver vazio, isso imprime Directory removed successfully. Usar is_dir() como guarda permite evitar o aviso que rmdir() emitiria para um caminho inexistente.

Exemplo 2: Removendo um Diretório Não Vazio

Como rmdir() se recusa a excluir um diretório que ainda possui conteúdo, você deve esvaziá-lo primeiro. A solução idiomática é um auxiliar recursivo que percorre a árvore, aplica unlink() em cada arquivo e recursa em cada subdiretório antes de finalmente chamar rmdir() no diretório agora vazio:

<?php

function removeDirectory($dir) {
    if (!is_dir($dir)) {
        return false;
    }
    $files = array_diff(scandir($dir), ['.', '..']);
    foreach ($files as $file) {
        $path = $dir . DIRECTORY_SEPARATOR . $file;
        is_dir($path) ? removeDirectory($path) : unlink($path);
    }
    return rmdir($dir);
}

removeDirectory('example_directory');

Aqui array_diff(scandir($dir), ['.', '..']) remove as entradas especiais . e .. retornadas por scandir(), e DIRECTORY_SEPARATOR constrói caminhos que funcionam tanto no Windows quanto em sistemas Unix. A função retorna o resultado do rmdir() final, para que você possa verificar o sucesso.

Dica: A exclusão recursiva é destrutiva e não tem desfazer. Valide o caminho antes de chamá-la (por exemplo, rejeite uma string vazia ou a raiz do sistema de arquivos) para que um bug não possa apagar mais do que o pretendido.

Erros Comuns e Armadilhas

• Tentar remover um diretório não vazio. Esta é a causa mais frequente de falha. Esvazie o diretório primeiro ou use o auxiliar recursivo acima.
• Ignorar o valor de retorno. rmdir() retorna false em vez de lançar exceção para a maioria das falhas (emite um aviso). Sempre verifique o resultado boolean no código que importa.
• Suprimir o aviso com @. @rmdir($dir) oculta a mensagem, mas não a falha. Prefira verificar is_dir() e o valor de retorno.
• Esquecer as permissões. Excluir um diretório requer permissão de escrita e execução no seu pai, não no diretório em si.

Conclusão

A função rmdir() fornece uma maneira direta de remover diretórios vazios em PHP. Para excluir um diretório que possui conteúdo, limpe-o primeiro — tipicamente com um auxiliar recursivo que combina scandir() e unlink(). Sempre verifique o valor de retorno e proteja exclusões recursivas destrutivas com uma verificação de caminho.

Para ir mais longe, explore as funções de diretório complementares: mkdir(), is_dir(), scandir() e rename().

Prática