is_valid()
The is_valid can be used to check if there are any uploaded files present that have been validated.
Static | Yes |
---|---|
Parameters | None |
Returns | boolean - true if validated files exist, false if not. |
Example |
|
The upload class allows to securely process files that have been uploaded to the application. It allows you to filter uploads in various ways, define what the destination filenames should look like, or filter on size or length of the filename.
Information of every uploaded file is stored in a multidimensional array within the Upload class. For every file, an array is defined with the following fields:
Key | Type | Description |
---|---|---|
field | string | Name of the form field that was used to upload the file. |
key | mixed | If the form field was defined as an array, the key used. If not, this field is set to false. |
name | string | Name of the file uploaded. |
type | string | Mime-type of the file uploaded, as defined by the browser. |
mimetype | string | Mime-type of the file uploaded, as determined by the Upload class. Note that this requires an up-to-date 'mime magic' file to be installed. This file is present on every *nix platform, but on Windows platforms, you might have to install this file yourself. If the mime-type can not be determined, this field contains the same value as 'type'. |
file | string | The fully qualified filename of the temporary location of the uploaded file. |
filename | string | The filename (basename) of the file uploaded. |
extension | string | The extension of the file uploaded. |
size | integer | The size in bytes of the file uploaded. |
error | integer | The error detected when uploading the file or when validating the uploaded file. If zero, there were no errors. |
Note that mime-type will always contain the most specific type. So if the browser claims it's an MS-Word document, but the mime-type is determined as being "application/octet-stream", the browser's mime-type is used, even if this may be wrong or unexpected! For example, a Microsoft .xlsx file might be detected as being "application/zip".
After you have called the save() method, this array structure is expanded with two extra fields, giving you information about what was actually saved.
Key | Type | Description |
---|---|---|
saved_to | string | Fully qualified path where the uploaded file was saved. |
saved_as | string | Name of the file that was saved |
error | integer | The error field will be updated after calling save() to indicate any errors encountered when trying to save the file. |
The Upload class defines the following error constants:
Name | Description |
---|---|
UPLOAD_ERR_OK | There is no error, the file uploaded with success. |
UPLOAD_ERR_INI_SIZE | The uploaded file exceeds the upload_max_filesize directive in php.ini. |
UPLOAD_ERR_FORM_SIZE | The uploaded file exceeds the MAX_FILE_SIZE directive that was specified in the HTML form. |
UPLOAD_ERR_PARTIAL | The uploaded file was only partially uploaded. |
UPLOAD_ERR_NO_FILE | No file was uploaded. Note that entries with this error will be filtered when the uploaded file list is processed. |
UPLOAD_ERR_NO_TMP_DIR | Missing a temporary folder. |
UPLOAD_ERR_CANT_WRITE | Failed to write file to disk. |
UPLOAD_ERR_EXTENSION | A PHP extension stopped the file upload. PHP does not provide a way to ascertain which extension caused the file upload to stop; examining the list of loaded extensions with phpinfo() may help. |
UPLOAD_ERR_MAX_SIZE | The file uploaded exceeds the maximum file size defined in the configuration. |
UPLOAD_ERR_EXT_BLACKLISTED | The extension of the file uploaded is defined in the extension blacklist. |
UPLOAD_ERR_EXT_NOT_WHITELISTED | The extension of the file uploaded is not defined in the extension whitelist. |
UPLOAD_ERR_TYPE_BLACKLISTED | The extension of the file uploaded is defined in the type blacklist. |
UPLOAD_ERR_TYPE_NOT_WHITELISTED | The extension of the file uploaded is not defined in the type whitelist. |
UPLOAD_ERR_MIME_BLACKLISTED | The extension of the file uploaded is defined in the mime-type blacklist. |
UPLOAD_ERR_MIME_NOT_WHITELISTED | The extension of the file uploaded is not defined in the mime-type whitelist. |
UPLOAD_ERR_MAX_FILENAME_LENGTH | The uploaded filename exceeds the defined maximum filename length. |
UPLOAD_ERR_MOVE_FAILED | The uploaded filename could not be moved from temporary storage to the path specified. This could mean that there's a permission issue. |
UPLOAD_ERR_DUPLICATE_FILE | The uploaded filename could not be saved because a file with that name already exists. |
The is_valid can be used to check if there are any uploaded files present that have been validated.
Static | Yes |
---|---|
Parameters | None |
Returns | boolean - true if validated files exist, false if not. |
Example |
|
The get_files method returns a multi-dimensional array with all files uploaded that have an error status = Upload::UPLOAD_ERR_OK.
Static | Yes | ||||||
---|---|---|---|---|---|---|---|
Parameters |
|
||||||
Returns | array | ||||||
Example |
|
The get_files method returns a multi-dimensional array with all files uploaded that have an error status != Upload::UPLOAD_ERR_OK.
Static | Yes | ||||||
---|---|---|---|---|---|---|---|
Parameters |
|
||||||
Returns | array | ||||||
Example |
|
The register method allows you to register callbacks for specific upload events, and allow you to add your own code to the process() and save() methods.
Static | Yes | |||||||||
---|---|---|---|---|---|---|---|---|---|---|
Parameters |
|
|||||||||
Returns | boolean - true if the callback was registered, false if the registration failed. | |||||||||
Example |
|
If you want to use a 'validate' callback, be sure to register it before you call Upload::process(). If you have used the 'auto_process' configuration setting, Upload::process() will be called as soon as you use the Upload class, which means you will have to call it again after you have defined the callback.
The callback will receive an entry from the uploaded files array as parameter. The entry is passed by reference, which allows
the callback function to modify the entries of the array.
If the callback function returns an integer, it is assumed to be an update of the uploaded file's error code.
All other return values are ignored.
The process method processes the information about all uploaded files, normalizes the different permutations of form field names that can be used, fetches additional information about the file and its mimetype, and validates the file.
Static | Yes | ||||||
---|---|---|---|---|---|---|---|
Parameters |
|
||||||
Returns | void | ||||||
Example |
|
The save method saves all validated files uploaded to the path specified.
Static | Yes | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Parameters |
Note that the order in which these parameters are given is not relevant, and all of them are optional. But either use $integer or $array, and not both. If you do, the last one specified will be used. |
||||||||||||
Returns | void | ||||||||||||
Example |
|