filetype()

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

filetype() é uma função nativa do PHP que indica que tipo de entrada do sistema de arquivos um caminho aponta — um arquivo comum, um diretório, um link simbólico, entre outros. Ela recebe um único caminho e retorna o tipo como uma string em minúsculas, ou false em caso de falha.

Isso é útil quando você percorre um diretório e precisa tratar arquivos e subdiretórios de forma diferente, quando valida que um upload chegou onde era esperado, ou quando precisa ignorar entradas especiais (pipes, arquivos de dispositivo) que não devem ser lidos como arquivos comuns.

Veja a sintaxe:

A sintaxe PHP de filetype()

filetype(string $filename): string|false

Onde $filename é um caminho relativo ou absoluto para a entrada que você deseja inspecionar.

Valores de Retorno

filetype() retorna uma das seguintes strings:

Se o caminho não existir ou não puder ser lido, filetype() retorna false e emite um E_WARNING. Como false é comparado como igual à string vazia em uma comparação solta, sempre verifique o resultado com === antes de confiar nele.

Como Usar a Função filetype()?

Passe um caminho e inspecione a string retornada:

Uso básico

<?php

$path = __FILE__;          // the path of the currently running script
$type = filetype($path);

echo "The entry '$path' is of type: $type";
// e.g. The entry '/var/www/index.php' is of type: file

Usar __FILE__ garante que o caminho existe, então o exemplo funciona em qualquer lugar sem configuração prévia.

Tratando o Retorno false

Como filetype() retorna false para um caminho inexistente ou ilegível, proteja a chamada antes de usar o resultado. Verificar com file_exists() primeiro evita o aviso completamente:

Consulta segura

<?php

$path = '/path/that/does/not/exist';

if (!file_exists($path)) {
    echo "Path not found.";
} else {
    $type = filetype($path);
    echo $type === false
        ? "Could not determine the type."
        : "Type: $type";
}
// Path not found.

Distinguindo Arquivos de Diretórios em Iterações

Uma tarefa real comum é iterar um diretório e agir apenas sobre arquivos ou apenas sobre subdiretórios. filetype() torna a ramificação explícita:

Classificar entradas do diretório

<?php

$dir = sys_get_temp_dir();          // a directory that always exists

foreach (scandir($dir) as $entry) {
    if ($entry === '.' || $entry === '..') {
        continue;                   // skip the self/parent references
    }

    $full = $dir . DIRECTORY_SEPARATOR . $entry;
    echo $entry . ' => ' . filetype($full) . PHP_EOL;
}

Aqui scandir() lista o conteúdo do diretório e filetype() classifica cada entrada. Para uma travessia de nível mais baixo, você pode usar readdir() com opendir().

filetype() vs. is_file() e is_dir()

Quando você só precisa de uma resposta sim/não para um tipo específico, as funções de predicado dedicadas são mais claras e não exigem uma comparação de string:

• is_file() — true se o caminho for um arquivo comum.
• is_dir() — true se o caminho for um diretório.

Use filetype() quando precisar distinguir entre vários tipos possíveis em um único lugar (por exemplo, para ignorar FIFOs e sockets), e use is_file() / is_dir() quando uma única verificação booleana for mais legível.

Cuidado com o Cache de Stat

O PHP armazena em cache os resultados das funções do sistema de arquivos durante a duração de uma requisição, portanto, se um caminho for criado, excluído ou substituído após a primeira verificação, filetype() pode retornar um valor desatualizado. Chame clearstatcache() para forçar uma nova consulta. Note também que filetype() segue links simbólicos da mesma forma que stat() — para detectar o próprio link, use lstat().

Conclusão

filetype() retorna o tipo de uma entrada do sistema de arquivos como uma string (file, dir, link, entre outros) e false em caso de falha. Proteja o resultado com ===, verifique o caminho com file_exists() para evitar avisos, e lembre-se de clearstatcache() ao verificar novamente um caminho que foi alterado durante a requisição. Para verificações simples de um único tipo, prefira is_file() e is_dir(); para o conjunto completo de estatísticas de arquivo em uma única chamada, consulte stat().

Prática