is_file()

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

is_file() é uma função nativa do PHP que informa se um caminho aponta para um arquivo regular — um arquivo comum no disco, diferente de um diretório, do tipo alvo de um link simbólico ou de um arquivo especial (pipe, socket ou nó de dispositivo). Ela retorna true apenas para arquivos regulares e false para todo o resto, incluindo caminhos que não existem.

Esta é a função ideal para usar antes de tentar ler, incluir ou processar um arquivo, quando "este caminho aponta realmente para um arquivo com o qual posso trabalhar?" importa mais do que "este caminho existe?".

Sintaxe

is_file(string $filename): bool

• $filename — o caminho a verificar. Pode ser relativo (resolvido em relação ao diretório de trabalho atual) ou absoluto.
• Valor de retorno — true se $filename existir e for um arquivo regular, false caso contrário. Nenhum aviso é emitido quando o arquivo está ausente; você simplesmente obtém false.

Exemplo Básico

Usar __FILE__ (o caminho absoluto do script atual) garante que a verificação seja aprovada, então o script imprime uma mensagem confirmando que o caminho é um arquivo regular. Substitua por qualquer outro caminho — um caminho inexistente ou um diretório retorna false.

is_file() vs file_exists() vs is_dir()

Essas três funções se sobrepõem, e escolher a errada é uma fonte comum de bugs:

A armadilha principal: file_exists('/some/folder') é true para um diretório. Se você então tentar usar fopen() ou include como se fosse um arquivo, obterá um erro. Use is_file() sempre que o próximo passo pressupõe um arquivo real:

<?php

$path = sys_get_temp_dir(); // a directory that definitely exists

var_dump(file_exists($path)); // bool(true)  — it exists
var_dump(is_file($path));     // bool(false) — but it is NOT a file
var_dump(is_dir($path));      // bool(true)  — it is a directory

Protegendo a Leitura de um Arquivo

Um uso típico no mundo real: confirmar que o caminho é um arquivo utilizável antes de lê-lo. Combinar is_file() com is_readable() evita falhas de "não é um arquivo" e de "sem permissão":

<?php

$path = __FILE__;

if (is_file($path) && is_readable($path)) {
    echo "Safe to read: " . basename($path);
} else {
    echo "Cannot read that path.";
}

Isso imprime uma saída no estilo Safe to read: is-file.mdx (o basename do script em execução) e encerra de forma limpa se o caminho for um diretório, estiver ausente ou não for legível.

A armadilha do cache de stat

O PHP armazena em cache os resultados de verificações de sistema de arquivos como is_file() durante a duração de uma requisição para evitar acessos repetidos ao disco. Se um arquivo for criado ou excluído após o PHP já ter verificado o mesmo caminho, uma segunda chamada a is_file() pode retornar o resultado em cache, que está desatualizado. Quando você precisa de um resultado atualizado — por exemplo, em um script de longa duração que cria um arquivo e o verifica imediatamente — limpe o cache primeiro:

<?php

clearstatcache();          // discard cached stat results
var_dump(is_file($path));  // now reflects the current state on disk

Armadilhas Comuns

• Não é uma verificação de segurança. Um caminho pode passar em is_file() e ainda ser ilegível ou não gravável. Combine-a com is_readable() ou is_writable() antes de agir.
• Links simbólicos são seguidos. is_file() verifica o alvo de um symlink, não o próprio link. Um symlink apontando para um arquivo regular retorna true.
• Sem aviso para caminhos inexistentes. Diferentemente de abrir um arquivo, um caminho inexistente simplesmente retorna false, portanto is_file() é segura de chamar sem suprimir erros.

Conclusão

is_file() responde a uma pergunta precisa — "isto é um arquivo regular?" — e é a verificação ideal a colocar antes de qualquer código que leia, inclua ou processe um arquivo. Use file_exists() quando um diretório também seria aceitável, is_dir() quando você quer especificamente uma pasta, e combine is_file() com as verificações de legibilidade acima quando as permissões forem relevantes.

Prática