UploadINC

The topic of uploading files comes up often on the ECE Webteam, so much so that we often find ourselves reprogramming the same uploading script over and over again. If we're able to reuse code though, it will not only save us time, but also make all of our lives easier.

It is for this reason I've written UploadINC. This will give everyone a simple, easy to use method for uploading files, and also, creating forms to upload the files.

Before you can use UploadINC at all, you need to include this one crucial line before any code:

require "upload.inc.php";

This will include the UploadINC source into your file so that you'll be able to use it.

The source of UploadINC contains two classes. The first is the UploadForm() class. This class is designed for creating forms for uploading files. The second is the Upload() class, which is designed for doing the actual uploading to the server of the file.

UploadForm() Class

UploadForm()
Usage: $Form = new UploadForm();
     Constructor function. Used to start the class.
     Accepts no parameters.
     Returns no parameters.

FormOpen()
Usage: $Form->FormOpen($Name, $Action);
     Opens a new <form> with the ENCTYPE set as "multipart/form-data"
     Accepts two parameters.
          $Name = Name of Form
          $Action = Form Action (GET, POST, etc.)
     Returns string containing opening line of <form>.

File()
Usage: $Form->File($Name, $Value, $Class, $Length, $Disabled);
     Creates a new <input> element for files
     Accepts five parameters.
          $Name = Name of element
          $Value = Predefined value of element
          $Class = CSS class name
          $Length = Length of element
          $Disabled = Whether the element is disabled or not. 0 for No; 1 for Yes.
     Returns string containing <input> line for files.

Text()
Usage: $Form->Text($Name, $Value, $Class, $Length, $Disabled);
     Creates a new <input> element for text
     Accepts five parameters.
          $Name = Name of element
          $Value = Predefined value of element
          $Class = CSS class name
          $Length = Length of element
          $Disabled = Whether the element is disabled or not. 0 for No; 1 for Yes.
     Returns string containing <input> line for text.

Checkbox()
Usage: $Form->Checkbox($Name, $Value, $Class, $Checked, $Disabled);
     Creates a new <input> element for a checkbox
     Accepts five parameters.
          $Name = Name of element
          $Value = Predefined value of element
          $Class = CSS class name
          $Checked = If the value of this variable is the same as the value
               of $Value the radio button will be checked. Also supports arrays.
          $Disabled = Whether the element is disabled or not. 0 for No; 1 for Yes.
     Returns string containing <input> line for a checkbox.

Radio()
Usage: $Form->Radio($Name, $Value, $Class, $Checked, $Disabled);
     Creates a new <input> element for a radio button
     Accepts five parameters.
          $Name = Name of element
          $Value = Predefined value of element
          $Class = CSS class name
          $Checked = If the value of this variable is the same as the value
               of $Value the radio button will be checked.
          $Disabled = Whether the element is disabled or not. 0 for No; 1 for Yes.
     Returns string containing <input> line for a radio button.

TextArea()
Usage: $Form->TextArea($Name, $Value, $Class, $Length, $Height);
     Creates a new <textarea> element
     Accepts five parameters.
          $Name = Name of element
          $Value = Predefined value of element
          $Class = CSS class name
          $Length = Width of element
          $Height = Rows of element
     Returns string containing <textarea>.

Hidden()
Usage: $Form->Hidden($Name, $Value);
     Creates a new hidden <input> element
     Accepts two parameters.
          $Name = Name of element
          $Value = Predefined value of element
     Returns string containing <input> line for a hidden element.

SelectOpen()
Usage: $Form->SelectOpen($Name, $Value);
     Creates and opens a <select> element
     Accepts two parameters.
          $Name = Name of element
          $Class = CSS class name
     Returns string containing the opening line for a <select> element.

Option()
Usage: $Form->Option($Value, $Text, $Selected);
     Creates a new <option> element for inclusion in a <select> element
     Accepts three parameters.
          $Value = Predefined value of element
          $Text = The text to appear inbetween the opening and closing
               <option> tags.
          $Selected = The option value the <select> element should be set to.
     Returns string containing <option> line for inclusion in a <select> element.

SelectClose()
Usage: $Form->SelectClose();
     Creates and opens a <select> element
     Accepts no parameters.
     Returns string containing the closing line for a <select> element.
     Note: Any <select> elements opened with SelectOpen() must be closed with
          SelectClose() in order to use FormClose().

Submit()
Usage: $Form->Submit($Name, $Value, $Class);
     Creates a new submit button for the form
     Accepts three parameters.
          $Name = Name of element
          $Value = Predefined value of element
          $Class = CSS class name
     Returns string containing <input> line for a submit 1button.

FormClose()
Usage: $Form->FormClose();
     Creates and opens a <select> element
     Accepts no parameters.
     Returns string containing the closing line for a <form> element.
     Note: The function will throw an error if SelectOpen() is not closed with
          SelectClose()

---

Sample UploadINC Form

Code:

<?php
$A = new UploadForm();
echo $A->FormOpen('NewForm', $_SERVER['SCRIPT_NAME]);
echo $A->File("Filename","",'Style4',"50","0");
echo '<br />';
echo $A->Radio('Favorite','Bear','Style3', '0', 0);
echo 'Bear';
echo $A->Radio('Favorite','Chicken','Style3', 'Chicken', 0);
echo 'Chicken';
echo '<br />';
echo $A->SelectOpen('FavAnimal','Style1', 'Wolf');
echo $A->Option("Dog","Dog");
echo $A->Option("Cat","Cat");
echo $A->Option("Wolf","Wolf");
echo $A->Option("Turtle","Turtle");
echo $A->SelectClose();
echo $A->Submit('Click','Submit','Style2');
echo $A->FormClose();
?>

Output:

<form name="NewForm" action="/webteam/using_uploadinc.php" method="POST" ENCTYPE="multipart/form-data"><input type="File" name="Filename" value="" class="Style4" size="50" />
<input type="Radio" name="Favorite" value="Bear" class="Style3" checked />Bear<input type="Radio" name="Favorite" value="Chicken" class="Style3" checked />Chicken
<select name="FavAnimal" class="Style1"><option value="Dog">Dog</option><option value="Cat">Cat</option><option value="Wolf" selected>Wolf</option><option value="Turtle">Turtle</option></select><input type="submit" name="Click" value="Submit" class="Style2" /></form>

Upload() Class

Upload()
Usage: $Form = new Upload($File);
     Constructor function. Used to start the class.
     Accepts one parameters.
          $File = Array containing information about the file the user is
               attempting to upload. This should be an array from $_FILES[]
     Returns no parameters.
     Note: This function will return an error in the ShowErrors()
          debugging function if there is a failure.

AllowOverwrite()
Usage: $Form->AllowOverwrite($O);
     Determines the state of whether a file can be overwritten on
          the server if it already exists.
     Accepts one parameters.
          $O = Binary Value; Use 1 if the file can be overwritten; 0 if it cannot
     Returns no paramaters.
     Note: Overwriting is off by default.

SetPath()
Usage: $Form->SetPath($Path);
     Tells UploadINC where to upload the file to
     Accepts one parameters.
          $Path = Path to upload to
     Returns no parameters.
     Note: The beginning path for all ECE uploads is:
          /afs/eos.ncsu.edu/engrservers/www/ece/

SetName()
Usage: $Form->SetName($NewName);
     Sets the name of the file that will be uploaded
     Accepts one parameters.
          $NewName = Name of file
     Returns no parameters.
     Note: You must be sure to include the extension on the file.

SetMaxSize()
Usage: $Form->SetMaxSize($Max);
     Sets the maximum size of files allowed to be uploaded.
     Accepts one parameters.
          $Max = Maximum size of allowed files (in MB)
     Returns no parameters.
     Note: The default max size is set to 2MB.

GetName()
Usage: $Form->GetName();
     Gets the name of the file being uploaded
     Accepts no parameters.
     Returns the name of the file.

GetMIME()
Usage: $Form->GetMIME();
     Gets the MIME type of the file being uploaded
     Accepts no parameters.
     Returns the MIME type of the file.

GetExtension()
Usage: $Form->GetExtension();
     Gets the extension of the file being uploaded
     Accepts no parameters.
     Returns the extension type of the file.

AddMIME()
Usage: $Form->AddMIME($Ext);
     Adds a MIME type that is allowed to be uploaded to an
          array of allowed file types.
     Accepts one parameters.
          $Ext = Name of file
     Returns no parameters.
     Note: You can find out the MIME type of most files by using
          IANA.org or Google.

DoUpload()
Usage: $Form->DoUpload();
     Performs the action of uploading the file.
     Accepts no parameters.
     Returns true if uploading is successful. Otherwise, returns
          false with an explanation that can be seen by calling
          ShowErrors()

ShowErrors()
Usage: $Form->ShowErrors();
     Returns all errors encountered by UploadINC
     Accepts no parameters.
     Returns any errors that prevented the script from running successfully.
     Note: If the file is uploaded successfully, ShowErrors() returns a success message.

---

Sample UploadINC Upload Script

Code:

<?php
$F = new Upload($_FILES['Filename']);
$F->SetPath('/afs/eos.ncsu.edu/engrservers/www/ece/_data/testfiles/');
$F->AddMIME('application/pdf');
$F->AddMIME('application/msword');
$F->AddMIME('text/plain');
$F->AddMIME('application/mspowerpoint');
$F->AddMIME('application/vnd.ms-powerpoint');
$F->AllowOverwrite(1);
$UploadWork = $F->DoUpload();
$FileName = $F->GetName();
if ($UploadWork === true){
     // Code to be executed if file is uploaded successfully
} else {
     echo $F->ShowErrors();
}
?>

Important Note About Uploading

Before any files can be uploaded, the target directory set in the SetPath() function must have permissions set so that engr:www-servers has read, lookup, insert, delete, write, and lock permissions. Otherwise, the file upload will fail.

Keep in mind that there is an open_basedir restriction on the web servers. This prevents you from writing to a directory above the directory which the script resides in. For example:

/path/ece/beta/upload.php can write to /path/ece/beta/

/path/ece/beta/upload.php can write to /path/ece/beta/abstein2/
/path/ece/beta/upload.php cannot write to /path/ece/
/path/ece/beta/upload.php cannot write to /path/