is_uploaded_file()

A função is_uploaded_file() verifica se um determinado arquivo foi enviado por meio de uma requisição HTTP POST. É uma das principais ferramentas de segurança do PHP para uploads de arquivos: permite confirmar que um caminho realmente aponta para um arquivo temporário criado pelo próprio PHP a partir da requisição atual — e não para um caminho arbitrário que um invasor possa ter inserido no seu script.

Este capítulo abrange a sintaxe, um exemplo funcional, o problema de segurança que a função resolve e os erros comuns que pegam as pessoas de surpresa.

Sintaxe

is_uploaded_file(string $filename): bool

• $filename — o caminho a ser verificado. Na prática, esse valor sempre vem de $_FILES['...']['tmp_name'].
• Valor de retorno — true se $filename for um arquivo enviado da requisição atual, false caso contrário.

A função só retorna true para o nome de arquivo temporário atribuído pelo PHP durante o upload. Passar um caminho que você mesmo construiu (por exemplo, o destino final após mover o arquivo) retorna false.

Exemplo básico

<?php

$file = $_FILES['file']['tmp_name'];

if (is_uploaded_file($file)) {
    echo 'The file was uploaded via HTTP POST.';
} else {
    echo 'The file was NOT uploaded via HTTP POST.';
}

Aqui, $_FILES['file'] é a entrada criada quando um campo de formulário chamado file é enviado com enctype="multipart/form-data". A chave tmp_name contém o caminho temporário no servidor, e is_uploaded_file() verifica se ele realmente veio da requisição.

Por que a função existe (segurança)

Sem essa verificação, um invasor poderia enviar um campo de formulário comum (não um arquivo) cujo valor é um caminho do servidor, como /etc/passwd. Se o seu código confiasse cegamente nessa string e depois a lesse ou copiasse, você exporia arquivos do sistema. is_uploaded_file() protege contra isso retornando true apenas para arquivos que o próprio PHP recebeu como uploads na requisição atual.

Um manipulador de upload seguro valida o arquivo antes de fazer qualquer coisa com ele:

<?php

if (
    isset($_FILES['file']) &&
    $_FILES['file']['error'] === UPLOAD_ERR_OK &&
    is_uploaded_file($_FILES['file']['tmp_name'])
) {
    $destination = __DIR__ . '/uploads/' . basename($_FILES['file']['name']);

    if (move_uploaded_file($_FILES['file']['tmp_name'], $destination)) {
        echo 'File stored safely.';
    } else {
        echo 'Failed to move the uploaded file.';
    }
} else {
    echo 'No valid upload received.';
}

Observe que move_uploaded_file() realiza internamente a mesma verificação de is_uploaded_file(), portanto é a forma preferida de mover um upload. Use is_uploaded_file() diretamente apenas quando precisar inspecionar ou ler o arquivo temporário antes de movê-lo.

is_uploaded_file() vs. move_uploaded_file()

Erros comuns

• Sempre passe tmp_name, nunca o caminho final. Após mover um arquivo com move_uploaded_file(), o arquivo temporário deixa de existir, então verificá-lo novamente retorna false.
• A verificação é por requisição. Um caminho que era um upload em uma requisição anterior não é válido na atual.
• Não valida o conteúdo. is_uploaded_file() não informa nada sobre o tipo ou tamanho do arquivo. Valide $_FILES['file']['size'], o tipo MIME e a extensão separadamente antes de confiar nos dados do usuário.
• Verifique o código de erro primeiro. Inspecione $_FILES['file']['error'] === UPLOAD_ERR_OK antes de chamar is_uploaded_file(); um upload com falha pode deixar tmp_name vazio.

Funções relacionadas

• move_uploaded_file() — mover com segurança um arquivo enviado para o seu destino.
• $_FILES e outras superglobais — como os dados do arquivo enviado são expostos ao seu script.
• Upload de Arquivos PHP — o formulário HTML completo mais o manipulador PHP para aceitar arquivos.

Resumo

is_uploaded_file() retorna true apenas para o arquivo temporário criado pelo PHP a partir de um upload via HTTP POST na requisição atual. Combinada com o código de erro do upload e a validação do conteúdo, é a base do tratamento seguro de arquivos em PHP. Na maioria dos casos, você deixa move_uploaded_file() fazer a verificação por você, e recorre a is_uploaded_file() diretamente apenas quando precisa ler o arquivo temporário antes de movê-lo.

Prática