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 Exemplo de informação
Exemplo de estrutura do array de progresso de 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.
A informação do progresso do upload é escrita na sessão antes da execução de quaisquer scripts. Portanto, alterar o nome da sessão através da função ini_set() ou session_name() resultará em uma sessão sem as informações de progresso do upload.
Note, this feature doesn't work, when your webserver is runnig PHP via FastCGI. There will be no progress informations in the session array.
Unfortunately PHP gets the data only after the upload is completed and can't show any progress.
I hope this informations helps.ATTENTION:
Put the upload progress session name input field BEFORE your file field in the form :
<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>
If you make it after your file field, you'll waste a lot of time figuring why (just like me ...)
The following form will make you crazy and waste really a lot of time:
<form action="upload.php" method="POST" enctype="multipart/form-data">
<input type="file" name="file1" />
<input type="file" name="file2" />
<input type="hidden" name="<?php echo ini_get("session.upload_progress.name"); ?>" value="123" />
<input type="submit" />
</form>
DON'T do this!While the example in the documentation is accurate, the description is a bit off. To clarify:
PHP will populate an array in the $_SESSION, where the index is a concatenated value of the session.upload_progress.prefix and the VALUE of the POSTed session.upload_progress.name variable.If you're seeing
"PHP Warning: Unknown: The session id is too long or contains illegal characters, valid characters are a-z, A-Z, 0-9 and '-,' in Unknown on line 0",
then a misplaced input could be the cause. It's worth mentioning again that the hidden element MUST be before the file elements.Note that if you run that code and you print out the content of $_SESSSION[$key] you get an empty array due that session.upload_progress.cleanup is on by default and it cleans the progress information as soon as all POST data has been read.
Set it to Off or 0 to see the content of $_SESSION[$key].it should be noted that the hidden element come before the file element otherwise you wont get any updates.dont't forget, that the session has to be initialized before the form is generated, otherwise the mentioned example above won't work.Warning:
Do not change session.save_path and session.name (in your application)!
The request for upload info must by POST with same value and name of your hidden input (session.upload_progress.name).
Info:
It works under IIS /FastCGI (at PHP 5.4 and PHP 8.2, other not tested).There were two gotchas that got me with implementing this.
The first - if you use session_name() to change the name of sessions, this will not work. I discovered this by looking at phpinfo() and seeing that is saw a different session name.
At least in Apache, a better way to set the session is in your apache config use
php_value session.name "your custom name"
It goes within the Directory directive, might work in .htaccess - I don't know.
-=-
Secondly - in apache, don't use mod_mpm_prefork.so
That was the problem I had, that's the default in CentOS 7.
The problem is it causes Apache to wait with any additional requests until the upload is finished.
Commenting that module out and using mod_mpm_worker.so instead fixed that problem, and the progress meter worked.session.upload_progress updates completely ignore custom session handlers set via session_set_save_handler()It seems like if you send a form with the field like :
<?php echo '<input type="hidden" name="'.ini_get('session.upload_progress.name') .'" value="123" />'; ?>
without any field type "file", the server respons will be an 500 error.