Quando a configuração INI session.upload_progress.enabled estiver habilitada, o PHP será capaz de rastrear o progresso do upload de arquivos individuais que estiverem sendo feito upload. Esta informação não é muito útil para a requisição atual, mas durante o upload do arquivo uma aplicação pode enviar uma requisição POST para um endpoint separado (via XHR por exemplo) para checar o status.
O progresso do upload estará disponível na variável super global $_SESSION quando um upload estiver em progresso e quando a requisição POST tiver uma variável com o mesmo nome que a configuração INI session.upload_progress.name estiver configurada. Quando o PHP detectar requisições como essa, ele preencherá um array em $_SESSION, onde o índice é um valor resultante da concatenação de session.upload_progress.prefix e session.upload_progress.name (configurações INI). O índice normalmente é obtido lendo essas configurações INI, ou seja
<?php
$key = ini_get("session.upload_progress.prefix") . $_POST[ini_get("session.upload_progress.name")];
var_dump($_SESSION[$key]);
?>
Também é possível cancelar o upload do arquivo em
andamento ao definir o índice $_SESSION[$key]["cancel_upload"] para
TRUE.
Quando houver upload de múltiplos arquivos em uma mesma requisição, isso vai cancelar apenas o
upload dos arquivos que ainda estiverem em andamento e pendentes, mas não
removerá uploads já concluídos com sucesso.
Quando um upload é cancelado dessa forma, o índice error no array
$_FILES será alterado para
UPLOAD_ERR_EXTENSION.
As configurações INI session.upload_progress.freq e session.upload_progress.min_freq controlam a frequência com que a informação do progresso do upload deve ser recalculado. Com um valor razoável para estas duas configurações, a sobrecarga desse recurso é quase inexistente.
Exemplo #1 Informação de exemplo
Exemplo de estrutura do array de progresso do upload.
<form action="upload.php" method="POST" enctype="multipart/form-data">
<input type="hidden" name="<?php echo ini_get("session.upload_progress.name"); ?>" value="123" />
<input type="file" name="file1" />
<input type="file" name="file2" />
<input type="submit" />
</form>
Os dados armazenados na sessão serão parecidos com isto:
<?php
$_SESSION["upload_progress_123"] = array(
"start_time" => 1234567890, // A hora da requisição
"content_length" => 57343257, // tamanho do conteúdo de POST
"bytes_processed" => 453489, // Quantidade de bytes recebidos e processados
"done" => false, // true quando o manipulador do POST finalizar, com sucesso ou não
"files" => array(
0 => array(
"field_name" => "file1", // Nome do campo <input/>
// Os próximos 3 elementos se assemelham aos de $_FILES
"name" => "foo.avi",
"tmp_name" => "/tmp/phpxxxxxx",
"error" => 0,
"done" => true, // True quando o manipulador do POST terminar de manipular este arquivo
"start_time" => 1234567890, // Quando este arquivo começou a ser processado
"bytes_processed" => 57343250, // Quantidade de bytes recebidos e processados para este arquivo
),
// Um outro arquivo, em que o upload ainda não acabou, na mesma requisição
1 => array(
"field_name" => "file2",
"name" => "bar.avi",
"tmp_name" => NULL,
"error" => 0,
"done" => false,
"start_time" => 1234567899,
"bytes_processed" => 54554,
),
)
);
O buffer de requisições do servidor web deve estar desabilitado para que isso funcione corretamente ou o PHP pode enxergar o upload apenas quando ele já estiver completado. É de conhecimento que servidores como Nginx criam buffer para requisições maiores.