<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>POST method uploads</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="features.file-upload.html">Handling file uploads</a></div>
<div class="next" style="text-align: right; float: right;"><a href="features.file-upload.errors.html">Error Messages Explained</a></div>
<div class="up"><a href="features.file-upload.html">Handling file uploads</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="features.file-upload.post-method" class="sect1">
<h2 class="title">POST method uploads</h2>
<p class="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.
</p>
<p class="simpara">
PHP is capable of receiving file uploads from any RFC-1867
compliant browser.
</p>
<blockquote class="note"><p><strong class="note">Note</strong>:
<strong>Related Configurations Note</strong><br />
<p class="para">
See also the <a href="ini.core.html#ini.file-uploads" class="link">file_uploads</a>,
<a href="ini.core.html#ini.upload-max-filesize" class="link">upload_max_filesize</a>,
<a href="ini.core.html#ini.upload-tmp-dir" class="link">upload_tmp_dir</a>,
<a href="ini.core.html#ini.post-max-size" class="link">post_max_size</a> and
<a href="info.configuration.html#ini.max-input-time" class="link">max_input_time</a> directives
in <var class="filename">php.ini</var>
</p>
</p></blockquote>
<p class="para">
PHP also supports PUT-method file uploads as used by
<span class="productname">Netscape Composer</span> and W3C's
<span class="productname">Amaya</span> clients. See the <a href="features.file-upload.put-method.html" class="link">PUT Method
Support</a> for more details.
</p>
<p class="para">
<div class="example" id="example-356">
<p><strong>Example #1 File Upload Form</strong></p>
<div class="example-contents"><p>
A file upload screen can be built by creating a special form which
looks something like this:
</p></div>
<div class="example-contents">
<div class="htmlcode"><pre class="htmlcode"><!-- 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></pre>
</div>
</div>
<div class="example-contents"><p>
The <em>__URL__</em> in the above example should be replaced,
and point to a PHP file.
</p></div>
<div class="example-contents"><p>
The <em>MAX_FILE_SIZE</em> hidden field (measured in bytes) must
precede the file input field, and its value is the maximum filesize accepted by PHP.
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
large and the transfer failed. Keep in mind: fooling this setting on the
browser side is quite easy, so never rely on files with a greater size
being blocked by this feature. It is merely a convenience feature for
users on the client side of the application. The PHP settings (on the server
side) for maximum-size, however, cannot be fooled.
</p></div>
</div>
</p>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
Be sure your file upload form has attribute <em>enctype="multipart/form-data"</em>
otherwise the file upload will not work.
</p>
</p></blockquote>
<p class="para">
The global <var class="varname"><var class="varname"><a href="reserved.variables.files.html" class="classname">$_FILES</a></var></var>
exists as of PHP 4.1.0 (Use <var class="varname"><var class="varname">$HTTP_POST_FILES</var></var>
instead if using an earlier version).
These arrays will contain all the uploaded file information.
</p>
<p class="para">
The contents of <var class="varname"><var class="varname"><a href="reserved.variables.files.html" class="classname">$_FILES</a></var></var>
from the example form is as follows. Note that this assumes the use of
the file upload name <em class="emphasis">userfile</em>, as used in the example
script above. This can be any name.
<dl>
<dt>
<span class="term"><var class="varname"><var class="varname"><a href="reserved.variables.files.html" class="classname">$_FILES['userfile']['name']</a></var></var></span>
<dd>
<p class="para">
The original name of the file on the client machine.
</p>
</dd>
</dt>
<dt>
<span class="term"><var class="varname"><var class="varname"><a href="reserved.variables.files.html" class="classname">$_FILES['userfile']['type']</a></var></var></span>
<dd>
<p class="para">
The mime type of the file, if the browser provided this
information. An example would be
<em>"image/gif"</em>. This mime type is however
not checked on the PHP side and therefore don't take its value
for granted.
</p>
</dd>
</dt>
<dt>
<span class="term"><var class="varname"><var class="varname"><a href="reserved.variables.files.html" class="classname">$_FILES['userfile']['size']</a></var></var></span>
<dd>
<p class="para">
The size, in bytes, of the uploaded file.
</p>
</dd>
</dt>
<dt>
<span class="term"><var class="varname"><var class="varname"><a href="reserved.variables.files.html" class="classname">$_FILES['userfile']['tmp_name']</a></var></var></span>
<dd>
<p class="para">
The temporary filename of the file in which the uploaded file
was stored on the server.
</p>
</dd>
</dt>
<dt>
<span class="term"><var class="varname"><var class="varname"><a href="reserved.variables.files.html" class="classname">$_FILES['userfile']['error']</a></var></var></span>
<dd>
<p class="para">
The <a href="features.file-upload.errors.html" class="link">error code</a>
associated with this file upload. This element was added in PHP 4.2.0
</p>
</dd>
</dt>
</dl>
</p>
<p class="para">
Files will, by default be stored in the server's default temporary
directory, unless another location has been given with the <a href="ini.core.html#ini.upload-tmp-dir" class="link">upload_tmp_dir</a> directive in
<var class="filename">php.ini</var>. The server's default directory can
be changed by setting the environment variable
<span class="envar">TMPDIR</span> in the environment in which PHP runs.
Setting it using <span class="function"><a href="function.putenv.html" class="function">putenv()</a></span> 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.
<div class="example" id="example-357">
<p><strong>Example #2 Validating file uploads</strong></p>
<div class="example-contents"><p>
See also the function entries for <span class="function"><a href="function.is-uploaded-file.html" class="function">is_uploaded_file()</a></span>
and <span class="function"><a href="function.move-uploaded-file.html" class="function">move_uploaded_file()</a></span> for further information. The
following example will process the file upload that came from a form.
</p></div>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #FF8000">// In PHP versions earlier than 4.1.0, $HTTP_POST_FILES should be used instead<br />// of $_FILES.<br /><br /></span><span style="color: #0000BB">$uploaddir </span><span style="color: #007700">= </span><span style="color: #DD0000">'/var/www/uploads/'</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$uploadfile </span><span style="color: #007700">= </span><span style="color: #0000BB">$uploaddir </span><span style="color: #007700">. </span><span style="color: #0000BB">basename</span><span style="color: #007700">(</span><span style="color: #0000BB">$_FILES</span><span style="color: #007700">[</span><span style="color: #DD0000">'userfile'</span><span style="color: #007700">][</span><span style="color: #DD0000">'name'</span><span style="color: #007700">]);<br /><br />echo </span><span style="color: #DD0000">'<pre>'</span><span style="color: #007700">;<br />if (</span><span style="color: #0000BB">move_uploaded_file</span><span style="color: #007700">(</span><span style="color: #0000BB">$_FILES</span><span style="color: #007700">[</span><span style="color: #DD0000">'userfile'</span><span style="color: #007700">][</span><span style="color: #DD0000">'tmp_name'</span><span style="color: #007700">], </span><span style="color: #0000BB">$uploadfile</span><span style="color: #007700">)) {<br /> echo </span><span style="color: #DD0000">"File is valid, and was successfully uploaded.\n"</span><span style="color: #007700">;<br />} else {<br /> echo </span><span style="color: #DD0000">"Possible file upload attack!\n"</span><span style="color: #007700">;<br />}<br /><br />echo </span><span style="color: #DD0000">'Here is some more debugging info:'</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">print_r</span><span style="color: #007700">(</span><span style="color: #0000BB">$_FILES</span><span style="color: #007700">);<br /><br />print </span><span style="color: #DD0000">"</pre>"</span><span style="color: #007700">;<br /><br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
<p class="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
<var class="varname"><var class="varname"><a href="reserved.variables.files.html" class="classname">$_FILES['userfile']['size']</a></var></var> variable
to throw away any files that are either too small or too big. You
could use the
<var class="varname"><var class="varname"><a href="reserved.variables.files.html" class="classname">$_FILES['userfile']['type']</a></var></var> 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 <var class="varname"><var class="varname"><a href="reserved.variables.files.html" class="classname">$_FILES['userfile']['error']</a></var></var>
and plan your logic according to the <a href="features.file-upload.errors.html" class="link">error codes</a>.
Whatever the logic, you should either delete the file from the
temporary directory or move it elsewhere.
</p>
<p class="simpara">
If no file is selected for upload in your form, PHP will return
<var class="varname"><var class="varname"><a href="reserved.variables.files.html" class="classname">$_FILES['userfile']['size']</a></var></var> as 0, and
<var class="varname"><var class="varname"><a href="reserved.variables.files.html" class="classname">$_FILES['userfile']['tmp_name']</a></var></var> as none.
</p>
<p class="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.
</p>
<div class="example" id="example-358">
<p><strong>Example #3 Uploading array of files</strong></p>
<div class="example-contents"><p>
PHP supports <a href="faq.html.html#faq.html.arrays" class="link">HTML array feature</a>
even with files.
</p></div>
<div class="example-contents">
<div class="htmlcode"><pre class="htmlcode"><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></pre>
</div>
</div>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #007700">foreach (</span><span style="color: #0000BB">$_FILES</span><span style="color: #007700">[</span><span style="color: #DD0000">"pictures"</span><span style="color: #007700">][</span><span style="color: #DD0000">"error"</span><span style="color: #007700">] as </span><span style="color: #0000BB">$key </span><span style="color: #007700">=> </span><span style="color: #0000BB">$error</span><span style="color: #007700">) {<br /> if (</span><span style="color: #0000BB">$error </span><span style="color: #007700">== </span><span style="color: #0000BB">UPLOAD_ERR_OK</span><span style="color: #007700">) {<br /> </span><span style="color: #0000BB">$tmp_name </span><span style="color: #007700">= </span><span style="color: #0000BB">$_FILES</span><span style="color: #007700">[</span><span style="color: #DD0000">"pictures"</span><span style="color: #007700">][</span><span style="color: #DD0000">"tmp_name"</span><span style="color: #007700">][</span><span style="color: #0000BB">$key</span><span style="color: #007700">];<br /> </span><span style="color: #0000BB">$name </span><span style="color: #007700">= </span><span style="color: #0000BB">$_FILES</span><span style="color: #007700">[</span><span style="color: #DD0000">"pictures"</span><span style="color: #007700">][</span><span style="color: #DD0000">"name"</span><span style="color: #007700">][</span><span style="color: #0000BB">$key</span><span style="color: #007700">];<br /> </span><span style="color: #0000BB">move_uploaded_file</span><span style="color: #007700">(</span><span style="color: #0000BB">$tmp_name</span><span style="color: #007700">, </span><span style="color: #DD0000">"data/</span><span style="color: #0000BB">$name</span><span style="color: #DD0000">"</span><span style="color: #007700">);<br /> }<br />}<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
<p class="para">
File upload progress bar can be implemented using <a href="session.upload-progress.html" class="link">Session Upload Progress</a>.
</p>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="features.file-upload.html">Handling file uploads</a></div>
<div class="next" style="text-align: right; float: right;"><a href="features.file-upload.errors.html">Error Messages Explained</a></div>
<div class="up"><a href="features.file-upload.html">Handling file uploads</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
