mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-17 01:18:55 +00:00
7a2bcc0af2
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@210381 c90b9560-bf6c-de11-be94-00142212c4b1
588 lines
21 KiB
XML
588 lines
21 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!-- $Revision: 1.88 $ -->
|
|
<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).
|
|
</simpara>
|
|
|
|
<note>
|
|
<title>Related Configurations Note</title>
|
|
<para>
|
|
See also the <link linkend="ini.file-uploads">file_uploads</link>,
|
|
<link linkend="ini.upload-max-filesize">upload_max_filesize</link>,
|
|
<link linkend="ini.upload-tmp-dir">upload_tmp_dir</link>,
|
|
<link linkend="ini.post-max-size">post_max_size</link> and
|
|
<link linkend="ini.max-input-time">max_input_time</link> directives
|
|
in &php.ini;
|
|
</para>
|
|
</note>
|
|
|
|
<para>
|
|
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>
|
|
<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[
|
|
<!-- 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>
|
|
<para>
|
|
The <literal>__URL__</literal> in the above example should be replaced,
|
|
and point to a PHP file.
|
|
</para>
|
|
<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>
|
|
</example>
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
Be sure your file upload form has attribute <literal>enctype="multipart/form-data"</literal>
|
|
otherwise the file upload will not work.
|
|
</para>
|
|
</note>
|
|
|
|
<para>
|
|
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 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.
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><varname>$_FILES['userfile']['name']</varname></term>
|
|
<listitem>
|
|
<para>
|
|
The original name of the file on the client machine.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><varname>$_FILES['userfile']['type']</varname></term>
|
|
<listitem>
|
|
<para>
|
|
The mime type of the file, if the browser provided this
|
|
information. An example would be
|
|
<literal>"image/gif"</literal>. This mime type is however
|
|
not checked on the PHP side and therefore don't take its value
|
|
for granted.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><varname>$_FILES['userfile']['size']</varname></term>
|
|
<listitem>
|
|
<para>
|
|
The size, in bytes, of the uploaded file.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><varname>$_FILES['userfile']['tmp_name']</varname></term>
|
|
<listitem>
|
|
<para>
|
|
The temporary filename of the file in which the uploaded file
|
|
was stored on the server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><varname>$_FILES['userfile']['error']</varname></term>
|
|
<listitem>
|
|
<para>
|
|
The <link linkend="features.file-upload.errors">error code</link>
|
|
associated with this file upload. This element was added in PHP 4.2.0
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
|
|
<para>
|
|
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
|
|
be changed by setting the environment variable
|
|
<envar>TMPDIR</envar> in the environment in which PHP runs.
|
|
Setting it using <function>putenv</function> from within a PHP
|
|
script will not work. This environment variable can also be used
|
|
to make sure that other operations are working on uploaded files,
|
|
as well.
|
|
<example>
|
|
<title>Validating file uploads</title>
|
|
<para>
|
|
See also the function entries for <function>is_uploaded_file</function>
|
|
and <function>move_uploaded_file</function> for further information. The
|
|
following example will process the file upload that came from a form.
|
|
</para>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
// In PHP versions earlier than 4.1.0, $HTTP_POST_FILES should be used instead
|
|
// of $_FILES.
|
|
|
|
$uploaddir = '/var/www/uploads/';
|
|
$uploadfile = $uploaddir . basename($_FILES['userfile']['name']);
|
|
|
|
echo '<pre>';
|
|
if (move_uploaded_file($_FILES['userfile']['tmp_name'], $uploadfile)) {
|
|
echo "File is valid, and was successfully uploaded.\n";
|
|
} else {
|
|
echo "Possible file upload attack!\n";
|
|
}
|
|
|
|
echo 'Here is some more debugging info:';
|
|
print_r($_FILES);
|
|
|
|
print "</pre>";
|
|
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<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
|
|
<varname>$_FILES['userfile']['size']</varname> variable
|
|
to throw away any files that are either too small or too big. You
|
|
could use the
|
|
<varname>$_FILES['userfile']['type']</varname> variable
|
|
to throw away any files that didn't match a certain type criteria, but
|
|
use this only as first of a series of checks, because this value
|
|
is completely under the control of the client and not checked on the PHP
|
|
side.
|
|
As of PHP 4.2.0, you could use <varname>$_FILES['userfile']['error']</varname>
|
|
and plan your logic according to the <link
|
|
linkend="features.file-upload.errors">error codes</link>.
|
|
Whatever the logic, you should either delete the file from the
|
|
temporary directory or move it elsewhere.
|
|
</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.
|
|
</simpara>
|
|
<simpara>
|
|
The file will be deleted from the temporary directory at the end
|
|
of the request if it has not been moved away or renamed.
|
|
</simpara>
|
|
<example>
|
|
<title>Uploading array of files</title>
|
|
<para>
|
|
PHP supports <link linkend="faq.html.arrays">HTML array feature</link>
|
|
even with files.
|
|
</para>
|
|
<programlisting role="html">
|
|
<![CDATA[
|
|
<form action="" method="post" enctype="multipart/form-data">
|
|
<p>Pictures:
|
|
<input type="file" name="pictures[]" />
|
|
<input type="file" name="pictures[]" />
|
|
<input type="file" name="pictures[]" />
|
|
<input type="submit" value="Send" />
|
|
</p>
|
|
</form>
|
|
]]>
|
|
</programlisting>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
foreach ($_FILES["pictures"]["error"] as $key => $error) {
|
|
if ($error == UPLOAD_ERR_OK) {
|
|
$tmp_name = $_FILES["pictures"]["tmp_name"][$key];
|
|
$name = $_FILES["pictures"]["name"][$key];
|
|
move_uploaded_file($tmp_name, "data/$name");
|
|
}
|
|
}
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</sect1>
|
|
|
|
<sect1 id="features.file-upload.errors">
|
|
<title>Error Messages Explained</title>
|
|
<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
|
|
<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>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><constant>UPLOAD_ERR_OK</constant></term>
|
|
<listitem>
|
|
<para>
|
|
Value: 0; There is no error, the file uploaded with success.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><constant>UPLOAD_ERR_INI_SIZE</constant></term>
|
|
<listitem>
|
|
<para>
|
|
Value: 1; The uploaded file exceeds the
|
|
<link linkend="ini.upload-max-filesize">upload_max_filesize</link>
|
|
directive in &php.ini;.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><constant>UPLOAD_ERR_FORM_SIZE</constant></term>
|
|
<listitem>
|
|
<para>
|
|
Value: 2; The uploaded file exceeds the <emphasis>MAX_FILE_SIZE</emphasis>
|
|
directive that was specified in the HTML form.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><constant>UPLOAD_ERR_PARTIAL</constant></term>
|
|
<listitem>
|
|
<para>
|
|
Value: 3; The uploaded file was only partially uploaded.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><constant>UPLOAD_ERR_NO_FILE</constant></term>
|
|
<listitem>
|
|
<para>
|
|
Value: 4; No file was uploaded.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><constant>UPLOAD_ERR_NO_TMP_DIR</constant></term>
|
|
<listitem>
|
|
<para>
|
|
Value: 6; Missing a temporary folder. Introduced in PHP 4.3.10 and PHP
|
|
5.0.3.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><constant>UPLOAD_ERR_CANT_WRITE</constant></term>
|
|
<listitem>
|
|
<para>
|
|
Value: 7; Failed to write file to disk. Introduced in PHP 5.1.0.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
<note>
|
|
<para>
|
|
These became PHP constants in PHP 4.3.0.
|
|
</para>
|
|
</note>
|
|
</sect1>
|
|
|
|
<sect1 id="features.file-upload.common-pitfalls">
|
|
<title>Common Pitfalls</title>
|
|
<simpara>
|
|
The <literal>MAX_FILE_SIZE</literal> item cannot specify a file size
|
|
greater than the file size that has been set in the <link
|
|
linkend="ini.upload-max-filesize">upload_max_filesize</link> ini-setting.
|
|
The default is 2 Megabytes.
|
|
</simpara>
|
|
<simpara>
|
|
If a memory limit is enabled, a larger <link
|
|
linkend="ini.memory-limit">memory_limit</link> may be needed. Make
|
|
sure you set <link linkend="ini.memory-limit">memory_limit</link>
|
|
large enough.
|
|
</simpara>
|
|
<simpara>
|
|
If <link linkend="ini.max-execution-time">max_execution_time</link>
|
|
is set too small, script execution may be exceeded by the value. Make
|
|
sure you set <literal>max_execution_time</literal> large enough.
|
|
</simpara>
|
|
<note>
|
|
<simpara>
|
|
<link linkend="ini.max-execution-time">max_execution_time</link> only
|
|
affects the execution time of the script itself. Any time spent
|
|
on activity that happens outside the execution of the script
|
|
such as system calls using <function>system</function>, the
|
|
<function>sleep</function> function, database queries, time taken by
|
|
the file upload process, etc. is not included when determining the maximum
|
|
time that the script has been running.
|
|
</simpara>
|
|
</note>
|
|
<warning>
|
|
<simpara>
|
|
<link linkend="ini.max-input-time">max_input_time</link> sets the maximum
|
|
time, in seconds, the script is allowed to receive input; this includes
|
|
file uploads. For large or multiple files, or users on slower connections,
|
|
the default of <literal>60 seconds</literal> may be exceeded.
|
|
</simpara>
|
|
</warning>
|
|
<simpara>
|
|
If <link linkend="ini.post-max-size">post_max_size</link> is set too
|
|
small, large files cannot be uploaded. Make sure you set
|
|
<literal>post_max_size</literal> large enough.
|
|
</simpara>
|
|
<simpara>
|
|
Not validating which file you operate on may mean that users can access
|
|
sensitive information in other directories.
|
|
</simpara>
|
|
<simpara>
|
|
Please note that the <productname>CERN httpd</productname> seems to strip off everything
|
|
starting at the first whitespace in the content-type mime header
|
|
it gets from the client. As long as this is the case, <productname>CERN httpd</productname>
|
|
will not support the file upload feature.
|
|
</simpara>
|
|
<simpara>
|
|
Due to the large amount of directory listing styles we cannot guarantee
|
|
that files with exotic names (like containing spaces) are handled properly.
|
|
</simpara>
|
|
<simpara>
|
|
A developer may not mix normal input fields and file upload fields in the same
|
|
form variable (by using an input name like <literal>foo[]</literal>).
|
|
</simpara>
|
|
</sect1>
|
|
|
|
<sect1 id="features.file-upload.multiple">
|
|
<title>Uploading multiple files</title>
|
|
<simpara>
|
|
Multiple files can be uploaded using different
|
|
<literal>name</literal> for <literal>input</literal>.
|
|
</simpara>
|
|
<simpara>
|
|
It is also possible to upload multiple files simultaneously and
|
|
have the information organized automatically in arrays for you. To
|
|
do so, you need to use the same array submission syntax in the
|
|
HTML form as you do with multiple selects and checkboxes:
|
|
</simpara>
|
|
<note>
|
|
<para>
|
|
Support for multiple file uploads was added in PHP 3.0.10.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
<example>
|
|
<title>Uploading multiple files</title>
|
|
<programlisting role="html">
|
|
<![CDATA[
|
|
<form action="file-upload.php" method="post" enctype="multipart/form-data">
|
|
Send these files:<br />
|
|
<input name="userfile[]" type="file" /><br />
|
|
<input name="userfile[]" type="file" /><br />
|
|
<input type="submit" value="Send files" />
|
|
</form>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<simpara>
|
|
When the above form is submitted, the arrays
|
|
<varname>$_FILES['userfile']</varname>,
|
|
<varname>$_FILES['userfile']['name']</varname>, and
|
|
<varname>$_FILES['userfile']['size']</varname> will be
|
|
initialized (as well as in <varname>$HTTP_POST_FILES</varname> for PHP versions prior
|
|
to 4.1.0).
|
|
When
|
|
<link linkend="ini.register-globals">register_globals</link> is on, globals for uploaded
|
|
files are also initialized. Each of these will be a numerically
|
|
indexed array of the appropriate values for the submitted files.
|
|
</simpara>
|
|
<simpara>
|
|
For instance, assume that the filenames
|
|
<filename>/home/test/review.html</filename> and
|
|
<filename>/home/test/xwp.out</filename> are submitted. In this
|
|
case, <varname>$_FILES['userfile']['name'][0]</varname>
|
|
would contain the value <filename>review.html</filename>, and
|
|
<varname>$_FILES['userfile']['name'][1]</varname> would
|
|
contain the value <filename>xwp.out</filename>. Similarly,
|
|
<varname>$_FILES['userfile']['size'][0]</varname> would
|
|
contain <filename>review.html</filename>'s file size, and so forth.
|
|
</simpara>
|
|
<simpara>
|
|
<varname>$_FILES['userfile']['name'][0]</varname>,
|
|
<varname>$_FILES['userfile']['tmp_name'][0]</varname>,
|
|
<varname>$_FILES['userfile']['size'][0]</varname>, and
|
|
<varname>$_FILES['userfile']['type'][0]</varname> are
|
|
also set.
|
|
</simpara>
|
|
</sect1>
|
|
|
|
<sect1 id="features.file-upload.put-method">
|
|
<title>PUT method support</title>
|
|
<para>
|
|
PHP provides support for the HTTP PUT method used by some clients to store
|
|
files on a server.
|
|
PUT requests are much simpler than a file upload using POST requests
|
|
and they look something like this:
|
|
<informalexample>
|
|
<programlisting role="HTTP">
|
|
<![CDATA[
|
|
PUT /path/filename.html HTTP/1.1
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
This would normally mean that the remote client would like to save
|
|
the content that follows as: <filename>/path/filename.html</filename> in your web tree.
|
|
It is obviously not a good idea for Apache or PHP to automatically
|
|
let everybody overwrite any files in your web tree. So, to handle
|
|
such a request you have to first tell your web server that you
|
|
want a certain PHP script to handle the request. In Apache you do
|
|
this with the <emphasis>Script</emphasis> directive. It can be
|
|
placed almost anywhere in your Apache configuration file. A
|
|
common place is inside a <Directory> block or perhaps inside
|
|
a <Virtualhost> block. A line like this would do the trick:
|
|
<informalexample>
|
|
<programlisting>
|
|
<![CDATA[
|
|
Script PUT /put.php
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<simpara>
|
|
This tells Apache to send all PUT requests for URIs that match the
|
|
context in which you put this line to the put.php script. This
|
|
assumes, of course, that you have PHP enabled for the .php
|
|
extension and PHP is active. The destination resource for all PUT
|
|
requests to this script has to be the script itself, not a filename the
|
|
uploaded file should have.
|
|
</simpara>
|
|
<simpara>
|
|
With PHP 4 and following you would then do something like the following in
|
|
your put.php. This would copy the contents of the uploaded file to the
|
|
file <filename>myputfile.ext</filename> on the server.
|
|
You would probably want to perform some checks and/or
|
|
authenticate the user before performing this file copy.
|
|
</simpara>
|
|
<para>
|
|
<example>
|
|
<title>Saving HTTP PUT files with PHP 4</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
/* PUT data comes in on the stdin stream */
|
|
$putdata = fopen("php://input", "r");
|
|
|
|
/* Open a file for writing */
|
|
$fp = fopen("myputfile.ext", "w");
|
|
|
|
/* Read the data 1 KB at a time
|
|
and write to the file */
|
|
while ($data = fread($putdata, 1024))
|
|
fwrite($fp, $data);
|
|
|
|
/* Close the streams */
|
|
fclose($fp);
|
|
fclose($putdata);
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<note>
|
|
<para>
|
|
All documentation below applies to PHP 3 only.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
<example>
|
|
<title>Saving HTTP PUT files with PHP 3</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php copy($PHP_UPLOADED_FILE_NAME, $DOCUMENT_ROOT . $REQUEST_URI); ?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<simpara>
|
|
The only
|
|
trick here is that when PHP sees a PUT-method request it stores
|
|
the uploaded file in a temporary file just like those handled by
|
|
the <link
|
|
linkend="features.file-upload.post-method">POST-method</link>.
|
|
When the request ends, this temporary file is deleted. So, your
|
|
PUT handling PHP script has to copy that file somewhere. The
|
|
filename of this temporary file is in the <varname>$PHP_PUT_FILENAME</varname>
|
|
variable, and you can see the suggested destination filename in
|
|
the <varname>$REQUEST_URI</varname> (may vary on non-Apache web servers). This
|
|
destination filename is the one that the remote client specified.
|
|
You do not have to listen to this client. You could, for example,
|
|
copy all uploaded files to a special uploads directory.
|
|
</simpara>
|
|
</sect1>
|
|
|
|
</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:"../../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
|
|
-->
|