unlink()

Introdução

A função PHP unlink() exclui um único arquivo do sistema de arquivos. O nome vem da chamada de sistema Unix unlink, que remove um nome (um "link") que aponta para os dados de um arquivo. Quando o último link para um arquivo é removido, o próprio arquivo é liberado.

Este capítulo aborda a sintaxe, o valor de retorno, as regras de permissão e — igualmente importante — os pontos de atenção: avisos silenciados, exclusão somente quando o arquivo existe e por que o unlink() não pode remover diretórios.

Sintaxe

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

Parâmetros

• $filename — o caminho para o arquivo a ser excluído. Pode ser relativo ao diretório de trabalho atual ou um caminho absoluto.
• $context (opcional) — um recurso de contexto de stream, usado em casos avançados como exclusão por meio de um wrapper de stream (por exemplo, FTP). Você raramente precisará disso.

Valor de retorno

• true se o arquivo foi excluído com sucesso.
• false se houve falha — por exemplo, o arquivo não existe, o caminho aponta para um diretório ou o processo não tem permissão. Em caso de falha, o PHP também emite um E_WARNING.

unlink() é o equivalente oposto às funções que criam arquivos, como fopen() e file_put_contents().

Um exemplo básico

Sempre verifique o valor de retorno para que seu script saiba se a exclusão realmente aconteceu:

<?php
// Create a file so we have something to delete.
file_put_contents('example.txt', 'temporary data');

if (unlink('example.txt')) {
    echo "File deleted successfully.";
} else {
    echo "Failed to delete the file.";
}

Saída:

File deleted successfully.

Excluir somente se o arquivo existir

Chamar unlink() em um arquivo inexistente retorna false e gera um aviso. Proteja a chamada com file_exists() (ou is_file()) para evitar avisos desnecessários:

<?php
$path = 'cache/report.tmp';

if (file_exists($path)) {
    unlink($path);
    echo "Removed: {$path}";
} else {
    echo "Nothing to remove.";
}

Se cache/report.tmp não existir, isso imprime Nothing to remove. em vez de disparar um aviso.

Tratando falhas de forma limpa

Em produção, muitas vezes você quer reagir a uma exclusão com falha em vez de travar. O operador @ suprime o aviso, mas uma abordagem mais limpa é verificar o resultado e reportá-lo você mesmo:

<?php
$path = 'logs/old.log';

if (!@unlink($path)) {
    // file_exists() distinguishes "already gone" from a real permission error.
    if (file_exists($path)) {
        echo "Could not delete {$path} — check permissions.";
    } else {
        echo "File was already gone.";
    }
}

Permissões: quem pode excluir um arquivo

Uma surpresa comum: a permissão para excluir um arquivo é controlada pelo diretório, não pelo arquivo. Para remover um arquivo, o processo PHP (por exemplo, o usuário do servidor web como www-data) precisa de permissão de escrita e execução no diretório que o contém — mesmo que o próprio arquivo seja somente leitura. Se você receber erros de "permissão negada", inspecione as permissões do diretório pai, não apenas as do arquivo.

Excluindo muitos arquivos

unlink() remove um arquivo por vez. Para excluir vários arquivos que correspondem a um padrão, combine-o com glob():

<?php
// Delete every .tmp file in the cache directory.
foreach (glob('cache/*.tmp') as $file) {
    unlink($file);
}

glob() retorna um array de caminhos correspondentes (ou um array vazio se nenhum corresponder), então o loop simplesmente não faz nada quando não há nada a excluir.

unlink() vs rmdir()

unlink() só funciona em arquivos. Se você passar um diretório para ele, ele falha e emite um aviso. Para remover um diretório, use rmdir() — e note que rmdir() só funciona em um diretório vazio. Remover um diretório não vazio significa excluir seu conteúdo primeiro (com unlink() para arquivos e rmdir() para subdiretórios), depois remover o diretório em si.

Pontos de atenção comuns

• O arquivo deve existir. Um arquivo ausente retorna false e gera aviso. Verifique com file_exists() primeiro.
• É permanente. unlink() não move o arquivo para uma lixeira; os dados são apagados imediatamente.
• Não serve para diretórios. Use rmdir() para diretórios.
• Cache de stat. Após excluir um arquivo, o PHP pode ainda informar que ele existe por causa do cache de stat. Chame clearstatcache() se você verificar o mesmo caminho novamente em um loop apertado.
• Handles de arquivo abertos. No Windows, você não pode excluir um arquivo que ainda está aberto; feche-o com fclose() primeiro. No Unix, a exclusão é permitida, mas os dados permanecem até que o último handle seja fechado.

Conclusão

unlink() é a forma direta do PHP de excluir um único arquivo, retornando true em caso de sucesso e false (mais um aviso) em caso de falha. As práticas principais são: verificar se o arquivo existe antes de excluir, sempre inspecionar o valor de retorno, lembrar que a permissão de exclusão depende do diretório e recorrer a rmdir() quando precisar remover diretórios. Para uma visão mais ampla sobre leitura, escrita e gerenciamento de arquivos, consulte PHP File Handling.

Prática