Objetivo

O objetivo deste tutorial é mostrar como realizar o upload de arquivos em PHP de forma simples e eficiente. Você aprenderá como criar um formulário de upload de arquivos em HTML, processar o upload de arquivos em um script PHP e lidar com possíveis erros e problemas que possam surgir durante o processo. Ao final deste tutorial, você terá os conhecimentos necessários para implementar o upload de arquivos em seus próprios projetos PHP.

Definições

O upload de arquivos é uma funcionalidade essencial em muitos sites e aplicativos web. Seja para permitir que os usuários enviem documentos, imagens, vídeos ou outros tipos de arquivos.

Saber como fazer upload de arquivos de forma eficaz e segura é fundamental para o desenvolvimento web. Neste tutorial, vamos explorar o processo de upload de arquivos em PHP, passo a passo, para que você possa implementar essa funcionalidade em seus projetos com confiança.

1. Configuração do ambiente de desenvolvimento PHP

1.1. No seu servidor web ou servidor local, verifique se a extensão file_uploads está habilitada no php.ini para permitir o upload de arquivos.

1.1.1. Em um servidor web, o arquivo php.ini está localizado no diretório principal (raiz) do sistema de arquivos onde o seu site está hospedado.

1.1.2. Em um servidor local, como o WAMP, por exemplo, encontre o arquivo php.ini na pasta de configuração do próprio WAMP. Você pode acessar essa pasta através da interface do WAMP, clicando no ícone do WAMP na barra de tarefas e navegando até "PHP" > "php.ini".

1.1.3. Abra o arquivo php.ini em um editor de texto e localize a linha que contém a extensão file_uploads. Certifique-se de que essa linha não esteja comentada (não tenha um ponto-e-vírgula no início). Se a extensão estiver desativada Off, altere para On :

file_uploads = On

2. Cria uma pasta onde os arquivos serão enviados

2.1. Crie uma pasta no seu servidor onde os arquivos enviados serão armazenados. No nosso exemplo criamos a pasta denominada de "arquivos" que fica na pasta "upload".

2.1.1. Observe que, para este exemplo, também criamos os documentos index.php e upload.php.

2.1.1.1. No arquivo index.php criaremos o formulário HTML responsável por enviar os arquivos desejados para o servidor na pasta "arquivos".

2.1.1.2. No arquivo upload.php, trataremos o processo de upload dos arquivos.

2.1.2. Se a pasta "arquivos" estiver hospedada em um servidor web, certifique-se de que a pasta tenha permissão de escrita (chmod 755 ou chmod 777 dependendo do ambiente desejado).

 3. Crie um formulário HTML para enviar arquivos para o servidor

3.1. No arquivo index.php, desenvolva um formulário HTML que permita o envio de arquivos para o servidor.

3.1.1. Veja no exemplo abaixo onde criamos um formulário na página index.php para enviar arquivos para o servidor de acordo com os processo que serão definidos no arquivo upload.php.

index.php

<form action="upload.php" method="POST" enctype="multipart/form-data">
    <label>Arquivo que será enviado: <input type="file" name="arquivo"></label>
    <input type="submit" value="Enviar">
</form>

Observações:

3.1.1.1. O parâmetro action em um formulário HTML especifica para onde os dados devem ser enviado. Ele define o URL do script PHP que processará os dados do formulário do lado do servidor, que no nosso exemplo é o arquivo "upload.php".

3.1.1.2. O método especificado no formulário (method="post") determina como os dados são enviados (no caso, usando o método POST, que é o mais usual em formulários).

3.1.1.3. O atributo enctype="multipart/form-data" é usado em formulários HTML quando você deseja permitir o envio de arquivos binários, como imagens, vídeos, arquivos PDF, etc. Este atributo é essencial quando você está criando um formulário que inclui um campo de upload de arquivo (<input type="file">).

3.1.1.4. O atributo type="file" é usado em um elemento <input> em formulários HTML para criar um campo de seleção de arquivo. Esse campo permite que os usuários selecionem um arquivo em seus dispositivos para ser enviado para o servidor quando o formulário for submetido.

Obs.: Quando você usa type="file" em um <input>, é necessário incluir o atributo enctype="multipart/form-data" no formulário para que os arquivos possam ser enviados corretamente.

Variável Superglobal $_FILES

3.2. No formulário, é importante entender que, por padrão, ao enviar um arquivo via PHP é gerado automaticamente um arquivo temporário na memória do servidor. Além disso, diversas informações sobre o arquivo enviado são adicionadas à variável superglobal do PHP, $_FILES.

3.2.1. A variável super global $_FILES em PHP é usada para acessar informações sobre arquivos enviados para o servidor em um formulário HTML com um campo <input type="file">, usando o método POST e enctype="multipart/form-data". Ela é um array associativo que contém várias informações sobre o arquivo, como nome, tipo, tamanho, localização temporária no servidor, e um código de erro (se houver algum problema com o envio).

3.2.1.1. No nosso formulário, onde enviamos o arquivo de exemplo eltrônica.jpg, a estrutura da variável  $_FILES fica desta forma:

Array
(
    [arquivo] => Array
        (
            [name] => eletrônica.jpg
            [type] => image/jpeg
            [tmp_name] => /tmp/phpArsn5B
            [error] => 0
            [size] => 30611
        )

)

 3.2.1.2. Onde:

'arquivo': É o nome do campo <input> de arquivo no formulário HTML.

'name': É o nome original do arquivo que foi enviado pelo cliente. No nosso exemplo enviamos o arquivo eletrônica.jpg

'type': É o tipo MIME do arquivo, ou seja o tipo de arquivo (imagem, texto, pdf, etc). No nosso exemplo temos um arquivo de imagem jpg.

'tmp_name': É o caminho temporário no servidor onde o arquivo foi armazenado temporariamente após o envio.

'error': É um código que representa se ocorreu algum erro durante o envio do arquivo. Se não houver erro, o valor é UPLOAD_ERR_OK. Quando não existe erro, o valor é "0".

'size': É o tamanho do arquivo em bytes.

3.2.1.3. Portanto, ao acessar $_FILES['arquivo']['name'], você obtém o nome original do arquivo enviado no campo de formulário HTML do nosso exemplo (<input type="file" name="arquivo">) chamado de "arquivo". Para saber o local onde o arquivo temporário foi armazenado no servidor após o envio, utilize $_FILES['arquivo']['tmp_name'].

4. Crie o arquivo PHP para realizar o processamento do envio

4.1. Agora que o formulário de envio está no arquivo index.php, vamos criar o arquivo upload.php responsável por processar os dados recebidos no servidor.

upload.php

if (isset($_FILES["arquivo"]) && $_FILES["arquivo"]["error"] == 0) {        
    if (move_uploaded_file($_FILES['arquivo']['tmp_name'], 'arquivos/'.$_FILES['arquivo']['name']) === FALSE) {        
        echo "Desculpe, ocorreu um erro ao enviar seu arquivo.";
    } else {
        echo 'Arquivo <b>' . $_FILES['arquivo']['name'] . '</b> enviado com sucesso.';
    }    
} else {
    echo "Desculpe, ocorreu um erro ao enviar seu arquivo.";
}

4.2. A variável global $_FILES em PHP, como já vimos, é usada para acessar informações sobre arquivos enviados para o servidor em um formulário HTML com um campo <input type="file">. Como já mostramos anteriormente, ela é um array associativo que contém várias informações sobre o arquivo, como nome, tipo, tamanho, localização temporária no servidor, e um código de erro (se houver algum problema com o envio).

 4.4. Pronto, com esse sistema simples podemos enviar qualquer tipo de arquivo para o servidor. Para verificar se o arquivo enviado foi salvo com sucesso, verifique na pasta "arquivos".

5. Validações e Filtros

5.1. O código PHP desenvolvido no arquivo upload.php do exemplo anterior verifica apenas se o arquivo foi enviado e se houve erros durante o envio. Podemos verificar também outros eventos, como:

a) Verificar se o arquivo já existe (evitar duplicidade).

b) Verificar o tamanho do arquivo. Desta forma, você poderá filtrar arquivos definindo um limite de tamanho máximo.

c) Filtrar tipos MIME de arquivo, ou seja por formatos de arquivo (imagens, textos, pdf, etc). Para conhecer todos os tipos MIME de arquivos acesse: Lista de tipos MIME (Exemplo: extensão PDF - tipo MIME: application/pdf)

5.2. Veja abaixo um exemplo de código PHP para upload de arquivos com verificações de duplicidade, tamanho do arquivo e tipos MIME permitidos.

upload.php

if (isset($_FILES["arquivo"]) && $_FILES["arquivo"]["error"] == 0) {

    // variáveis iniciais
    $mensagem = null;
    $uploadOk = 1;

            
    // verifica se o arquivo já existe
    if (file_exists("arquivos/".$_FILES['arquivo']['name'])) {
        $mensagem = "O arquivo já existe.";
        $uploadOk = 0;
    }
    
    // limita o arquivo em 500000bytes (500kb)
    if ($_FILES['arquivo']['size'] > 500000) {
        $mensagem = "O arquivo é muito grande.";
        $uploadOk = 0;
    }
    
    //  permite apenas alguns formatos de arquivo
    if (!in_array($_FILES['arquivo']['type'], array('image/jpg','image/jpeg','image/png','image/gif','image/webp'))) {
        $mensagem = "Apenas arquivos JPG, JPEG, PNG,GIF e webp são permitidos.";
        $uploadOk = 0;
    }
    
    // valida e envia o arquivo para a pasta arquivos
    if ($uploadOk == 0) {          
        echo "Desculpe, o seu arquivo não foi enviado. ".$mensagem;
    } else {
        if (move_uploaded_file($_FILES['arquivo']['tmp_name'], 'arquivos/'.$_FILES['arquivo']['name']) === FALSE) {        
            echo "Desculpe, ocorreu um erro ao enviar seu arquivo.";
        } else {
            echo 'Arquivo <b>' . $_FILES['arquivo']['name'] . '</b> enviado com sucesso.';
        }
    }    
} else echo "Desculpe, ocorreu um erro ao enviar seu arquivo.";

6. Código completo otimizado

6.1. Abaixo, vamos apresentar um exemplo completo otimizado com as boas práticas do PHP moderno, onde recomendamos:

1. Use funções para melhorar a legibilidade e reutilização do código.
2. Evite concatenar diretamente strings com variáveis, use a sintaxe de string com aspas duplas para interpolação de variáveis.
3. Use constantes para valores fixos, como o limite de tamanho do arquivo e os tipos de arquivo permitidos.
4. Considere adicionar o bloco try...catch para capturar exceções ao mover o arquivo.

index.php

<!DOCTYPE html>
<html lang="pt-BR">
<head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Formulário de Envio de Arquivo</title>
</head>
<body>
    <form action="upload.php" method="POST" enctype="multipart/form-data">
        <label>Arquivo que será enviado: <input type="file" name="arquivo"></label>
        <input type="submit" value="Enviar">
    </form>
</body>
</html>

 upload.php

<h1>Validando o arquivo enviado</h1>
<?php

if (isset($_FILES["arquivo"]) && $_FILES["arquivo"]["error"] == 0) {
    
    // Variáveis iniciais
    $mensagem = null;
    $uploadOk = 1;
    $diretorio = 'arquivos/';
    $tamanhoMaximo = 500000; // 500kb
    $tiposPermitidos = array('image/jpg','image/jpeg','image/png','image/gif','image/webp');

    // Verifica se o arquivo já existe
    if (file_exists($diretorio . $_FILES['arquivo']['name'])) {
        $mensagem = "O arquivo já existe.";
        $uploadOk = 0;
    }

    // Limita o arquivo em 500000 bytes (500kb)
    if ($_FILES['arquivo']['size'] > $tamanhoMaximo) {
        $mensagem = "O arquivo é muito grande.";
        $uploadOk = 0;
    }

    // Permite apenas alguns formatos de arquivo
    if (!in_array($_FILES['arquivo']['type'], $tiposPermitidos)) {
        $mensagem = "Apenas arquivos JPG, JPEG, PNG, GIF e WEBP são permitidos.";
        $uploadOk = 0;
    }

    // Valida e envia o arquivo para a pasta "arquivos"
    if ($uploadOk == 0) {
        echo "Desculpe, o seu arquivo não foi enviado. " . $mensagem;
    } else {
        try {
            if (move_uploaded_file($_FILES['arquivo']['tmp_name'], $diretorio . $_FILES['arquivo']['name'])) {
                echo 'Arquivo <b>' . $_FILES['arquivo']['name'] . '</b> enviado com sucesso.';
            } else {
                throw new Exception("Ocorreu um erro ao enviar seu arquivo.");
            }
        } catch (Exception $e) {
            echo $e->getMessage();
        }
    }
} else {
    echo "Desculpe, ocorreu um erro ao enviar seu arquivo.";
}
?>

<br/><br/>
<div>
    <div>
        <a href="/index.php">Enviar Novo Arquivo</a> 
    </div>
</div>

Esse é apenas um exemplo sugerido. Certifique-se de adaptar o código conforme necessário para atender às suas necessidades específicas.

7. Documentação Oficial

1. [Documentação PHP - $_FILES] » $_FILES — Variáveis de Upload de Arquivos HTTP.

2. [Documentação PHP - Upload de arquivos] » Sobre o upload de arquivos com o método POST ¶

3. [Documentação PHP - move_uploaded_file » Sobre  a função move_uploaded_file() — Move um arquivo enviado para uma nova localização