Session 上传进度

Note: 此特性自 PHP 5.4.0 后可用。

当 session.upload_progress.enabled INI 选项开启时，PHP 能够在每一个文件上传时监测上传进度。这个信息对上传请求自身并没有什么帮助，但在文件上传时应用可以发送一个POST请求到终端（例如通过XHR）来检查这个状态

当一个上传在处理中，同时POST一个与INI中设置的session.upload_progress.name同名变量时，上传进度可以在$_SESSION中获得。当PHP检测到这种POST请求时，它会在$_SESSION中添加一组数据, 索引是 session.upload_progress.prefix 与 session.upload_progress.name连接在一起的值。通常这些键值可以通过读取INI设置来获得，例如


<?php
$key = ini_get("session.upload_progress.prefix") . ini_get("session.upload_progress.name");
var_dump($_SESSION[$key]);
?>

通过将$_SESSION[$key]["cancel_upload"]设置为true，还可以取消一个正在处理中的文件上传。当在同一个请求中上传多个文件，它仅会取消当前正在处理的文件上传和未处理的文件上传，但是不会移除那些已经完成的上传。当一个上传请求被这么取消时，$_FILES中的error将会被设置为 UPLOAD_ERR_EXTENSION。

session.upload_progress.freq 和 session.upload_progress.min_freq INI选项控制了上传进度信息应该多久被重新计算一次。通过合理设置这两个选项的值，这个功能的开销几乎可以忽略不计。

Example #1 样例信息

一个上传进度数组的结构的例子

<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>

在session中存放的数据看上去是这样子的：


<?php
$_SESSION["upload_progress_123"] = array(
 "start_time" => 1234567890,   // The request time
 "content_length" => 57343257, // POST content length
 "bytes_processed" => 453489,  // Amount of bytes received and processed
 "done" => false,              // true when the POST handler has finished, successfully or not
 "files" => array(
  0 => array(
   "field_name" => "file1",       // Name of the <input/> field
   // The following 3 elements equals those in $_FILES
   "name" => "foo.avi",
   "tmp_name" => "/tmp/phpxxxxxx",
   "error" => 0,
   "done" => true,                // True when the POST handler has finished handling this file
   "start_time" => 1234567890,    // When this file has started to be processed
   "bytes_processed" => 57343250, // Amount of bytes received and processed for this file
  ),
  // An other file, not finished uploading, in the same request
  1 => array(
   "field_name" => "file2",
   "name" => "bar.avi",
   "tmp_name" => NULL,
   "error" => 0,
   "done" => false,
   "start_time" => 1234567899,
   "bytes_processed" => 54554,
  ),
 )
);

Warning

为了使这个正常工作，web服务器的请求缓冲区需要禁用，否则 PHP可能仅当文件完全上传完成时才能收到文件上传请求。已知会缓冲这种大请求的程序有Nginx。

Caution

这个进度信息是在任意脚本被执行前写入session的，因此通过 ini_set()或session_name()修改session名将会导致一个没有上传进度信息的session。

User Contributed Notes

alice at librelamp dot com 20-Jul-2016 11:49


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.

adri74 at hotmail dot fr 18-Feb-2016 04:15


It seems like defining a session name before starting the session makes the $_SESSION['upload_progress...'] not to work any more !



session_name('session');

session_start();



(in both the upload page, and the XHR request)

ricki at rocker dot com 28-Apr-2015 06:36


session.upload_progress updates completely ignore custom session handlers set via  session_set_save_handler()

howtomakeaturn 04-Apr-2015 07:18


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!

StrateGeyti 20-Oct-2014 10:07


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.

wilsonr at st dot com 03-Oct-2014 07:22


If you have upload progress enabled in your php.ini, and you have 



<form enctype="multipart/form-data" ...

    <input type="hidden" name="PHP_SESSION_UPLOAD_PROGRESS" ...



in your form, but you DON'T specify an input with 'type="file"', you may lose your session ID. I am using PHP 5.5 and I lose my session ID on the second loading of such a page. To prevent this, you can use a dummy input as follows:



<form enctype="multipart/form-data" ... >

    <input type="hidden" name="PHP_SESSION_UPLOAD_PROGRESS" ... />

    <input type="file"' name="dummy" style="display="none;" ... />

jortsc at gmail dot com 29-Sep-2013 06:47


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].

Anonymous 12-Jun-2013 03:34


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.

Anonymous 02-May-2013 08:01


dont't forget, that the session has to be initialized before the form is generated, otherwise the mentioned example above won't work.

isius 03-Sep-2012 05:11


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.

nihaopaul at gmail dot com 10-Aug-2012 06:12


it should be noted that the hidden element come before the file element otherwise you wont get any updates.

s.zarges 19-Jun-2012 09:32


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.

powtac at gmx dot de 02-Mar-2012 08:35


For PHP >= 5.2 there is http://pecl.php.net/package/uploadprogress