PHP CookBook

Recipe 9.7 Processing Uploaded Files

9.7.1 Problem

You want to process a file uploaded by a user.

9.7.2 Solution

Use the $_FILES array:

// from <input name="event" type="file">
if (is_uploaded_file($_FILES['event']['tmp_name'])) {
    readfile($_FILES['event']['tmp_name']); // print file on screen
}

9.7.3 Discussion

Starting in PHP 4.1, all uploaded files appear in the $_FILES superglobal array. For each file, there are four pieces of information:

name

The name assigned to the form input element

type

The MIME type of the file

size

The size of the file in bytes

tmp_name

The location in which the file is temporarily stored on the server.

If you're using an earlier version of PHP, you need to use $HTTP_POST_FILES instead.

After you've selected a file from that array, use is_uploaded_file( ) to confirm that the file you're about to process is a legitimate file resulting from a user upload, then process it as you would other files on the system. Always do this. If you blindly trust the filename supplied by the user, someone can alter the request and add names such as /etc/passwd to the list for processing.

You can also move the file to a permanent location; use move_uploaded_file( ) to safely transfer the file:

// move the file: move_uploaded_file() also does a check of the file's
// legitimacy, so there's no need to also call is_uploaded_file()
move_uploaded_file($_FILES['event']['tmp_name'], '/path/to/file.txt');

Note that the value stored in tmp_name is the complete path to the file, not just the base name. Use basename( ) to chop off the leading directories if needed.

Be sure to check that PHP has permission to read and write to both the directory in which temporary files are saved (see the upload_tmp_dir configuration directive to check where this is) and the location in which you're trying to copy the file. This can often be user nobody or apache, instead of your personal username. Because of this, if you're running under safe_mode, copying a file to a new location will probably not allow you to access it again.

Processing files can often be a subtle task because not all browsers submit the same information. It's important to do it correctly, however, or you open yourself up to a possible security hole. You are, after all, allowing strangers to upload any file they choose to your machine; malicious people may see this as an opportunity to crack into or crash the computer.

As a result, PHP has a number of features that allow you to place restrictions on uploaded files, including the ability to completely turn off file uploads all together. So, if you're experiencing difficulty processing uploaded files, check that your file isn't being rejected because it seems to pose a security risk.

To do such a check first, make sure file_uploads is set to On inside your configuration file. Next, make sure your file size isn't larger than upload_max_filesize; this defaults to 2 MB, which stops someone trying to crash the machine by filling up the hard drive with a giant file. Additionally, there's a post_max_size directive, which controls the maximum size of all the POST data allowed in a single request; its initial setting is 8 MB.

From the perspective of browser differences and user error, if you can't get $_FILES to populate with information, make sure you add enctype="multipart/form-data" to the form's opening tag; PHP needs this to trigger processing. If you can't do so, you need to manually parse $HTTP_RAW_POST_DATA. (See RFCs 1521 and 1522 for the MIME specification at http://www.faqs.org/rfcs/rfc1521.html and http://www.faqs.org/rfcs/rfc1522.html.)

Also, if no file is selected for uploading, versions of PHP prior to 4.1 set tmp_name to none; newer versions set it to the empty string. PHP 4.2.1 allows files of length 0. To be sure a file was uploaded and isn't empty (although blank files may be what you want, depending on the circumstances), you need to make sure tmp_name is set and size is greater than 0. Last, not all browsers necessarily send the same MIME type for a file; what they send depends on their knowledge of different file types.

9.7.4 See Also

Documentation on handling file uploads at http://www.php.net/features.file-upload and on basename() at http://www.php.net/basename.