Como adicionar uma funcionalidade de carregamento de ficheiros em PHP com jQuery AJAX

Principais conclusões

• Utiliza PHP e jQuery em conjunto para permitir carregamentos de ficheiros suaves, baseados em AJAX, sem recarregar a página.
• Valida sempre os tipos e tamanhos dos ficheiros para proteger o teu servidor de carregamentos indesejados.
• Limpa os nomes de ficheiros para evitar riscos de segurança, como ataques de passagem de caminhos.
• Melhora a experiência do utilizador com indicadores de progresso em tempo real e mensagens de estado de carregamento.
• Armazena os detalhes dos ficheiros carregados de forma segura e, opcionalmente, utiliza o SQLite para um registo leve da base de dados.

Permitir que os utilizadores carreguem ficheiros é uma caraterística comum em muitos websites – quer se trate de imagens, PDFs ou outros documentos. Se estiveres a construir algo que precise disto, aprender a configurá-lo com PHP e jQuery pode poupar-te muito tempo e dores de cabeça.

O PHP torna o manuseamento de ficheiros bastante simples. E quando o combinas com jQuery e AJAX, podes fazer com que a experiência de carregamento seja perfeita sem necessidade de recarregar a página.

Neste passo a passo, começaremos com uma versão simples de um tutorial de upload de arquivos em PHP e, gradualmente, vamos desenvolvê-lo – adicionando verificações de tipo e tamanho de arquivo, limpeza de nome de arquivo, uma barra de progresso e até mesmo uma pequena galeria para visualizar os arquivos enviados.

Vamos lá começar.

Pré-requisitos

Antes de começarmos, eis o que vais precisar:

• Um servidor ativo ou um servidor local:
  • Podes usar o XAMPP ou o MAMP para desenvolvimento local (isto inclui Apache, MySQL e PHP prontos a usar).
  • Neste tutorial, usarei o Cloudways para implantar meu servidor e aplicativo on-line, o que elimina a necessidade de configuração local e fornece uma plataforma fácil de usar com uma pilha integrada.
• Uma forma de aceder aos ficheiros do teu servidor:
  • Estou a utilizar o FileZilla para carregar e gerir ficheiros no meu servidor.
• Tens conhecimentos básicos de HTML, PHP e jQuery. Mesmo que não tenhas, eu acompanho-te em todos os passos.

Base de dados (opcional): Usaremos o SQLite mais tarde no tutorial para registar a informação dos ficheiros carregados, por isso não precisas de uma configuração completa do MySQL.

Para este tutorial, utilizaremos o Cloudways para iniciar um servidor com um aplicativo WordPress implantado. No entanto, nosso foco será a criação de um recurso PHP independente.

O que estamos a construir?

Vamos construir uma interface web simples onde um utilizador pode carregar um ficheiro (por exemplo, imagem, PDF, etc.), e o ficheiro será armazenado no servidor – sem atualizar a página. Usaremos:

• HTML para o formuláriojQuery para capturar a entrada do ficheiro e enviá-la através de AJAX
• PHP no backend para lidar com o upload
• FileZilla para fazer upload de arquivos para o teu servidor Cloudways

No final, carregamos o formulário no browser e carregamos um ficheiro para garantir que tudo funciona.

Melhora as tuas aplicações PHP com o alojamento gerido da Cloudways!

Experimenta o próximo nível de desempenho com o nosso Alojamento PHP Gerido! Melhora os teus projectos Web hoje. Começa agora!

Experimenta grátis!

Parte 1: Configurar o carregamento básico de ficheiros

Vamos começar com um sistema simples de carregamento de ficheiros. Terás uma página Web onde os utilizadores podem selecionar um ficheiro e clicar em carregar. O ficheiro será enviado para o servidor utilizando AJAX sem atualizar a página.

Passo 1: Criar a tua estrutura de pastas

Na tua aplicação Cloudways (ou public_html local), cria uma nova pasta para este projeto. Eu vou chamar a minha de file-upload.

Dentro de file-upload, cria estas três coisas:

1. index.html – O nosso ficheiro principal do frontend.
2. upload.php – O script de backend que lida com os uploads.
3. uploads/ – Uma pasta para armazenar os ficheiros carregados.

Podes criar esta estrutura utilizando o FileZilla, navegando até public_html, clicando com o botão direito do rato para criar um diretório (file-upload) e, em seguida, criando os ficheiros e as pastas no seu interior.

Passo 2: Constrói o formulário HTML (index.html)

Vamos escrever a interface de carregamento. Este é o ficheiro com o qual os utilizadores vão interagir. Vamos editar o ficheiro index.html que criámos anteriormente e colar este código nele:

<!DOCTYPE html>

<html lang="en">

<cabeça>

<meta charset="UTF-8">

<título>Upload de ficheiros simples</title>

<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>

</head>

<corpo>

<h2>Carrega um ficheiro</h2>

<input type="file" id="fileInput">

<botão id="uploadBtn">Carrega</button>

<div id="status"></div>

<guião>

$('#uploadBtn').on('click', function () {

var ficheiro = $('#fileInput')[0].ficheiros[0];

se (!ficheiro) {

$('#status').text('Por favor, seleciona um ficheiro.');

regressa;

}

var formData = new FormData();

formData.append('file', file);

$.ajax({

url: 'upload.php',

tipo: "POST",

dados: formData,

processData: false,

contentType: false,

sucesso: função (resposta) {

$('#status').html(response);

},

erro: função () {

$('#status').text('Ocorreu um erro durante o carregamento.');

}

});

});

</script>

</body>

</html>

Esta é a parte da frente do nosso carregador – apenas um formulário básico com uma entrada de ficheiro e um botão. Também vamos carregar o jQuery para podermos usar AJAX.

O que é que se passa aqui?

Estamos a utilizar o jQuery para ouvir um clique no botão, agarrar o ficheiro selecionado e enviá-lo para o servidor utilizando AJAX. Isso evita que a página seja recarregada e proporciona uma experiência mais suave.

Passo 3: Trata do Upload em PHP (upload.php)

Este script recebe o ficheiro do AJAX e move-o para a pasta uploads/.

<?php

se (isset($_FILES['file'])) {

$targetDir = "uploads/";

$filename = basename($_FILES["file"]["name"]);

$targetFilePath = $targetDir . $filename; 

Se (move_uploaded_file($_FILES["file"]["tmp_name"], $targetFilePath)) {

echo "Ficheiro carregado com sucesso: " . htmlspecialchars($filename); 

} else {

echo "Falha ao carregar o ficheiro.";

}

} else {

echo "Não recebeste nenhum ficheiro";

}

?>

Passo 4: Testar o Upload básico

• Navega para https://yourdomain.com/file-upload/index.html no teu browser. No meu caso, vou para este URL: https://wordpress-1070279-3883303.cloudwaysapps.com/file-upload/index.html.

• Seleciona um ficheiro e clica no botão Carregar.

• Deves ver uma mensagem de sucesso e o ficheiro deve aparecer no diretório de uploads.

Aloja sites PHP com facilidade [A partir de $11 de crédito]

• Encenação gratuita
• Backup gratuito
• PHP 8.3
• Websites ilimitados

TESTE AGORA

Parte 2: Atualizar o carregamento de ficheiros (versão avançada)

Agora que já temos o upload básico de ficheiros a funcionar, vamos dar um passo em frente. O que construímos antes foi a “prova de conceito” – carrega um ficheiro e diz-nos que funcionou (ou não).

Isso é bom para começar, mas no mundo real, precisamos de mais controlo, segurança e feedback.

Por isso, nesta parte do guia, vamos melhorar o nosso carregador:

• Limitar os tipos de ficheiros (para que os utilizadores não possam carregar qualquer coisa)
• Aplicar um limite de tamanho
• Limpa os nomes dos ficheiros (porque os utilizadores podem ser sorrateiros)
• Mostra uma barra de progresso de carregamento em direto
• Apresenta uma galeria de ficheiros carregados
• Armazena a informação do ficheiro numa base de dados (vamos usar o SQLite – mais fácil do que o MySQL)
• Proteger a pasta de carregamento
• Adiciona opcionalmente o reCAPTCHA para proteção contra spam

Esta secção assume que já configuraste o teu projeto com a versão básica (com index.html, upload.php e uma pasta uploads/). Se não o fizeste, volta atrás e segue primeiro a Parte 1.

Restringe os carregamentos a tipos de ficheiros específicos (imagens e PDFs)

Neste momento, os utilizadores podem carregar qualquer ficheiro – .exe, .php, .zip, o que quiseres. Não é seguro. Vamos corrigir isso verificando o tipo MIME do ficheiro carregado. Apenas os ficheiros JPEG, PNG, GIF e PDF devem ser permitidos.

Abre o teu ficheiro upload.php e substitui todo o código por este:

<?php

se (isset($_FILES['file'])) {

$allowedTypes = ['image/jpeg', 'image/png', 'image/gif', 'application/pdf'];

$fileType = $_FILES["file"]["type"];

Se (!in_array($fileType, $allowedTypes)) {

echo "Só são permitidas imagens JPG, PNG, GIF e PDFs";

sai;

}

$targetDir = "uploads/";

$filename = basename($_FILES["file"]["name"]);

$targetFilePath = $targetDir . $filename; 

Se (move_uploaded_file($_FILES["file"]["tmp_name"], $targetFilePath)) {

echo "Ficheiro carregado com sucesso: " . htmlspecialchars($filename); 

} else {

echo "Falha ao carregar o ficheiro.";

}

} else {

echo "Não recebeste nenhum ficheiro";

}

?>

O que é que se passa aqui?

Estamos a verificar o tipo de ficheiro carregado. Se não corresponder a um dos tipos da nossa lista de permissões, interrompemos o carregamento e mostramos uma mensagem.

Testa!

Por isso, se eu tentar carregar um ficheiro não suportado, recebo uma mensagem a dizer “Apenas são permitidas imagens JPG, PNG, GIF e PDFs”.

Mas se eu carregar um arquivo PNG, por exemplo, ele deve ser carregado imediatamente.

Adiciona um limite de tamanho de ficheiro (máx. 5MB)

Para evitar que ficheiros enormes entupam o teu servidor, limitaremos os carregamentos a 5 MB.

Abre novamente o teu upload.php e, antes da linha move_uploaded_file(), adiciona este código:

$maxSize = 5 1024 1024; // 5MB

se ($_FILES["ficheiro"]["tamanho"]  >  $maxSize) {

echo "O ficheiro é demasiado grande. O tamanho máximo permitido é 5MB";

sai;

}

Assim:

Porque é que estamos a fazer isto?

Um utilizador pode carregar acidentalmente (ou intencionalmente) um vídeo de 200 MB. Este limite evita que isso aconteça e ajuda o teu site a manter-se rápido e com boa capacidade de resposta.

Testa!

Para o testar, vou adicionar uma imagem com 10 MB de tamanho, superior ao limite de 5 MB que adicionámos.

Neste caso, verei a mensagem “O ficheiro é demasiado grande. O tamanho máximo permitido é 5MB”. Faz assim:

Limpa o nome do ficheiro

Quando os utilizadores carregam ficheiros, podem dar-lhes qualquer nome – desde algo inofensivo como profile_picture.jpg até algo muito confuso como:

../../../evil<script>.php

ou

o meu*currículo#final@@@!!v9.pdf

Não queremos que esse caos acabe no sistema de ficheiros do nosso servidor. Não só parece confuso, como pode abrir a porta a vulnerabilidades de segurança (como ataques de path traversal, em que alguém tenta saltar para fora da pasta pretendida).

Para resolver este problema, podemos implementar a sanitização de ficheiros.

Encontra esta linha em upload.php:

$filename = basename($_FILES["file"]["name"]);

E substitui-o por:

$filename = preg_replace("/[^A-Za-z0-9\.\-_]/", '', basename($_FILES["file"]["name"]));

O que é que isto faz:

Elimina qualquer caractere que não seja uma letra, número, ponto, traço ou sublinhado. Isso mantém as coisas limpas e evita explorações de caminho.

Vê a tabela abaixo para compreenderes melhor:

Nome do ficheiro original	Depois da Sanitização
o meu currículo (final)!!!v3.pdf	o meu curriculofinalv3.pdf
../../../secret.php	secret.php
olá@#mundo!.jpg	olá@#mundo.jpg
factura_2024^%$.pdf	factura_2024.pdf

Testa!

Para testar, vamos carregar um ficheiro chamado “weird^%$#@!.pdf”.

Agora, se formos à pasta de uploads, vais reparar que todos os símbolos estranhos desapareceram.

Adiciona uma barra de progresso com jQuery + AJAX

Vamos agora melhorar a experiência do utilizador. Em vez de clicares em carregar e esperares que algo aconteça, mostraremos o progresso ao vivo.

Porquê utilizar jQuery e AJAX aqui?

AJAX permite-nos carregar o ficheiro em segundo plano sem recarregar a página. jQuery torna a sintaxe mais fácil e mais limpa.

No teu index.html, encontra a etiqueta<script> na parte inferior e substitui tudo por isto:

<guião>

$('#uploadBtn').on('click', function () {

var ficheiro = $('#fileInput')[0].ficheiros[0];

se (!ficheiro) {

$('#status').text('Por favor, seleciona um ficheiro.');

regressa;

}

var formData = new FormData();

formData.append('file', file);

var xhr = new XMLHttpRequest();

xhr.open("POST", "upload.php", true);

xhr.upload.onprogress = function (e) {

Se (e.lengthComputable) {

var percent = Math.round((e.loaded / e.total) * 100);

$('#status').html("A carregar: " + percentagem + "%");

}

};

xhr.onload = function () {

se (xhr.status == 200) {

$('#status').html(xhr.responseText);

} else {

$('#status').text('Upload failed.');

}

};

xhr.send(formData);

});

</script>

Vê o GIF abaixo:

Testa!

Agora, se eu carregar um ficheiro, podemos ver uma barra de progresso. Vê o GIF abaixo:

Agora os teus utilizadores podem ver o progresso do carregamento em tempo real para uma experiência muito mais suave.

Mostra todos os ficheiros carregados por baixo do formulário

Agora mostramos uma lista de todos os ficheiros carregados numa mini-galeria mesmo por baixo do teu formulário de carregamento, e certificamo-nos de que é actualizada automaticamente sempre que um novo ficheiro é carregado.

Esta é uma excelente funcionalidade se quiseres que os utilizadores (ou tu próprio) vejam a lista de ficheiros que já se encontram nos teus carregamentos/pasta – sem teres de atualizar a página.

Eis como o podes conseguir:

1. Abre index.html e, abaixo da div #status, adiciona isto:

<div id="galeria"></div>

2. Cria um novo ficheiro na mesma pasta chamado list_uploads.php.

E cola isto lá dentro:

<?php

$dir = 'uploads/';

$files = scandir($dir);

vê ($files as $file) {

Se ($file === '.' || $file === '..') continua;

echo "<p><a href='uploads/$file' target='_blank'>$file</a></p>";

}

?>

3. Volta ao teu script<> em index.html e actualiza a parte xhr.onload da seguinte forma:

xhr.onload = function () {

se (xhr.status == 200) {

$('#status').html(xhr.responseText);

$('#gallery').load('list_uploads.php');

} else {

$('#status').text('Upload failed.');

}

};

Agora o que acontece:

Sempre que um ficheiro é carregado, a lista por baixo do formulário é actualizada com uma ligação clicável para esse ficheiro.

Os uploads de ficheiros PHP estão a funcionar mal?

Partilha o teu código e obtém feedback instantâneo dos programadores na Comunidade Cloudways Reddit.

Junta-te a nós no Reddit

Terminar!

Isso encerra nosso guia de upload de arquivos PHP. Agora tens uma funcionalidade de carregamento de ficheiros que funciona utilizando PHP e jQuery AJAX, com actualizações úteis como validação, uma barra de progresso e uma galeria ao vivo.

Estes pequenos mas importantes detalhes contribuem muito para que os utilizadores sintam que os carregamentos são fiáveis e fáceis. Se tencionas desenvolver isto, tens um ponto de partida sólido a partir do qual podes crescer.