FileUpload

FileUpload
This is the constructor for the class. To create a new object just use the following code:

Code:

$object = new FileUpload($_FILES['fieldname']);

addError
The addError function is used internally for adding errors to the array.

addFileType
Valid filetypes can be added to the object by using this function. There are several ways you can use to add new filetypes to the array.

Method 1 (Single extension, Single MIME-Type)

Code:

$object->addFileType('gif', 'image/gif');

or

Code:

$object->addFileType('gif', array('image/gif'));

Method 2 (Single Extension, Multiple MIME-Types)

Code:

$object->addFileType('jpg', array('image/jpeg', 'image/pjpeg'));

Method 3 (Array)

Code:

$object->addFileType(array(

                           'gif' => array('image/gif'),

                           'jpg' => array('image/jpeg', 'image/pjpeg')

                           ));

Remember: When using the third option, every mimetype must be in the array. You cannot use a string.

Checking of extensions is case-insensitive. You do not need to add JPG as well as jpg.

addUploaded
The addUploaded function is used internally for adding succesfull uploads to the array.

generateDirectoryStructure
When you issue the move() command, this function is called to make sure that the full path (given as an argument with the move() command) is available on the server. If a directory does not exists, this function will create the directory.

getExtension
getExtension() is used internally to extract the extension of a filename.

getHighestFileNumber
getHighestFileNumber() is used internally to extract the highest number of a file from the directory given in the parameter.

getUploaded
getUploaded() returns an array with the files which have been uploaded succesfully.

Code:

$aUploaded = $object->getUploaded();

isEmptyDir
isEmptyDir() is used internally by the rollback() function to check if a directory is empty before it is removed. If the directory is not empty, no action will be taken.

isFileTypeAllowed
isFileTypeAllowed() is used internally by the move function to check if the file which is currently being progressed is allowed. This function takes the extension and the mime-type of the uploaded file and checks if it exists in the array of allowed filetypes created with addFileType().
Checking of extensions is case-insensitive. You do not need to add JPG as well as jpg.

move
move() can be seen as the main command for the class. When this function is being called all files will be verified and (if possible) moved to the directory provided in the first argument of the command.
As told before; if the directory provided does not exist, the generateDirectoryStructure() function will make sure the full path exists on the server.
Information about errors and uploads is only available after executing this function.

Code:

$object->move('images/uploads');

prepareFileName
prepareFileName() is used internally to make preperations to the filename/extension of an individual file.

readDirectory
readDirectory() is used internally to read a directory into an array so it can be used by other functions.

rollback
rollback() can be used to return to the previous state when an error has occured.
The command has to be issued manually and will delete any succesfull uploaded files from that session (a session = one upload). It will also remove the directory structure as far as the directories are empty. If there are still files in the directory then it will not delete the directory.

Code:

$object->rollback();

Example: If you have issued the move() command with the argument 'images/upload/new/' and your directory structure looks like this after the initialisation of generateDirectoryStructure():

+ images
  + upload
    + new
  + news

after executing the function (and taking in consideration that the /new dir has just been created) and the upload dir is empty your directory structure will look like this:

+ images
  + news

setIgnoreEmptyUploads
When calling this function, the optional argument can be set to true/false to enable/disable the function. When you call the function without an argument (defaults to true), empty uploads will not be counted as an error.
This might be handy when you have a form with 4 file fields but sometimes only want to upload 3 files (for example). The fourth file (which isn't uploaded as you haven't selected it) will normally generate an error. This might be very frustrating if you are using the rollback() function if any errors occured.

Code:

$object->setIgnoreEmptyUploads();

setLowerCaseExtension
When calling this function, the optional argument can be set to true/false to enable/disable the function. When you call the function without an argument (defaults to true), all extensions of the files being uploaded will be casted to lowercase (.JPG will become .jpg, etc).

Code:

$object->setLowerCaseExtension();

setMaxSize
With setMaxSize() you can set the maximum size in bytes a file has to comply to.
So if you would like to set the limit at 80 kB you can use the following command:

Code:

$object->setMaxSize(80000);

setNewName
setNewName() is a usefull function which can be used to:
- Give a single-file upload a new name
- Give a multi-file upload new names
- Set the naming method for automatic naming

Method 1 (Single file)
This method can be used if you are uploading a single file and want to give it a new name. A good example for this is an avatar system. See the examples for more information.

Code:

$object->setNewName('myPicture');

Method 2 (Multiple file renaming)
This method can be used when you are uploading several items at the same time and would like to give them a certain name. For this you have to give the function an array of new names. For every entry one. If there are more file uploads than names in the array, the file will keep its original name.

Code:

$object->setNewName(array('myPicture', 'myCar', 'myComputer'));

Method 3 (Naming method)
This method can only be used when uploading several images at the same time. You will have to enter one of the following values: 'num' or 'alpha'.
When you have chosen for 'num' the uploads will get a number as filename starting with 1. The files will keep their original extension but the number will keep on counting. This method is usefull for creating image galleries.
When you chose for 'alpha' the first file will get the name 'a', the second 'b' and so on.

Code:

$object->setNewName('num');

setStartNumber
With setStartNumber() you can set the number where the automatic numbering system should start counting. This only works if you are uploading multiple files in an array and you set the newName to 'num' to enable numeric naming.

The argument for this call is optional. You can call this function with an integer value as the first argument, then this number will be the name for the first file being uploaded and the rest will just get that number + 1.

If you set the argument to 'auto' (which is the default) then the internal system will scan the directory where you are moving the files and will recognize the file with the highest file number. That number (+1) will be taken as the default value.

Code:

$object->setStartNumber(10);

Code:

$object->setStartNumber();

Which is the same as:

Code:

$object->setStartNumber('auto');