Manual

Easy and secure managment of files submitted via HTML forms.

Introduction

This package provides an advanced system for managing uploads of files via HTML <input type="file" /> fields. Features include:

Handling of multiple file uploads at a time
Safe file copying/moving from temporary directories
Upload validaton mechanisms
Extensive information about uploaded files
Renaming uploaded files
Internationalized error messages

Examples

In the following examples it is assumed that you are using an HTML form field <input type="file" name="f" /> in order to upload files. For example:

HTML form for simple file upload

The following form can be used in order to test the single file upload example.

<?php
// sample code from below goes here
?>
<html>
 <head>
 </head>
 <body>
  <form name="fileuploadexample" method="post" enctype="multipart/form-data"
   action="<?php echo htmlspecialchars($_SERVER['PHP_SELF']) ?>">
   <input type="file" name="f" />
   <input type="submit" name="submit" value="Submit" />
  </form>
 </body>
</html>

Simple file upload

The following code looks at the request and checks if a valid file was uploaded through the form. If that is the case, the file is moved to the subdirectory uploads.

<?php
require_once "HTTP/Upload.php";

$upload = new HTTP_Upload("en");
$file = $upload->getFiles("f");

if ($file->isValid()) {
    $moved = $file->moveTo('uploads/');
    if (!PEAR::isError($moved)) {
        echo 'File was moved to uploads/' . $file->getProp('name');
    } else {
        echo $moved->getMessage();
    }
} elseif ($file->isMissing()) {
    echo "No file was provided.";
} elseif ($file->isError()) {
    echo $file->errorMsg();
}
?>

Internally, HTTP_Upload_File::moveTo() calls $file->setName('safe'); which replaces special characters in the name with an underscore. You should always use $file->getProp('name') after moving to retrieve the new filename.

HTML form for multiple file upload

The following form can be used in order to test the multiple file upload example.

<?php
// sample code from below goes here
?>
<html>
 <head>
 </head>
 <body>
  <form name="fileuploadexample2" method="post" enctype="multipart/form-data"
   action="<?php echo htmlspecialchars($_SERVER['PHP_SELF']) ?>">
   <input type="file" name="f1" />
   <input type="file" name="f2" />
   <input type="submit" name="submit" value="Submit" />
  </form>
 </body>
</html>

Multiple files, more extensive checks

Multiple files can uploaded by replacing the name of the form field (f) with f[] and creating multiple <input /> fields with this name.

<?php
$upload = new HTTP_Upload("en");
$files = $upload->getFiles();

foreach($files as $file){
    if (PEAR::isError($file)) {
        echo $file->getMessage();
    }

    if ($file->isValid()) {
        $file->setName("uniq");
        $dest_name = $file->moveTo("uploads/");

        if (PEAR::isError($dest_name)) {
            echo $dest_name->getMessage();
        }

        $real = $file->getProp("real");

    } elseif ($file->isMissing()) {
        echo "No file was provided.";
    } elseif ($file->isError()) {
        echo $file->errorMsg();
    }

    print_r($file->getProp());
}
?>

Extensive information about uploaded files

HTTP_Upload provides extensive information about uploaded files via the getProp() method:

mixed HTTP_Upload_File::getProp ( [name] )

If no value for name is provided, then this method will return an array containing all available information about the uploaded file. Otherwise the information identified by the value of this parameter will be returned as a string.

The list of possible values is determined by the contents of the $_FILES array, but is customized for the purposes of HTTP_Upload. Here are the possible properties:

'name': destination file name
'tmp_name': temporary uploaded file name (assigned by PHP)
'form_name': name of the HTML form that submitted the uploaded file
'type': Mime type of the file
'size': size of the file
'error': if there was an error on upload, this contains a string representing the kind of error. The errorCode() method can be used to retrieve a localized error message from this property.

Extensive information via getProp()

<?php
require_once "HTTP/Upload.php";

$upload = new HTTP_Upload("en");
$file = $upload->getFiles("f");

if ($file->isValid()) {
    echo "<pre>";
    print_r($file->getProp());
    echo "</pre>";

    printf("The uploaded file has the extension %s.", $file->getProp("ext"));
}
?>

Internationalized Error Messages

Another handy feature of HTTP_Upload is support for internationalized error messages. This means that if an error (like an invalid file upload) is detected, the programmer can choose in which the language the error messages should be returned by HTTP_Upload.

The first parameter of the constructor method for HTTP_Upload determines the language to be used. This is illustrated in the following example:

Example

<?php
// German error messages
$language = "de";

require_once "HTTP/Upload.php";

$upload = new HTTP_Upload($language);
$file = $upload->getFiles("f");

if ($file->isValid()) {
    $moved = $file->moveTo("uploads/");
    if (!PEAR::isError($moved)) {
        echo "File was moved to uploads/";
    } else {
        // This will print a german error message
        echo "An error was detected: " . $moved->getMessage() . "<br />";
    }
}
?>