delete()

Como deletar um arquivo em PHP com unlink()

PHP não possui uma função delete(). Para deletar um arquivo no sistema de arquivos, usa-se unlink() — o nome vem da chamada de sistema Unix subjacente, que remove o nome de um arquivo (seu "link") de um diretório. Quando o último link é removido, os dados do arquivo são liberados.

Esta página aborda o que unlink() faz, os problemas comuns (arquivos inexistentes, permissões, caminhos relativos) e as funções relacionadas usadas quando unlink() não é a ferramenta certa — como rmdir() para diretórios e glob() para deletar vários arquivos de uma vez.

Deletar um arquivo (unlink()) não é o mesmo que deletar registros de banco de dados — para isso, executa-se uma consulta SQL DELETE, não uma chamada ao sistema de arquivos.

Sintaxe

unlink(string $filename, ?resource $context = null): bool

• $filename — o caminho para o arquivo que se deseja deletar. Pode ser absoluto (/var/www/data.txt) ou relativo ao diretório de trabalho do script (uploads/data.txt).
• $context — (opcional) um contexto de stream, usado apenas com wrappers de stream como ftp://. Raramente necessário para arquivos locais.

unlink() retorna true em caso de sucesso e false em caso de falha. Em caso de falha, também emite um E_WARNING — por exemplo, quando o arquivo não existe ou o processo não tem permissão para removê-lo.

Sempre verifique o resultado

Um simples unlink("file.txt") deixa silenciosamente um aviso nos logs se o arquivo estiver ausente. Verifique o valor de retorno e, quando o arquivo pode não existir, use file_exists() para evitar um aviso:

$path = "report.txt";

if (file_exists($path)) {
    if (unlink($path)) {
        echo "Deleted $path\n";
    } else {
        echo "Could not delete $path (check permissions)\n";
    }
} else {
    echo "Nothing to delete: $path does not exist\n";
}

Exemplos

Exemplo 1: Criar um arquivo e depois deletá-lo

Este exemplo autocontido cria um arquivo temporário, confirma que ele existe, deleta-o com unlink() e confirma que foi removido:

$path = sys_get_temp_dir() . "/w3docs-demo.txt";

file_put_contents($path, "temporary data");
echo "Exists before delete? " . (file_exists($path) ? "yes" : "no") . "\n";

unlink($path);
echo "Exists after delete?  " . (file_exists($path) ? "yes" : "no") . "\n";

Saída:

Exists before delete? yes
Exists after delete?  no

Exemplo 2: Deletar todos os arquivos correspondentes com glob()

unlink() deleta um arquivo por chamada, portanto, para limpar um conjunto de arquivos, combine-o com glob(), que retorna um array de caminhos correspondentes:

foreach (glob("/tmp/cache/*.tmp") as $file) {
    unlink($file);
}

Isso remove todos os arquivos .tmp em /tmp/cache. O mesmo padrão é a forma padrão de "esvaziar" um diretório de arquivos antes de removê-lo com rmdir() (que só funciona em diretórios vazios).

Exemplo 3: Deletar um arquivo por meio de um wrapper de stream

unlink() funciona com wrappers de stream, incluindo os remotos. O $context opcional permite passar opções específicas do wrapper:

$context = stream_context_create([
    'ftp' => ['overwrite' => true],
]);

unlink("ftp://example.com/old-export.txt", $context);

Armadilhas comuns

• O arquivo não existe. unlink() retorna false e emite um aviso. Use file_exists() ou suprima e verifique: @unlink($path).
• Permissões. A exclusão depende da permissão de escrita no diretório pai, não no arquivo em si. O processo PHP (geralmente www-data) precisa ter propriedade ou acesso de escrita nesse diretório.
• Caminhos relativos. Um caminho relativo é resolvido em relação ao diretório de trabalho atual, que nem sempre é a pasta do script. Prefira caminhos absolutos ou construa-os com __DIR__.
• É um diretório. unlink() não pode remover diretórios — use rmdir() para um diretório vazio e delete seu conteúdo primeiro.
• O arquivo está aberto. No Windows, deletar um arquivo ainda aberto por um handle falha; feche-o primeiro. No Unix, o unlink tem sucesso, mas os dados permanecem até que o handle seja fechado.

Funções relacionadas

• rmdir() — remove um diretório vazio.
• file_exists() — verifica se um caminho existe antes de deletar.
• rename() — move ou renomeia um arquivo em vez de deletá-lo.
• copy() — copia um arquivo antes de sobrescrevê-lo ou remover o original.
• glob() — lista arquivos que correspondem a um padrão e os deleta em um loop.

Conclusão

Use unlink() para deletar um único arquivo, sempre verifique seu valor de retorno e use file_exists() quando o arquivo pode estar ausente. Para diretórios, recorra a rmdir(), e para exclusões em lote, combine unlink() com glob().

Prática