bjori                                    Tue, 30 Aug 2011 11:13:22 +0000

Revision: http://svn.php.net/viewvc?view=revision&revision=315770

Log:
Fixed bug#55430, introduce the session.upload_progress family to the world

Bug: https://bugs.php.net/55430 (Assigned) New session.upload_progress.* values 
are not in php.ini-*
      
Changed paths:
    U   php/php-src/branches/PHP_5_4/php.ini-development
    U   php/php-src/branches/PHP_5_4/php.ini-production
    U   php/php-src/trunk/php.ini-development
    U   php/php-src/trunk/php.ini-production
    U   phpdoc/en/trunk/reference/session/book.xml
    U   phpdoc/en/trunk/reference/session/ini.xml
    A   phpdoc/en/trunk/reference/session/upload-progress.xml
    U   web/php/trunk/include/errors.inc

Modified: php/php-src/branches/PHP_5_4/php.ini-development
===================================================================
--- php/php-src/branches/PHP_5_4/php.ini-development	2011-08-30 11:08:01 UTC (rev 315769)
+++ php/php-src/branches/PHP_5_4/php.ini-development	2011-08-30 11:13:22 UTC (rev 315770)
@@ -1561,11 +1561,49 @@
 ; http://php.net/url-rewriter.tags
 url_rewriter.tags = "a=href,area=href,frame=src,input=src,form=fakeentry"

-;session.upload_progress.enabled = "1"
-;session.upload_progress.cleanup = "1"
+; Enable upload procgress tracking in $_SESSION
+; Default Value: On
+; Development Value: On
+; Production Value: On
+; http://php.net/session.upload-progress.enabled
+;session.upload_progress.enabled = On
+
+; Cleanup the progress information as soon as all POST data has been read
+; (i.e. upload completed).
+; Default Value: On
+; Development Value: On
+; Production Value: On
+; http://php.net/session.upload-progress.cleanup
+;session.upload_progress.cleanup = On
+
+; A prefix used for the upload progress key in $_SESSION
+; Default Value: "upload_progress_"
+; Development Value: "upload_progress_"
+; Production Value: "upload_progress_"
+; http://php.net/session.upload-progress.prefix
 ;session.upload_progress.prefix = "upload_progress_"
+
+; The index name (concatenated with the prefix) in $_SESSION
+; containing the upload progress information
+; Default Value: "PHP_SESSION_UPLOAD_PROGRESS"
+; Development Value: "PHP_SESSION_UPLOAD_PROGRESS"
+; Production Value: "PHP_SESSION_UPLOAD_PROGRESS"
+; http://php.net/session.upload-progress.name
 ;session.upload_progress.name = "PHP_SESSION_UPLOAD_PROGRESS"
+
+; How frequently the upload progress should be updated.
+; Given either in percentages (per-file), or in bytes
+; Default Value: "1%"
+; Development Value: "1%"
+; Production Value: "1%"
+; http://php.net/session.upload-progress.freq
 ;session.upload_progress.freq =  "1%"
+
+; The minimum delay between updates, in seconds
+; Default Value: 1
+; Development Value: 1
+; Production Value: 1
+; http://php.net/session.upload-progress.min-freq
 ;session.upload_progress.min_freq = "1"

 [MSSQL]

Modified: php/php-src/branches/PHP_5_4/php.ini-production
===================================================================
--- php/php-src/branches/PHP_5_4/php.ini-production	2011-08-30 11:08:01 UTC (rev 315769)
+++ php/php-src/branches/PHP_5_4/php.ini-production	2011-08-30 11:13:22 UTC (rev 315770)
@@ -1561,13 +1561,50 @@
 ; http://php.net/url-rewriter.tags
 url_rewriter.tags = "a=href,area=href,frame=src,input=src,form=fakeentry"

-;session.upload_progress.enabled = "1"
-;session.upload_progress.cleanup = "1"
+; Enable upload procgress tracking in $_SESSION
+; Default Value: On
+; Development Value: On
+; Production Value: On
+; http://php.net/session.upload-progress.enabled
+;session.upload_progress.enabled = On
+
+; Cleanup the progress information as soon as all POST data has been read
+; (i.e. upload completed).
+; Default Value: On
+; Development Value: On
+; Production Value: On
+; http://php.net/session.upload-progress.cleanup
+;session.upload_progress.cleanup = On
+
+; A prefix used for the upload progress key in $_SESSION
+; Default Value: "upload_progress_"
+; Development Value: "upload_progress_"
+; Production Value: "upload_progress_"
+; http://php.net/session.upload-progress.prefix
 ;session.upload_progress.prefix = "upload_progress_"
+
+; The index name (concatenated with the prefix) in $_SESSION
+; containing the upload progress information
+; Default Value: "PHP_SESSION_UPLOAD_PROGRESS"
+; Development Value: "PHP_SESSION_UPLOAD_PROGRESS"
+; Production Value: "PHP_SESSION_UPLOAD_PROGRESS"
+; http://php.net/session.upload-progress.name
 ;session.upload_progress.name = "PHP_SESSION_UPLOAD_PROGRESS"
+
+; How frequently the upload progress should be updated.
+; Given either in percentages (per-file), or in bytes
+; Default Value: "1%"
+; Development Value: "1%"
+; Production Value: "1%"
+; http://php.net/session.upload-progress.freq
 ;session.upload_progress.freq =  "1%"
+
+; The minimum delay between updates, in seconds
+; Default Value: 1
+; Development Value: 1
+; Production Value: 1
+; http://php.net/session.upload-progress.min-freq
 ;session.upload_progress.min_freq = "1"
-
 [MSSQL]
 ; Allow or prevent persistent links.
 mssql.allow_persistent = On

Modified: php/php-src/trunk/php.ini-development
===================================================================
--- php/php-src/trunk/php.ini-development	2011-08-30 11:08:01 UTC (rev 315769)
+++ php/php-src/trunk/php.ini-development	2011-08-30 11:13:22 UTC (rev 315770)
@@ -1561,11 +1561,49 @@
 ; http://php.net/url-rewriter.tags
 url_rewriter.tags = "a=href,area=href,frame=src,input=src,form=fakeentry"

-;session.upload_progress.enabled = "1"
-;session.upload_progress.cleanup = "1"
+; Enable upload procgress tracking in $_SESSION
+; Default Value: On
+; Development Value: On
+; Production Value: On
+; http://php.net/session.upload-progress.enabled
+;session.upload_progress.enabled = On
+
+; Cleanup the progress information as soon as all POST data has been read
+; (i.e. upload completed).
+; Default Value: On
+; Development Value: On
+; Production Value: On
+; http://php.net/session.upload-progress.cleanup
+;session.upload_progress.cleanup = On
+
+; A prefix used for the upload progress key in $_SESSION
+; Default Value: "upload_progress_"
+; Development Value: "upload_progress_"
+; Production Value: "upload_progress_"
+; http://php.net/session.upload-progress.prefix
 ;session.upload_progress.prefix = "upload_progress_"
+
+; The index name (concatenated with the prefix) in $_SESSION
+; containing the upload progress information
+; Default Value: "PHP_SESSION_UPLOAD_PROGRESS"
+; Development Value: "PHP_SESSION_UPLOAD_PROGRESS"
+; Production Value: "PHP_SESSION_UPLOAD_PROGRESS"
+; http://php.net/session.upload-progress.name
 ;session.upload_progress.name = "PHP_SESSION_UPLOAD_PROGRESS"
+
+; How frequently the upload progress should be updated.
+; Given either in percentages (per-file), or in bytes
+; Default Value: "1%"
+; Development Value: "1%"
+; Production Value: "1%"
+; http://php.net/session.upload-progress.freq
 ;session.upload_progress.freq =  "1%"
+
+; The minimum delay between updates, in seconds
+; Default Value: 1
+; Development Value: 1
+; Production Value: 1
+; http://php.net/session.upload-progress.min-freq
 ;session.upload_progress.min_freq = "1"

 [MSSQL]

Modified: php/php-src/trunk/php.ini-production
===================================================================
--- php/php-src/trunk/php.ini-production	2011-08-30 11:08:01 UTC (rev 315769)
+++ php/php-src/trunk/php.ini-production	2011-08-30 11:13:22 UTC (rev 315770)
@@ -1561,13 +1561,50 @@
 ; http://php.net/url-rewriter.tags
 url_rewriter.tags = "a=href,area=href,frame=src,input=src,form=fakeentry"

-;session.upload_progress.enabled = "1"
-;session.upload_progress.cleanup = "1"
+; Enable upload procgress tracking in $_SESSION
+; Default Value: On
+; Development Value: On
+; Production Value: On
+; http://php.net/session.upload-progress.enabled
+;session.upload_progress.enabled = On
+
+; Cleanup the progress information as soon as all POST data has been read
+; (i.e. upload completed).
+; Default Value: On
+; Development Value: On
+; Production Value: On
+; http://php.net/session.upload-progress.cleanup
+;session.upload_progress.cleanup = On
+
+; A prefix used for the upload progress key in $_SESSION
+; Default Value: "upload_progress_"
+; Development Value: "upload_progress_"
+; Production Value: "upload_progress_"
+; http://php.net/session.upload-progress.prefix
 ;session.upload_progress.prefix = "upload_progress_"
+
+; The index name (concatenated with the prefix) in $_SESSION
+; containing the upload progress information
+; Default Value: "PHP_SESSION_UPLOAD_PROGRESS"
+; Development Value: "PHP_SESSION_UPLOAD_PROGRESS"
+; Production Value: "PHP_SESSION_UPLOAD_PROGRESS"
+; http://php.net/session.upload-progress.name
 ;session.upload_progress.name = "PHP_SESSION_UPLOAD_PROGRESS"
+
+; How frequently the upload progress should be updated.
+; Given either in percentages (per-file), or in bytes
+; Default Value: "1%"
+; Development Value: "1%"
+; Production Value: "1%"
+; http://php.net/session.upload-progress.freq
 ;session.upload_progress.freq =  "1%"
+
+; The minimum delay between updates, in seconds
+; Default Value: 1
+; Development Value: 1
+; Production Value: 1
+; http://php.net/session.upload-progress.min-freq
 ;session.upload_progress.min_freq = "1"
-
 [MSSQL]
 ; Allow or prevent persistent links.
 mssql.allow_persistent = On

Modified: phpdoc/en/trunk/reference/session/book.xml
===================================================================
--- phpdoc/en/trunk/reference/session/book.xml	2011-08-30 11:08:01 UTC (rev 315769)
+++ phpdoc/en/trunk/reference/session/book.xml	2011-08-30 11:13:22 UTC (rev 315770)
@@ -80,6 +80,7 @@
  &reference.session.setup;
  &reference.session.constants;
  &reference.session.examples;
+ &reference.session.upload-progress;
  &reference.session.security;
  &reference.session.reference;


Modified: phpdoc/en/trunk/reference/session/ini.xml
===================================================================
--- phpdoc/en/trunk/reference/session/ini.xml	2011-08-30 11:08:01 UTC (rev 315769)
+++ phpdoc/en/trunk/reference/session/ini.xml	2011-08-30 11:13:22 UTC (rev 315770)
@@ -173,37 +173,37 @@
      <entry>Available since PHP 4.0.4.</entry>
     </row>
      <row>
-      <entry>session.upload_progress.enabled</entry>
+      <entry><link linkend="ini.session.upload-progress.enabled">session.upload_progress.enabled</link></entry>
       <entry>"1"</entry>
       <entry>PHP_INI_PERDIR</entry>
       <entry>Available since PHP 5.4.0.</entry>
      </row>
      <row>
-      <entry>session.upload_progress.cleanup</entry>
+      <entry><link linkend="ini.session.upload-progress.cleanup">session.upload_progress.cleanup</link></entry>
       <entry>"1"</entry>
       <entry>PHP_INI_PERDIR</entry>
       <entry>Available since PHP 5.4.0.</entry>
      </row>
      <row>
-      <entry>session.upload_progress.prefix</entry>
+      <entry><link linkend="ini.session.upload-progress.prefix">session.upload_progress.prefix</link></entry>
       <entry>"upload_progress_"</entry>
       <entry>PHP_INI_PERDIR</entry>
       <entry>Available since PHP 5.4.0.</entry>
      </row>
      <row>
-      <entry>session.upload_progress.name</entry>
+      <entry><link linkend="ini.session.upload-progress.name">session.upload_progress.name</link></entry>
       <entry>"PHP_SESSION_UPLOAD_PROGRESS"</entry>
       <entry>PHP_INI_PERDIR</entry>
       <entry>Available since PHP 5.4.0.</entry>
      </row>
      <row>
-      <entry>session.upload_progress.freq</entry>
+      <entry><link linkend="ini.session.upload-progress.freq">session.upload_progress.freq</link></entry>
       <entry>"1%"</entry>
       <entry>PHP_INI_PERDIR</entry>
       <entry>Available since PHP 5.4.0.</entry>
      </row>
      <row>
-      <entry>session.upload_progress.min_freq</entry>
+      <entry><link linkend="ini.session.upload-progress.min-freq">session.upload_progress.min_freq</link></entry>
       <entry>"1"</entry>
       <entry>PHP_INI_PERDIR</entry>
       <entry>Available since PHP 5.4.0.</entry>
@@ -741,6 +741,106 @@
     </note>
    </listitem>
   </varlistentry>
+
+  <varlistentry xml:id="ini.session.upload-progress.enabled">
+   <term>
+    <parameter>session.upload_progress.enabled</parameter>
+    <type>boolean</type>
+   </term>
+   <listitem>
+    <simpara>
+     Enables upload progress tracking, populating the <varname>$_SESSION</varname> variable.
+     Defaults to 1, enabled.
+    </simpara>
+   </listitem>
+  </varlistentry>
+
+  <varlistentry xml:id="ini.session.upload-progress.cleanup">
+   <term>
+    <parameter>session.upload_progress.cleanup</parameter>
+    <type>boolean</type>
+   </term>
+   <listitem>
+    <simpara>
+     Cleanup the progress information as soon as all POST data has been read
+     (i.e. upload completed). Defaults to 1, enabled.
+    </simpara>
+    <note>
+     <simpara>
+      It is highly recommended to keep this feature enabled.
+     </simpara>
+    </note>
+   </listitem>
+  </varlistentry>
+
+  <varlistentry xml:id="ini.session.upload-progress.prefix">
+   <term>
+    <parameter>session.upload_progress.prefix</parameter>
+    <type>string</type>
+   </term>
+   <listitem>
+    <simpara>
+     A prefix used for the upload progress key in the <varname>$_SESSION</varname>.
+     This key will be concatenated with the value of
+     <literal>$_POST[ini_get("session.upload_progress.name")]</literal> to
+     provide a unique index.
+    </simpara>
+    <simpara>
+     Defaults to "upload_progress_".
+    </simpara>
+   </listitem>
+  </varlistentry>
+
+  <varlistentry xml:id="ini.session.upload-progress.name">
+   <term>
+    <parameter>session.upload_progress.name</parameter>
+    <type>string</type>
+   </term>
+   <listitem>
+    <simpara>
+     The name of the key to be used in <varname>$_SESSION</varname> storing
+     the progress information. See also
+     <link linkend="ini.session.upload-progress.prefix">session.upload_progress.prefix</link>.
+    </simpara>
+    <simpara>
+     If <literal>$_POST[ini_get("session.upload_progress.name")]</literal>
+     is not passed available, upload progressing will not be recorded.
+    </simpara>
+    <simpara>
+     Defaults to "PHP_SESSION_UPLOAD_PROGRESS".
+    </simpara>
+   </listitem>
+  </varlistentry>
+
+  <varlistentry xml:id="ini.session.upload-progress.freq">
+   <term>
+    <parameter>session.upload_progress.freq</parameter>
+    <type>mixed</type>
+   </term>
+   <listitem>
+    <simpara>
+     Defines how often the upload progress information should be updated.
+     This can be defined in bytes (i.e. "update progress information after every 100 bytes"), or in percentages (i.e. "update progress information after recieving every 1% of the whole filesize).
+    </simpara>
+    <simpara>
+     Defaults to "1%".
+    </simpara>
+   </listitem>
+  </varlistentry>
+
+  <varlistentry xml:id="ini.session.upload-progress.min-freq">
+   <term>
+    <parameter>session.upload_progress.min-freq</parameter>
+    <type>integer</type>
+   </term>
+   <listitem>
+    <simpara>
+     The minimum delay between updates, in seconds.
+     Defaults to "1" (one second).
+    </simpara>
+   </listitem>
+  </varlistentry>
+
  </variablelist>
  </para>

@@ -753,6 +853,13 @@
   stored and restored.
  </para>

+ <para>
+  Upload progress will not be registered unless
+  session.upload_progress.enabled is enabled, and the
+  $_POST[ini_get("session.upload_progress.name")] variable is set.
+  See <link linkend="session.upload-progress">Session Upload Progress</link> for mor details on this functionality.
+ </para>
+
  <note>
   <para>
    As of PHP 4.0.3, <link

Added: phpdoc/en/trunk/reference/session/upload-progress.xml
===================================================================
--- phpdoc/en/trunk/reference/session/upload-progress.xml	                        (rev 0)
+++ phpdoc/en/trunk/reference/session/upload-progress.xml	2011-08-30 11:13:22 UTC (rev 315770)
@@ -0,0 +1,139 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision: 295472 $ -->
+
+<chapter xml:id="session.upload-progress" xmlns="http://docbook.org/ns/docbook"; xmlns:xlink="http://www.w3.org/1999/xlink";>
+ <title>Session Upload Progress</title>
+
+ <para>
+  When the
+  <link linkend="ini.session.upload-progress.enabled">session.upload_progress.enabled</link>
+  INI option is enabled, PHP will be able to track the upload progress of
+  individual files being uploaded.
+  This information isn't particularly useful for the actual upload request
+  itself, but during the file upload an application can send an POST request
+  to a seperate endpoint (via <acronym>XHR</acronym> for example) to check the
+  status.
+ </para>
+ <para>
+  The upload progress will be available in the <varname>$_SESSION</varname>
+  superglobal when an upload is in progress, and when POSTing a variable of
+  the same name as the
+  <link linkend="ini.session.upload-progress.name">session.upload_progress.name</link>
+  INI setting is set to.
+  When PHP detects such POST requests, it will populate an array in the
+  <varname>$_SESSION</varname>, where the index is a concatenated value of the
+  <link linkend="ini.session.upload-progress.prefix">session.upload_progress.prefix</link>
+  and
+  <link linkend="ini.session.upload-progress.name">session.upload_progress.name</link>
+  INI options.
+  The key is typically retrieved by reading these INI settings, i.e.
+  <informalexample>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$key = ini_get("session.upload_progress.prefix") . ini_get("session.upload-progress.name");
+var_dump($_SESSION[$key]);
+?>
+]]>
+   </programlisting>
+  </informalexample>
+ </para>
+ <para>
+  It is also possible to <emphasis>cancel</emphasis> the currently in-progress file
+  upload, by setting the <literal>$_SESSION[$key]["cancel_upload"]</literal> key to
+  <literal>true</literal>.
+  When uploading multiple files in the same request, this will only cancel the
+  currently in-progress file upload, and pending file uploads, but will not
+  remove successfully completed uploads.
+  When a upload is cancelled like this, the <literal>error</literal> key in
+  <varname>$_FILES</varname> array will be set to
+  <constant>UPLOAD_ERR_EXTENSION</constant>.
+ </para>
+ <para>
+  The
+  <link linkend="ini.session.upload-progress.freq">session.upload_progress.freq</link>
+  and
+  <link linkend="ini.session.upload-progress.min-freq">session.upload_progress.min_freq</link>
+  INI options control how frequent the upload progress information should be
+  recalculated.
+  With a reasonable amount for these two settings, the overhead of this
+  feature is almost non-existing
+ </para>
+ <para>
+  <example>
+   <title>Example information</title>
+   <para>
+    Example of the structure of progress upload array.
+   </para>
+   <programlisting role="html" xml:id="session.upload-progress.example-form">
+<![CDATA[
+<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>
+]]>
+   </programlisting>
+   <para>
+    The data stored in the session will looks like this:
+   </para>
+   <programlisting role="php" xml:id="session.upload-progress.example-array">
+<![CDATA[
+<?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,
+  ),
+ )
+);
+]]>
+   </programlisting>
+  </example>
+ </para>
+
+</chapter>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->
+

Modified: web/php/trunk/include/errors.inc
===================================================================
--- web/php/trunk/include/errors.inc	2011-08-30 11:08:01 UTC (rev 315769)
+++ web/php/trunk/include/errors.inc	2011-08-30 11:13:22 UTC (rev 315770)
@@ -283,7 +283,13 @@
 	'session.cache-expire'			=> 'session.configuration.php#ini.session.cache-expire',
 	'session.use-trans-sid'			=> 'session.configuration.php#ini.session.use-trans-sid',
 	'session.hash-function'			=> 'session.configuration.php#ini.session.hash-function',
-	'session.hash-bits-per-character'=> 'session.configuration.php#ini.session.hash-bits-per-character',
+	'session.hash-bits-per-character'       => 'session.configuration.php#ini.session.hash-bits-per-character',
+	'session.upload-progress.enabled'       => 'session.configuration.php#ini.session.upload-progress.enabled',
+	'session.upload-progress.cleanup'       => 'session.configuration.php#ini.session.upload-progress.cleanup',
+	'session.upload-progress.prefix'        => 'session.configuration.php#ini.session.upload-progress.prefix',
+	'session.upload-progress.name'          => 'session.configuration.php#ini.session.upload-progress.name',
+	'session.upload-progress.freq'          => 'session.configuration.php#ini.session.upload-progress.freq',
+	'session.upload-progress.min-freq'      => 'session.configuration.php#ini.session.upload-progress.min-freq',
 	'url-rewriter.tags'				=> 'session.configuration.php#ini.url-rewriter.tags',
 	'assert.active'					=> 'info.configuration.php#ini.assert.active',
 	'assert.warning'				=> 'info.configuration.php#ini.assert.warning',
-- 
PHP CVS Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php

Reply via email to