Uploading Files
In some dynamic web applications, it is necessary to allow users to upload files from their local computer to the Web server. Such an application may allow users to share files with others or simply provide a mechanism for storing files for later use. This section introduces the PHP function for uploading files.
In PHP, file upload capability is possible using the following function:
move_uploaded_file(filename, destination) - moves a file to a specified destination on the server.
Before we look at the details of the PHP code, lets focus on the XHTML form controls needed to create the file upload page.
<form enctype="multipart/form-data" action="upload.php" method="post">
Select File: <input type="file" name="uploadFile">
<input name="SubmitB" type="submit" value="Upload File">
</form>
The code block begins with a standard HTML <form> tag. In addition to the action and method attributes, a form used for file uploads must include the encode type or "enctype" attribute. The value of the enctype attribute "multipart/form-data" should be included when a form is used to upload files.
Following the <form> is an <input> text box control. This control is used to specify the location and name of the file that will be uploaded. The control includes a name and type attribute. The type attribute must be set to "file". The name is a user-defined value that will be used by the server to identify the source file during the upload process. The file text box also includes a "Browse..." button when viewed in the browser window. When the browse button is clicked, a dialog window appears and allows the user to browse their local computer for the file that will be uploaded.
The final control is a submit button. The submit button is used to initiate the form submission process. When the button is clicked, the file information is posted the upload.php page which contains the PHP code to upload the file to a folder located on the web server.
After the HTML form is coded, a PHP script can be added to the page to handle the dyanmic file upload. When a file is uploaded using the move_uploaded_file() function, it is briefly stored in a temporary location on the web server. To move the file to its final destination and manipulate its various properties, we use the PHP $_FILES super global array. The $_FILES array uses the name value provided in the <input type="file" name="UploadFile"> (in this case 'UploadFile') to indentify the file being uploaded. The entries associated with the $_FILES array are described below.
- $_FILES['UploadFile']['tmp_name'] - directory on the web server where the file is temporarily stored. By default this is the uploadtemp directory located in the PHP folder.
- $_FILES['UploadFile']['name'] - name of the file on the user's system.
- $_FILES['UploadFile']['size'] - size of the file in bytes.
- $_FILES['UploadFile']['type'] - the MIME type of the file.
- $_FILES['UploadFile']['error'] - the error code associated with the file upload (0 - successful upload, 1 - file exceeds maximum upload size, 2 - file exceeds maximum file size, 3 - file partially uploaded, 4 - no file uploaded)
The following code blocks shows how the $_FILES array is used with the move_uploaded_file() function to create a simple upload procedure.
upload.php
<?php
if ($_POST[SubmitB] == "Upload File")
{
move_uploaded_file ($_FILES['uploadFile'] ['tmp_name'],
"../PHPTutorial/ECommerce/Databases/{$_FILES['uploadFile'] ['name']}");
echo "File uploaded.";
}
?>
<form enctype="multipart/form-data" action="upload.php" method="post">
Select File: <input type="file" name="uploadFile">
<input name="SubmitB" type="submit" value="Upload File">
</form>
When the "Upload File" button is clicked, the file specified in the <input type="file" name="UploadFile"> is automatically posted to a temporary folder on the webserver. The move_uploaded_file() function is then called to move the file. The first parameter of the function - $_FILES['uploadFile'] ['tmp_name'], becomes a reference to the file as the function prepares to move it to its final destination. The second parameter - "../PHPTutorial/ECommerce/Databases/{$_FILES['uploadFile'] ['name']}", is a relative path to the folder were the file will be permanently saved. The last part of the path includes the code - {$_FILES['uploadFile'] ['name']}. This can be interpreted as the name of the file which was entered into the file text box named "uploadFile". In short, the move_uploaded_file() function moves the file from a temporary upload folder to the folder ($_FILES['uploadFile'] ['tmp_name']) to the folder ("../PHPTutorial/ECommerce/Databases/) and the file is saved with the same name as entered by the user ({$_FILES['uploadFile'] ['name']}). Files can be uploaded to any directory on the web server, however, the destination folder must have "write" access permissions.
The previous code example illustrates the ease of uploading a file but the assumption is that the file upload process will always work and errors will never occur. We have not considered what happens when a user attempts to upload a file that exceeds size limits, if the upload folder does not have appropriate security permissions, or some unforeseen network issue prevents the entire file from being uploaded. To improve the file upload code above, we must provide routines that check for errors and provide feedback to the user on how to correct these problems.
The next blocks shows a modified version of the previous upload routine which includes error checking.
upload.php
<?php
if ($_POST[SubmitB] == "Upload File")
{
move_uploaded_file ($_FILES['uploadFile'] ['tmp_name'],
"../PHPTutorial/ECommerce/Databases/{$_FILES['uploadFile'] ['name']}");
if($_FILES['uploadFile'] ['error'] > 0)
{
switch ($_FILES['uploadFile'] ['error'])
{
case 1: echo 'File exceeded maximum server upload size';
break;
case 2: echo 'File exceeded maximum file size';
break;
case 3: echo 'File only partially uploaded';
break;
case 4: echo 'No file uploaded';
break;
}
}
else
{
echo 'File successfully uploaded';
}
}
?>
<form enctype="multipart/form-data" action="upload.php" method="post">
Select File: <input type="file" name="uploadFile">
<input type="hidden" name="MAX_FILE_SIZE" value="1000000">
<input name="SubmitB" type="submit" value="Upload File">
</form>
The updated code includes an if statement and a switch/case statement to check the status of the file upload. After the move_uploaded_file(), and if statement checks the value of the $_FILES['uploadFile'] ['error'] array. If the value is greater than 0, an error has occured. The value of $_FILES['uploadFile'] ['error'] is passed to a switch statement and is evaluated. When the value is determined, the appropriate error message is displayed. If the value of $_FILES['uploadFile'] ['error'] is equal to 0, the else statement displays a success message.
Another new feature included in this example is an HTML hidden text box called "MAX_FILE_SIZE". This is a special hidden tag that can be used with the file tag <input type="file" name="uploadFile"> to set a maximum file size. If the file exceedes the specified value, an error will occur. The value is measured in bytes. Here the maximum file size is set to 1,000,000 bytes (approximately 1 MB). It is also possible to set a maximum server upload size. This is the maximum file size set on the server within the PHP.ini file.