move_uploaded_file()

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

A função move_uploaded_file() é uma função PHP embutida que move um arquivo enviado por meio de um formulário HTML para um local permanente no servidor. Quando um navegador faz o upload de um arquivo, o PHP primeiro o armazena em um diretório temporário com um nome aleatório. Esse arquivo temporário é excluído automaticamente quando o script termina, então você deve movê-lo para um local permanente se quiser mantê-lo — é exatamente para isso que serve o move_uploaded_file().

O que torna essa função especial é sua verificação de segurança embutida. Ela só move um arquivo se o PHP confirmar que o arquivo foi genuinamente enviado via uma requisição HTTP POST. Isso impede que um invasor engane o seu script para mover um arquivo sensível do servidor (como /etc/passwd) fornecendo seu caminho. Por esse motivo, você deve sempre usar move_uploaded_file() em vez de copy() ou rename() para lidar com uploads.

Esta página cobre a sintaxe, os parâmetros, o valor de retorno, um exemplo funcional completo, os códigos de erro de upload que você deve verificar e as armadilhas de segurança a observar.

Sintaxe

move_uploaded_file(string $from, string $to): bool

Valor de retorno

move_uploaded_file() retorna true se o arquivo foi movido com sucesso. Retorna false se $from não for um arquivo enviado válido (por exemplo, se o caminho foi forjado) ou se a movimentação em si falhar — geralmente por um diretório de destino inexistente ou permissões de escrita insuficientes. No caso de arquivo forjado, o PHP também emite um aviso e nenhuma movimentação é realizada.

Como Usar a Função move_uploaded_file()?

Usar a função move_uploaded_file() é simples. Aqui estão os passos a seguir:

1. Verifique se o upload do arquivo foi bem-sucedido verificando $_FILES['file']['error'].
2. Especifique o caminho de destino para o arquivo.
3. Chame a função move_uploaded_file(), passando o nome de arquivo temporário e o caminho de destino.

Aqui está um trecho de código de exemplo que demonstra como usar a função move_uploaded_file():

Como Usar a Função move_uploaded_file()?

<?php

if ($_FILES['file']['error'] === UPLOAD_ERR_OK) {
    $uploaded_file = $_FILES['file']['tmp_name'];
    $destination_path = '/path/to/new/location/' . basename($_FILES['file']['name']);
    if (move_uploaded_file($uploaded_file, $destination_path)) {
        echo "File uploaded successfully!";
    } else {
        echo "Error uploading file.";
    }
} else {
    echo "File upload failed.";
}

Neste exemplo, primeiro verificamos que o upload foi bem-sucedido usando $_FILES['file']['error']. Em seguida, especificamos o caminho de destino para o arquivo e usamos basename() para extrair o nome do arquivo com segurança e evitar vulnerabilidades de path traversal. Por fim, usamos a função move_uploaded_file() para mover o arquivo enviado para o novo local. Se o arquivo for movido com sucesso, exibimos uma mensagem de êxito. Se houver um erro ao mover o arquivo, exibimos uma mensagem de erro.

O formulário HTML correspondente deve usar method="post" e enctype="multipart/form-data", caso contrário $_FILES estará vazio:

<form action="upload.php" method="post" enctype="multipart/form-data">
    <input type="file" name="file">
    <input type="submit" value="Upload">
</form>

O atributo name do input de arquivo (file aqui) é a chave que você lê de $_FILES.

Códigos de Erro de Upload

O valor de $_FILES['file']['error'] informa se e por que um upload falhou. Sempre verifique antes de mover o arquivo. Os códigos mais comuns são:

Duas configurações do servidor frequentemente causam falhas silenciosas: upload_max_filesize e post_max_size. Se o arquivo enviado for maior do que qualquer um desses limites, $_FILES pode chegar vazio ou com um código de erro, independentemente de quão correto seja o seu código PHP.

Notas de Segurança

• Nunca confie no nome de arquivo original. Use basename() em $_FILES['file']['name'], ou melhor ainda, gere seu próprio nome seguro, para evitar path traversal como ../../config.php.
• Valide o tipo de arquivo pelo seu conteúdo real (por exemplo com finfo / mime_content_type), não apenas pela extensão — o cliente pode mentir tanto sobre a extensão quanto sobre o campo type.
• Armazene uploads fora da raiz web quando possível, para que os usuários não possam executar scripts enviados diretamente.
• Para uma verificação explícita de que um caminho é realmente um arquivo enviado, consulte is_uploaded_file() — embora move_uploaded_file() já realize essa verificação internamente.

Conclusão

A função move_uploaded_file() é a maneira correta e segura de mover um arquivo enviado via HTTP POST do diretório temporário do PHP para um local permanente. Ela retorna true em caso de sucesso e false em caso de falha, e se recusa a mover qualquer coisa que não tenha sido genuinamente enviada. Sempre verifique o código de erro do upload primeiro, sanitize o nome do arquivo de destino e valide o arquivo antes de confiar nele.

Para o fluxo de trabalho mais amplo sobre o tratamento de uploads, consulte PHP File Upload e o restante de PHP File Handling.

Prática