Pular para o conteúdo
Setup do Dev
Programação

Por que o $_FILES chega vazio no upload do PHP, e como saber qual limite estourou

Testamos os limites de upload do PHP 8.5 com arquivos de 300 KB a 2 MB. O maior deles apaga o $_POST inteiro, e só o log do servidor avisa.

Por Setup do Dev
4 min de leitura
Compartilhar
Capa roxa com a manchete "O upload que chegou vazio", o dado 2 MB contra o limite de 1 MB e um terminal com o $_POST e o $_FILES vazios.

O formulário tem o campo de arquivo, o usuário escolhe a foto, clica em enviar, e o script recebe um $_FILES vazio. Pior: às vezes o $_POST também chega vazio, com o título, a descrição e o token CSRF, e a mensagem de erro que aparece para o usuário é a do token inválido. Nada no navegador explica o que houve.

Montamos o caso na máquina da redação para ver o que o PHP 8.5 entrega ao script em cada situação. O servidor foi o embutido do PHP, com limites baixos para o teste ficar rápido:

php -d post_max_size=1M -d upload_max_filesize=512K -d max_file_uploads=5 \
    -S 127.0.0.1:8731 -t www

E o script só mostrava o que chegou: o Content-Length da requisição, o $_POST, o $_FILES e o error_get_last(). Os envios foram feitos com o curl -F, que monta o mesmo multipart/form-data de um formulário.

O que chegou em cada envio

Um arquivo de 300 KB chegou inteiro, com error 0. Até aí, nada de novo.

O de 700 KB passou do upload_max_filesize (512 KB), mas ficou abaixo do post_max_size (1 MB). O PHP entregou o resto do formulário normalmente e, no $_FILES, o nome do arquivo com tamanho 0 e error 1, que é a constante UPLOAD_ERR_INI_SIZE. É o caso fácil: o script consegue saber o que houve, se olhar o error.

O de 2 MB passou do post_max_size, e aí o comportamento muda. O script recebeu:

CONTENT_LENGTH: 2000320
$_POST: []
$_FILES: []
error_get_last: PHP Request Startup: POST Content-Length of 2000320 bytes exceeds the limit of 1048576 bytes

O campo de texto titulo, que não tinha nada a ver com o arquivo, sumiu junto. O manual do PHP confirma que, quando o corpo passa do post_max_size, as duas superglobais ficam vazias. O aviso vai para o log como PHP Warning, e com display_errors desligado, como deve estar em produção, ninguém o vê na tela.

Dois casos que não são de tamanho

Um formulário sem enctype="multipart/form-data" não manda o arquivo. No teste, o $_FILES veio vazio e o $_POST trouxe só o nome do arquivo como texto, "arquivo":"foto.jpg". É o primeiro lugar para olhar quando o vazio acontece com qualquer arquivo, até com o pequeno.

O outro é o max_file_uploads. Mandamos sete arquivos de 50 KB num campo fotos[], com o limite em 5. Chegaram cinco, todos com error 0, e os outros dois desapareceram sem erro nenhum no $_FILES. O único rastro é outro aviso no log: Maximum number of allowable file uploads has been exceeded. Uma galeria que aceita “várias fotos” perde as últimas sem avisar ninguém.

Tabela com cinco envios: 300 KB chegou com erro 0; 700 KB chegou com o nome, tamanho 0 e erro 1; 2 MB chegou com o $_POST e o $_FILES vazios; o formulário sem multipart trouxe só o nome do arquivo no $_POST; sete arquivos de 50 KB chegaram cinco.
O que o PHP entregou ao script em cada envio do teste, com post_max_size de 1 MB e upload_max_filesize de 512 KB

Os padrões, e onde mudar

Pelo manual, os padrões são post_max_size de 8M, upload_max_filesize de 2M e max_file_uploads de 20. O post_max_size precisa ser maior que o upload_max_filesize, com folga para os outros campos e para várias fotos de uma vez.

Os três são INI_PERDIR: mudam no php.ini, no .user.ini ou na configuração do servidor, e não no código. Testamos: ini_set('post_max_size', '64M') devolveu false e o valor continuou o mesmo. E confira o php.ini que o servidor web usa, que pode não ser o do terminal, como mostramos em outro guia.

Com nginx na frente, existe um quarto limite, que vem antes do PHP. O client_max_body_size tem padrão de 1m, e acima dele o nginx responde 413 sem o PHP nem saber que a requisição existiu. A própria documentação avisa que os navegadores não mostram esse erro direito. Subir o limite do PHP para 64M e esquecer o do nginx deixa tudo acima de 1 MB barrado do mesmo jeito.

Como o script descobre o que houve

O vazio total tem um sinal: método POST, $_POST e $_FILES vazios, e um Content-Length maior que o limite. Este trecho, testado com os mesmos envios, responde 413 com uma mensagem que o usuário entende, antes de o código reclamar do token:

function sdd_bytes(string $v): int
{
    $n = (int) $v;
    return match (strtoupper(substr(trim($v), -1))) {
        'G' => $n * 1024 ** 3,
        'M' => $n * 1024 ** 2,
        'K' => $n * 1024,
        default => $n,
    };
}

if ($_SERVER['REQUEST_METHOD'] === 'POST' && $_POST === [] && $_FILES === []
    && (int) ($_SERVER['CONTENT_LENGTH'] ?? 0) > sdd_bytes(ini_get('post_max_size'))) {
    http_response_code(413);
    exit('O envio passou de ' . ini_get('post_max_size') . '.');
}

Para o resto, a tabela de códigos de erro do upload vira uma mensagem por arquivo. No teste com um arquivo de 300 KB e outro de 700 KB no mesmo envio, o primeiro deu “ok” e o segundo, “maior que o upload_max_filesize (512K)”. Um campo de arquivo deixado em branco dá UPLOAD_ERR_NO_FILE, o 4, e não conta no limite de quantidade.

O que não dá para descobrir no PHP é o arquivo cortado pelo max_file_uploads: os que chegaram estão perfeitos. Se a galeria aceita várias fotos, conte quantas o usuário escolheu no navegador, mande o número num campo escondido e compare com o que chegou.

Fontes: Manual do PHP: diretivas do php.ini, Manual do PHP: mensagens de erro do upload, Documentação do nginx: client_max_body_size

Produzido com auxílio de IA e revisado pela redação.

Comentários (0)

Ainda não há comentários. Comece a conversa.

Deixe seu comentário

Seu e-mail não será publicado. O primeiro comentário de cada pessoa passa por moderação.

Seja respeitoso

Neste artigo

  1. O que chegou em cada envio
  2. Dois casos que não são de tamanho
  3. Os padrões, e onde mudar
  4. Como o script descobre o que houve

Mais lidas

Editorias

Leia também

Newsletter semanal

O essencial da tecnologia, toda sexta no seu e-mail

Uma curadoria da redação com as notícias que importam para quem desenvolve, joga e trabalha com tecnologia. Sem spam.

Ao assinar, você concorda com a política de privacidade. Cancele quando quiser.