file_exists()

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

A função file_exists() é uma função nativa do PHP que verifica se um determinado caminho aponta para um arquivo ou um diretório no sistema de arquivos. É uma das formas mais comuns de proteger operações com arquivos — você a chama antes de ler, escrever ou excluir para que seu script não falhe em caminhos inexistentes.

Ela retorna:

• true se o caminho existir (seja um arquivo regular, um diretório, um link simbólico ou qualquer outro arquivo especial), ou
• false se nada existir naquele caminho, ou se você não tiver permissão para ler as informações sobre ele.

Sintaxe

file_exists(string $filename): bool

$filename é o caminho a ser verificado. Pode ser:

• um caminho relativo ('data/users.csv'), resolvido em relação ao diretório de trabalho atual, ou
• um caminho absoluto ('/var/www/uploads/logo.png' ou 'C:\\temp\\file.txt' no Windows).

Um Exemplo Básico

Se myfile.txt estiver presente no diretório de trabalho do script, o primeiro bloco é executado; caso contrário, o bloco else é executado. Como file_exists() retorna um boolean simples, você pode usá-la diretamente em qualquer expressão if, && ou ternária.

Atenção ao Cache de Stat

O PHP armazena em cache o resultado das verificações do sistema de arquivos (incluindo file_exists()) para evitar acessos repetidos ao disco. Dentro de uma única execução de script, se você verificar um caminho, depois criar ou excluir o arquivo e verificar novamente, poderá ainda ver a resposta antiga.

Chame clearstatcache() para forçar uma nova consulta:

<?php

$path = 'temp.txt';

file_put_contents($path, 'hello');      // create the file
clearstatcache();                       // forget the cached result
var_dump(file_exists($path));           // bool(true)

unlink($path);                          // delete the file
clearstatcache();
var_dump(file_exists($path));           // bool(false)

Esse armazenamento em cache é importante em scripts de longa duração e em laços que criam ou removem arquivos dinamicamente.

file_exists() vs. is_file() vs. is_dir()

file_exists() não pode dizer que tipo de coisa existe — apenas que algo existe. Quando você precisa saber especificamente, use uma função mais precisa:

Um erro comum é usar file_exists() para confirmar que um caminho é um arquivo antes de abri-lo. Se um diretório tiver o mesmo nome, file_exists() retornará true, mas fopen() falhará. Prefira is_file() nesse caso.

Casos de Uso Comuns

Proteger uma leitura para nunca lançar um aviso:

<?php

$config = 'config.php';

if (is_file($config)) {
    require $config;
} else {
    die('Configuration file is missing.');
}

Evitar sobrescrever um upload existente adicionando um sufixo numérico:

<?php

$target = 'upload.png';
$i = 1;

while (file_exists($target)) {
    $target = "upload-$i.png";
    $i++;
}

echo "Saving to: $target";

Excluir um arquivo somente se ele existir, para que unlink() não avise sobre um caminho inexistente:

<?php

$tmp = 'cache.tmp';

if (file_exists($tmp)) {
    unlink($tmp);
}

Pontos a Ter em Mente

• Condições de corrida. Um arquivo pode ser criado ou removido por outro processo entre a verificação com file_exists() e a operação que se segue. Para escritas críticas, geralmente é mais seguro tentar a operação e tratar o erro do que verificar antes.
• Permissões. Se o diretório que contém o arquivo não estiver acessível ao processo PHP, file_exists() retornará false mesmo que o arquivo exista fisicamente.
• URLs remotas. Com a configuração correta, file_exists() pode funcionar com alguns wrappers de stream, mas não verifica URLs http:// de forma confiável — use uma função como file_get_contents() com tratamento de erros.

Para se aprofundar na leitura e escrita de arquivos, veja o capítulo Manipulação de Arquivos PHP.

Prática