<HTML ><HEAD ><TITLE >Handling file uploads</TITLE ><META NAME="GENERATOR" CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK REL="HOME" TITLE="PHP Manual" HREF="index.html"><LINK REL="UP" TITLE="Features" HREF="features.html"><LINK REL="PREVIOUS" TITLE="Cookies" HREF="features.cookies.html"><LINK REL="NEXT" TITLE="Error Messages Explained" HREF="features.file-upload.errors.html"><META HTTP-EQUIV="Content-type" CONTENT="text/html; charset=ISO-8859-1"></HEAD ><BODY CLASS="chapter" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#840084" ALINK="#0000FF" ><DIV CLASS="NAVHEADER" ><TABLE SUMMARY="Header navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TH COLSPAN="3" ALIGN="center" >PHP Manual</TH ></TR ><TR ><TD WIDTH="10%" ALIGN="left" VALIGN="bottom" ><A HREF="features.cookies.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="80%" ALIGN="center" VALIGN="bottom" ></TD ><TD WIDTH="10%" ALIGN="right" VALIGN="bottom" ><A HREF="features.file-upload.errors.html" ACCESSKEY="N" >Next</A ></TD ></TR ></TABLE ><HR ALIGN="LEFT" WIDTH="100%"></DIV ><DIV CLASS="chapter" ><H1 ><A NAME="features.file-upload" >Chapter 18. Handling file uploads</A ></H1 ><DIV CLASS="TOC" ><DL ><DT ><B >Table of Contents</B ></DT ><DT ><A HREF="features.file-upload.html#features.file-upload.post-method" >POST method uploads</A ></DT ><DT ><A HREF="features.file-upload.errors.html" >Error Messages Explained</A ></DT ><DT ><A HREF="features.file-upload.common-pitfalls.html" >Common Pitfalls</A ></DT ><DT ><A HREF="features.file-upload.multiple.html" >Uploading multiple files</A ></DT ><DT ><A HREF="features.file-upload.put-method.html" >PUT method support</A ></DT ></DL ></DIV ><DIV CLASS="sect1" ><H1 CLASS="sect1" ><A NAME="features.file-upload.post-method" ></A >POST method uploads</H1 ><P > PHP is capable of receiving file uploads from any RFC-1867 compliant browser (which includes Netscape Navigator 3 or later, Microsoft Internet Explorer 3 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. </P ><DIV CLASS="note" ><BLOCKQUOTE CLASS="note" ><P ><B >Related Configurations Note: </B > See also the <A HREF="configuration.directives.html#ini.file-uploads" >file_uploads</A >, <A HREF="configuration.directives.html#ini.upload-max-filesize" >upload_max_filesize</A >, <A HREF="configuration.directives.html#ini.upload-tmp-dir" >upload_tmp_dir</A >, and <A HREF="configuration.directives.html#ini.post-max-size" >post_max_size</A > directives in <TT CLASS="filename" >php.ini</TT > </P ></BLOCKQUOTE ></DIV ><P > Note that PHP also supports PUT-method file uploads as used by Netscape Composer and W3C's Amaya clients. See the <A HREF="features.file-upload.put-method.html" >PUT Method Support</A > for more details. </P ><P > A file upload screen can be built by creating a special form which looks something like this: <TABLE WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" CLASS="EXAMPLE" ><TR ><TD ><DIV CLASS="example" ><A NAME="AEN5800" ></A ><P ><B >Example 18-1. File Upload Form</B ></P ><TABLE BORDER="0" BGCOLOR="#E0E0E0" CELLPADDING="5" ><TR ><TD ><PRE CLASS="html" ><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"> </form></PRE ></TD ></TR ></TABLE ></DIV ></TD ></TR ></TABLE > The _URL_ should point to a PHP file. The MAX_FILE_SIZE hidden field must precede the file input field and its value is the maximum filesize accepted. The value is in bytes. <DIV CLASS="warning" ><P ></P ><TABLE CLASS="warning" BORDER="1" WIDTH="100%" ><TR ><TD ALIGN="CENTER" ><B >Warning</B ></TD ></TR ><TR ><TD ALIGN="LEFT" ><P > The MAX_FILE_SIZE is advisory to the browser. It is easy to circumvent this maximum. So don't count on it that the browser obeys your wish! The PHP-settings for maximum-size, however, cannot be fooled. </P ></TD ></TR ></TABLE ></DIV > </P ><P > The Variables defined for uploaded files differs depending on the PHP version and configuration. The autoglobal <A HREF="reserved.variables.html#reserved.variables.files" >$_FILES</A > exists as of PHP 4.1.0 The <TT CLASS="varname" >$HTTP_POST_FILES</TT > array has existed since PHP 4.0.0. These arrays will contain all your uploaded file information. Using <TT CLASS="varname" >$_FILES</TT > is preferred. If the PHP directive <A HREF="configuration.directives.html#ini.register-globals" >register_globals</A > is <SPAN CLASS="emphasis" ><I CLASS="emphasis" >on</I ></SPAN >, related variable names will also exist. <A HREF="configuration.directives.html#ini.register-globals" >register_globals</A > defaults to <SPAN CLASS="emphasis" ><I CLASS="emphasis" >off</I ></SPAN > as of PHP <A HREF="http://www.php.net/release_4_2_0.php" TARGET="_top" >4.2.0</A >. </P ><P > The contents of <A HREF="reserved.variables.html#reserved.variables.files" >$_FILES</A > from our example script is as follows. Note that this assumes the use of the file upload name <SPAN CLASS="emphasis" ><I CLASS="emphasis" >userfile</I ></SPAN >, as used in the example script above. <P ></P ><DIV CLASS="variablelist" ><DL ><DT ><TT CLASS="varname" >$_FILES['userfile']['name']</TT ></DT ><DD ><P > The original name of the file on the client machine. </P ></DD ><DT ><TT CLASS="varname" >$_FILES['userfile']['type']</TT ></DT ><DD ><P > The mime type of the file, if the browser provided this information. An example would be <TT CLASS="literal" >"image/gif"</TT >. </P ></DD ><DT ><TT CLASS="varname" >$_FILES['userfile']['size']</TT ></DT ><DD ><P > The size, in bytes, of the uploaded file. </P ></DD ><DT ><TT CLASS="varname" >$_FILES['userfile']['tmp_name']</TT ></DT ><DD ><P > The temporary filename of the file in which the uploaded file was stored on the server. </P ></DD ><DT ><TT CLASS="varname" >$_FILES['userfile']['error']</TT ></DT ><DD ><P > The <A HREF="features.file-upload.errors.html" >error code</A > associated with this file upload. <SPAN CLASS="emphasis" ><I CLASS="emphasis" >['error']</I ></SPAN > was added in PHP 4.2.0 </P ></DD ></DL ></DIV > </P ><DIV CLASS="note" ><BLOCKQUOTE CLASS="note" ><P ><B >Note: </B > In PHP versions prior 4.1.0 this was named <TT CLASS="varname" >$HTTP_POST_FILES</TT > and it's not an <A HREF="language.variables.predefined.html#language.variables.superglobals" >autoglobal</A > variable like <TT CLASS="varname" >$_FILES</TT > is. PHP 3 does not support <TT CLASS="varname" >$HTTP_POST_FILES</TT >. </P ></BLOCKQUOTE ></DIV ><P > When <A HREF="configuration.directives.html#ini.register-globals" >register_globals</A > is turned <SPAN CLASS="emphasis" ><I CLASS="emphasis" >on</I ></SPAN > in <TT CLASS="filename" >php.ini</TT >, additional variables are available. For example, <TT CLASS="varname" >$userfile_name</TT > will equal <TT CLASS="varname" >$_FILES['userfile']['name']</TT >, <TT CLASS="varname" >$userfile_type</TT > will equal <TT CLASS="varname" >$_FILES['userfile']['type']</TT >, 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. </P ><P > Files will by default be stored in the server's default temporary directory, unless another location has been given with the <A HREF="configuration.directives.html#ini.upload-tmp-dir" >upload_tmp_dir</A > directive in <TT CLASS="filename" >php.ini</TT >. The server's default directory can be changed by setting the environment variable <TT CLASS="envar" >TMPDIR</TT > in the environment in which PHP runs. Setting it using <A HREF="function.putenv.html" ><B CLASS="function" >putenv()</B ></A > 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. <TABLE WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" CLASS="EXAMPLE" ><TR ><TD ><DIV CLASS="example" ><A NAME="AEN5865" ></A ><P ><B >Example 18-2. Validating file uploads</B ></P ><P > See also the function entries for <A HREF="function.is-uploaded-file.html" ><B CLASS="function" >is_uploaded_file()</B ></A > and <A HREF="function.move-uploaded-file.html" ><B CLASS="function" >move_uploaded_file()</B ></A > for further information. The following example will process the file upload that came from a form. </P ><TABLE BORDER="0" BGCOLOR="#E0E0E0" CELLPADDING="5" ><TR ><TD ><PRE CLASS="php" ><?php // In PHP earlier then 4.1.0, $HTTP_POST_FILES should be used instead of $_FILES. // In PHP earlier then 4.0.3, use copy() and is_uploaded_file() instead of move_uploaded_file $uploaddir = '/var/www/uploads/'; print "<pre>"; if (move_uploaded_file($_FILES['userfile']['tmp_name'], $uploaddir . $_FILES['userfile']['name'])) { print "File is valid, and was successfully uploaded. Here's some more debugging info:\n"; print_r($_FILES); } else { print "Possible file upload attack! Here's some debugging info:\n"; print_r($_FILES); } ?></PRE ></TD ></TR ></TABLE ></DIV ></TD ></TR ></TABLE > </P ><P > 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 <TT CLASS="varname" >$_FILES['userfile']['size']</TT > variable to throw away any files that are either too small or too big. You could use the <TT CLASS="varname" >$_FILES['userfile']['type']</TT > variable to throw away any files that didn't match a certain type criteria. As of PHP 4.2.0, you could use <TT CLASS="varname" >$_FILES['userfile']['error']</TT > and plan your logic according to the <A HREF="features.file-upload.errors.html" >error codes</A >. Whatever the logic, you should either delete the file from the temporary directory or move it elsewhere. </P ><P > 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 ></DIV ><DIV CLASS="NAVFOOTER" ><HR ALIGN="LEFT" WIDTH="100%"><TABLE SUMMARY="Footer navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" ><A HREF="features.cookies.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="index.html" ACCESSKEY="H" >Home</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" ><A HREF="features.file-upload.errors.html" ACCESSKEY="N" >Next</A ></TD ></TR ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" >Cookies</TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="features.html" ACCESSKEY="U" >Up</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" >Error Messages Explained</TD ></TR ></TABLE ></DIV ></BODY ></HTML >