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
