Working with File Uploads

So far, we've looked at simple form input. However, Web browsers support file uploads, and so, of course, does PHP. In this section, you examine the features that PHP makes available to deal with this kind of input.

Information about the uploaded file becomes available to you in the $_FILES superglobal, which is indexed by the name of the upload field (or fields) in the form. The corresponding value for each of these keys is an associative array. These fields are described in Table 10.1, using fileupload as the name of the form field used for the upload.

Table 10.1. File Upload Global Variables
Element Example	Contains
`$_FILES['fileupload']['name']test.gif`	Original name of uploaded file
`$_FILES['fileupload']['tmp_name'] /tmp/phprDfZvN`	Path to temporary file
`$_FILES['fileupload']['size']6835`	Size (in bytes) of uploaded file
`$_FILES['fileupload']['type']image/gif`	MIME type of uploaded file (where given by client)

Keep these elements in the back of your mind for a moment, while we create the upload form in the next section.

Creating the File Upload Form

First, we must create the HTML form to handle the upload. HTML forms that include file upload fields must include an ENCTYPE argument:

PHP also works with an optional hidden field that can be inserted before the file upload field. This field must be called MAX_FILE_SIZE and should have a value representing the maximum size in bytes of the file that you're willing to accept. The MAX_FILE_SIZE field is obeyed at the browser's discretion, so you should rely on the php.ini setting, upload_max_filesize, to cap unreasonably large uploads. After the MAX_FILE_SIZE field has been entered, you're ready to add the upload field itself. This is simply an INPUT element with a TYPE argument of "file". You can give it any name you want. Listing 10.13 brings all this together into an HTML upload form.

Listing 10.13. A Simple File Upload Form

As you can see, file uploads are limited to 50KB on line 7, and the name of the file upload field is fileupload, as shown on line 8. Save this listing in a text file called fileupload.html, and place that file in your Web server document root. Use your Web browser to access this form and you should see something like Figure 10.9.

Creating the File Upload Script

If you remember the information regarding the $_FILES superglobal, you have all the information you need to write a simple file upload script. This script is the backend for the form created in Listing 10.14.

Listing 10.14. A File Upload Script

In Listing 10.14, we first create the $file_dir variable on line 2 to store path information. This path should be one that exists on your system, and the Web server user (for example, httpd, www, nobody) must have write permissions for it.

By the Way

The path used in line 2 is a Linux/Unix path. Windows users would use backslashes, such as \My Documents\.

Line 3 begins a foreach statement that loops through every element in the $_FILES array. A loop is used rather than an if statement, to make our script capable of scaling to deal with multiple uploads on the same page. The foreach loop on line 3 stores the upload file's name in the $file_name variable and the file information in the $file_array variable. We can then output the information we have about the upload.

Before moving the uploaded file from its temporary position to the location specified in line 2, first check that it exists. We do so on line 9, using the is_uploaded_file() function. This function accepts a path to an uploaded file and returns true only if the file in question is a valid upload file. This function therefore enhances the security of your scripts.

Assuming that all is well, the file is copied from its temporary home to a new directory on lines 10 and 11. We use another function, move_uploaded_file(), for this purpose. This function copies a file from one place to another, first performing the same security checks as those performed by is_uploaded_file(). The move_uploaded_file() function requires a path to the source file and a path to the destination. It returns true if the move is successful and false if the file isn't a valid upload file or if the file couldn't be found.

Watch Out!

Beware of the names of uploaded files. Operating systems such as Mac OS and Windows are pretty relaxed when it comes to file naming, so expect uploaded files to come complete with spaces, quotation marks, and all manner of other unexpected characters. Therefore, it's a good idea to filter filenames.

Put these lines into a text file called do_upload.php, and place that file in your Web server document root. Use your Web browser to go back to the form, and try to upload a file. If successful, you should see something like Figure 10.10 in your browser.