aidan Tue Oct 12 04:45:27 2004 EDT
Modified files:
/phpdoc/en/features file-upload.xml
Log:
Revised
http://cvs.php.net/diff.php/phpdoc/en/features/file-upload.xml?r1=1.79&r2=1.80&ty=u
Index: phpdoc/en/features/file-upload.xml
diff -u phpdoc/en/features/file-upload.xml:1.79 phpdoc/en/features/file-upload.xml:1.80
--- phpdoc/en/features/file-upload.xml:1.79 Fri Sep 10 09:45:23 2004
+++ phpdoc/en/features/file-upload.xml Tue Oct 12 04:45:26 2004
@@ -1,21 +1,23 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.79 $ -->
+<!-- $Revision: 1.80 $ -->
<chapter id="features.file-upload">
<title>Handling file uploads</title>
<sect1 id="features.file-upload.post-method">
<title>POST method uploads</title>
-
+ <simpara>
+ This feature lets people upload both text and binary files.
+ With PHP's authentication and file manipulation functions,
+ you have full control over who is allowed to upload and
+ what is to be done with the file once it has been uploaded.
+ </simpara>
<simpara>
PHP is capable of receiving file uploads from any RFC-1867
compliant browser (which includes <productname>Netscape Navigator 3</productname>
or later, <productname>Microsoft Internet Explorer 3</productname>
- with a patch from Microsoft, or
- later without a patch). This feature lets people upload both text
- and binary files. With PHP's authentication and file manipulation
- functions, you have full control over who is allowed to upload and
- what is to be done with the file once it has been uploaded.
+ with a patch from Microsoft, or later without a patch).
</simpara>
+
<note>
<title>Related Configurations Note</title>
<para>
@@ -27,70 +29,70 @@
in &php.ini;
</para>
</note>
+
<para>
- Note that PHP also supports PUT-method file uploads as used by
+ PHP also supports PUT-method file uploads as used by
<productname>Netscape Composer</productname> and W3C's
<productname>Amaya</productname> clients. See the <link
linkend="features.file-upload.put-method">PUT Method
Support</link> for more details.
</para>
- <para>
- A file upload screen can be built by creating a special form which
- looks something like this:
- </para>
+
<para>
<example>
<title>File Upload Form</title>
+ <para>
+ A file upload screen can be built by creating a special form which
+ looks something like this:
+ </para>
<programlisting role="html">
+ <!-- The HTML comments in this example code are stripped.
+ This needs to be fixed in livedocs. -->
<![CDATA[
-<form enctype="multipart/form-data" action="_URL_" method="post">
- <input type="hidden" name="MAX_FILE_SIZE" value="30000" />
- Send this file: <input name="userfile" type="file" />
- <input type="submit" value="Send File" />
+<!-- The data encoding type, enctype, MUST be specified as below -->
+<form enctype="multipart/form-data" action="__URL__" method="POST">
+ <!-- MAX_FILE_SIZE must precede the file input field -->
+ <input type="hidden" name="MAX_FILE_SIZE" value="30000" />
+ <!-- Name of input element determines name in $_FILES array -->
+ Send this file: <input name="userfile" type="file" />
+ <input type="submit" value="Send File" />
</form>
]]>
</programlisting>
- </example>
- </para>
- <para>
- The "_URL_" in the above example should be replaced, and point to a PHP
- file. The <literal>MAX_FILE_SIZE</literal> hidden field (measured in bytes) must
precede
- the file input field, and its value is the maximum filesize accepted.
- Also, be sure your file upload form has
- <literal>enctype="multipart/form-data"</literal> otherwise the file
- upload will not work.
- <warning>
<para>
- The <literal>MAX_FILE_SIZE</literal> is advisory to the browser, although PHP
also checks
- it. Changing this on the browser side is quite easy, so you can never
- rely on files with a greater size being blocked by this feature. The
- PHP-settings for maximum-size, however, cannot be fooled. You should add
- the <literal>MAX_FILE_SIZE</literal> form variable anyway as it saves users the
trouble of
- waiting for a big file being transferred only to find that it was too
- big and the transfer actually failed.
+ The <literal>__URL__</literal> in the above example should be replaced,
+ and point to a PHP file.
</para>
- </warning>
+ <para>
+ The <literal>MAX_FILE_SIZE</literal> hidden field (measured in bytes) must
+ precede the file input field, and its value is the maximum filesize accepted.
+ This is an advisory to the browser, PHP also checks it.
+ Fooling this setting on the browser side is quite easy, so never rely
+ on files with a greater size being blocked by this feature.
+ The PHP settings for maximum-size, however, cannot be fooled.
+ This form element should always be used as it
+ saves users the trouble of waiting for a big file being transferred only
+ to find that it was too big and the transfer failed.
+ </para>
+ <para>
+ Be sure your file upload form has attribute
<literal>enctype="multipart/form-data"</literal>
+ otherwise the file upload will not work.
+ </para>
+ </example>
</para>
<para>
- The Variables defined for uploaded files differs depending on
- the PHP version and configuration. The autoglobal
- <link linkend="reserved.variables.files">$_FILES</link>
- exists as of PHP 4.1.0 The <varname>$HTTP_POST_FILES</varname> array
- has existed since PHP 4.0.0. These arrays will contain all
- your uploaded file information. Using <varname>$_FILES</varname>
- is preferred. If the PHP directive
- <link linkend="ini.register-globals">register_globals</link> is
- <emphasis>on</emphasis>, related variable names will also exist.
- <link linkend="ini.register-globals">register_globals</link>
- defaults to <emphasis>off</emphasis> as of PHP
- <ulink url="&url.php.release4.2.0;">4.2.0</ulink>.
+ The global <link linkend="reserved.variables.files">$_FILES</link>
+ exists as of PHP 4.1.0 (Use <varname>$HTTP_POST_FILES</varname>
+ instead if using an earlier version).
+ These arrays will contain all the uploaded file information.
</para>
+
<para>
The contents of <link linkend="reserved.variables.files">$_FILES</link>
- from our example script is as follows. Note that this assumes the use of
+ from the example form is as follows. Note that this assumes the use of
the file upload name <emphasis>userfile</emphasis>, as used in the example
- script above. This can be any name.
+ script above. This can be any name.
<variablelist>
<varlistentry>
<term><varname>$_FILES['userfile']['name']</varname></term>
@@ -107,7 +109,7 @@
The mime type of the file, if the browser provided this
information. An example would be
<literal>"image/gif"</literal>.
- </para>
+ </para>
</listitem>
</varlistentry>
<varlistentry>
@@ -132,35 +134,15 @@
<listitem>
<para>
The <link linkend="features.file-upload.errors">error code</link>
- associated with this file upload. <emphasis>['error']</emphasis>
- was added in PHP 4.2.0
+ associated with this file upload. This element was added in PHP 4.2.0
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
- <note>
- <para>
- In PHP versions prior to 4.1.0 this was named
- <varname>$HTTP_POST_FILES</varname> and it's not an
- <link linkend="language.variables.superglobals">autoglobal</link>
- variable like <varname>$_FILES</varname> is. PHP 3 does not
- support <varname>$HTTP_POST_FILES</varname>.
- </para>
- </note>
- <para>
- When <link linkend="ini.register-globals">register_globals</link>
- is turned <emphasis>on</emphasis> in &php.ini;, additional
- variables are available. For example,
- <varname>$userfile_name</varname> will equal
- <varname>$_FILES['userfile']['name']</varname>,
- <varname>$userfile_type</varname> will equal
- <varname>$_FILES['userfile']['type']</varname>, etc. Keep in mind
- that as of PHP 4.2.0, register_globals defaults to off. It's
- preferred to not rely on this directive.
- </para>
+
<para>
- Files will by default be stored in the server's default temporary
+ Files will, by default be stored in the server's default temporary
directory, unless another location has been given with the <link
linkend="ini.upload-tmp-dir">upload_tmp_dir</link> directive in
&php.ini;. The server's default directory can
@@ -186,15 +168,16 @@
$uploaddir = '/var/www/uploads/';
$uploadfile = $uploaddir . basename($_FILES['userfile']['name']);
-print "<pre>";
+echo '<pre>';
if (move_uploaded_file($_FILES['userfile']['tmp_name'], $uploadfile)) {
- print "File is valid, and was successfully uploaded. ";
- print "Here's some more debugging info:\n";
- print_r($_FILES);
+ echo "File is valid, and was successfully uploaded.\n";
} else {
- print "Possible file upload attack! Here's some debugging info:\n";
- print_r($_FILES);
+ echo "Possible file upload attack!\n";
}
+
+echo 'Here is some more debugging info:';
+print_r($_FILES);
+
print "</pre>";
?>
@@ -205,7 +188,7 @@
<simpara>
The PHP script which receives the uploaded file should implement
whatever logic is necessary for determining what should be done
- with the uploaded file. You can, for example, use the
+ with the uploaded file. You can, for example, use the
<varname>$_FILES['userfile']['size']</varname> variable
to throw away any files that are either too small or too big. You
could use the
@@ -219,8 +202,8 @@
</simpara>
<simpara>
If no file is selected for upload in your form, PHP will return
- <varname>$_FILES['userfile']['size']</varname> as 0, and
<varname>$_FILES['userfile']['tmp_name']</varname> as
- none.
+ <varname>$_FILES['userfile']['size']</varname> as 0, and
+ <varname>$_FILES['userfile']['tmp_name']</varname> as none.
</simpara>
<simpara>
The file will be deleted from the temporary directory at the end
@@ -233,8 +216,8 @@
<simpara>
Since PHP 4.2.0, PHP returns an appropriate error code along with the
file array. The error code can be found in the
- <emphasis>['error']</emphasis> segment of the file array that is created
- during the file upload by PHP. In other words, the error might be
+ <literal>error</literal> segment of the file array that is created
+ during the file upload by PHP. In other words, the error might be
found in <varname>$_FILES['userfile']['error']</varname>.
</simpara>
<para>
