Verificar se o ficheiro existe em PHP

Use file_exists() do PHP para verificar se um caminho corresponde, naquele momento, a um ficheiro ou diretório existente. A função devolve um valor booleano, pelo que pode escolher o que fazer com base no resultado. A verificação descreve o caminho nesse instante; não garante que uma operação posterior com o ficheiro seja bem-sucedida.

Verificar se um caminho existe com file_exists()

Passe o caminho como uma cadeia de caracteres. Este exemplo autónomo cria um ficheiro temporário, verifica se existe e elimina-o em seguida. Assim, o ramo de sucesso não depende de já existir um ficheiro no projeto.

Execute este exemplo:

O código e os rótulos ou saídas exibidos nesta seção permanecem em inglês.

$directory = sys_get_temp_dir() . DIRECTORY_SEPARATOR . 'file-exists-' . uniqid('', true);
mkdir($directory);
$file = $directory . DIRECTORY_SEPARATOR . 'example.txt';
file_put_contents($file, 'Ready');

if (file_exists($file)) {
    echo "File is ready.\n";
} else {
    echo "File was not found.\n";
}

unlink($file);
rmdir($directory);

Este exemplo é apresentado sem afirmar qual será o resultado, pois o pacote não contém evidências de execução. No seu código, use o mesmo padrão condicional com o caminho que pretende verificar. Um resultado true significa que o caminho existe; false significa que o PHP não o encontrou no momento da verificação.

Distinguir ficheiros de diretórios

file_exists() também devolve true para um diretório. Se o passo seguinte exigir especificamente um diretório, verifique-o com is_dir(); para um ficheiro normal, use is_file(). Estas verificações respondem a perguntas diferentes: saber que um caminho existe não permite determinar o seu tipo.

O código e os rótulos ou saídas exibidos nesta seção permanecem em inglês.

$path = __DIR__ . DIRECTORY_SEPARATOR . 'uploads';

if (is_dir($path)) {
    echo 'The path is a directory.';
} elseif (is_file($path)) {
    echo 'The path is a file.';
} else {
    echo 'No file or directory was found at this path.';
}

O caminho é construído a partir de __DIR__, que corresponde ao diretório que contém o ficheiro PHP atual. Altere o último componente do caminho para indicar a localização que a sua aplicação precisa de verificar.

Gerir caminhos e resultados de forma segura

Um caminho relativo é interpretado no contexto do processo PHP em execução, pelo que a mesma cadeia pode identificar locais diferentes consoante o diretório de trabalho. Um caminho absoluto começa na raiz do sistema de ficheiros e torna explícita a localização pretendida. Se um caminho relativo produzir um resultado inesperado, inspecione o caminho que o PHP está a usar — por exemplo, combine-o com getcwd() para diagnosticar o problema — ou construa-o a partir de um diretório conhecido, como __DIR__.

Use a verificação para escolher um passo seguinte adequado, mas tenha em conta que a própria operação pode falhar. O caminho pode mudar depois da verificação, e a sua existência não prova que o processo o possa ler, alterar ou utilizar de outra forma. Verifique também o resultado da operação propriamente dita e trate eventuais falhas de acordo com a aplicação.

Limitações comuns e resolução de problemas

Se file_exists() devolver false inesperadamente, confirme a grafia e a construção do caminho e, em seguida, verifique se aponta para a localização pretendida no ambiente do processo PHP. Considere também se o caminho mudou entre verificações ou se o processo em execução consegue inspecionar a localização relevante no sistema de ficheiros. A função informa se o caminho existe; não identifica a causa de um resultado falso.

O manual do PHP descreve file_exists() como uma verificação da existência de um ficheiro ou diretório e observa que o resultado depende do contexto do sistema de ficheiros configurado. Não a trate como uma verificação da disponibilidade de um recurso remoto: use o mecanismo adequado ao protocolo ou serviço desse recurso. Consulte o manual do PHP sobre file_exists() para obter informações sobre o parâmetro, o valor devolvido e outras notas da função.

Se precisar de fazer verificações repetidas, não parta do princípio de que um resultado anterior continua válido. Sempre que possível, execute diretamente a operação pretendida e trate o respetivo resultado. Assim, o programa continua correto mesmo que o sistema de ficheiros mude entre a verificação e a operação.