Overview

Namespaces

  • Rundiz
    • Upload

Classes

  • Upload
  • Overview
  • Namespace
  • Class

Class Upload

PHP upload class that is able to validate requirements and limitations, real file's mime type check, detect the errors and report.

Namespace: Rundiz\Upload
Package: Upload
Author: Vee W.
Version: 2.0.1
Located at Rundiz/Upload/Upload.php
Methods summary
public
# __construct( string $input_file_name )

Begins upload class.

Begins upload class.

Parameters

$input_file_name
The name of input file.
public
# __destruct( )

Class destructor. Works at end of class (unset class's variable).

Class destructor. Works at end of class (unset class's variable).
protected static string
# __( string $string )

Placeholder method for language editor program like Poedit to lookup for the words that is using this method.
This method does nothing but for who use program like Poedit to search/lookup the words that is using this method to create translation.
Example:
There is this code in generator class.

static::__('Hello');


Use Poedit to search for __ function to update/retreive the source text and translate it.

Placeholder method for language editor program like Poedit to lookup for the words that is using this method.
This method does nothing but for who use program like Poedit to search/lookup the words that is using this method to create translation.
Example:
There is this code in generator class.

static::__('Hello');


Use Poedit to search for __ function to update/retreive the source text and translate it.

Parameters

$string
The message to use.

Returns

string
Return the same string.
public
# clear( )

Clear all properties to its default values.

Clear all properties to its default values.
protected
# clearUploadedAtTemp( )

Clear uploaded files at temp folder. (if it is able to write/delete).

Clear uploaded files at temp folder. (if it is able to write/delete).
public array
# getUploadedData( )

Get the uploaded data.

Get the uploaded data.

Returns

array

Return array set of successful uploaded files and its data.
Example:

$output = array(
    'input_file_name_key' => array(
        'name' => 'file_name_where_user_selected_in_the_upload_form.ext',
        'extension' => 'ext',
        'size' => 'file size in bytes.',
        'new_name' => 'new_file_name_that_was_set_while_upload_process.ext',
        'full_path_new_name' => '/full/move_uploaded_path/to/new_file_name_that_was_set_while_upload_process.ext',
        'mime' => 'The real file mime type',
        'md5_file' => 'The md5 file value.',
    ),
    'other_input_file_name_key' => array(
        'name' => '...',
        'extension' => '...',
        'size' => '...',
        'new_name' => '...',
        'full_path_new_name' => '...',
        'mime' => '...',
        'md5_file' => '...',
    ),
);

If failed to upload, it will return empty array.
protected boolean
# moveUploadedFiles( )

Move the uploaded file(s).

Move the uploaded file(s).

Returns

boolean
Return true on success, false on failure.
protected string
# renameDuplicateFile( string $file_name, $loop_count = 1 )

Rename the file where it is duplicate with existing file.

Rename the file where it is duplicate with existing file.

Parameters

$file_name
File name to check
$loop_count

Returns

string
Return renamed file that will not duplicate the existing file.
protected boolean
# securityScan( )

Security scan. Scan for such as embedded php code in the uploaded file.

Security scan. Scan for such as embedded php code in the uploaded file.

Returns

boolean
Return true on safety, return false for otherwise.
protected
# setErrorMessage( string $error_messages, string $code, string $errorAttributes = '', string $errorFileName = '', string $errorFileSize = '', string $errorFileMime = '' )

Set the error message into error_messages and error_codes properties.

Set the error message into error_messages and error_codes properties.

Parameters

$error_messages
The error message.
$code
The error code, start with RDU_ and follow with number or short error message without space.
$errorAttributes
Error attributes. For example: 9MB > 2MB in case that limit file size to 2MB but uploaded 9MB, or showing file name that have problem.
$errorFileName
The file name with extension.
$errorFileSize
The file size in bytes.
$errorFileMime
The file mime type.

Since

2.0.1
public
# setInputFileName( string $input_file_name )

Set input file name.
If you begins new class object then you don't have to call this method. You must call this method after called to the clear() method.
Or you can call this method in case that you want to process the other uploaded file next to previous one.

Set input file name.
If you begins new class object then you don't have to call this method. You must call this method after called to the clear() method.
Or you can call this method in case that you want to process the other uploaded file next to previous one.

Parameters

$input_file_name
The name of input file.
protected
# setNewFileName( )

Set the new file name if it was not set, check for reserved file name and removed those characters.

Set the new file name if it was not set, check for reserved file name and removed those characters.

Link

Windows file name FAQ.
Windows reserved file name.
Global reserved file name.
protected
# setNewFileNameToRandom( )

Set the new file name to random. (unique id and microtime).

Set the new file name to random. (unique id and microtime).
protected
# setupFileExtensionsMimeTypesForValidation( )

Setup file extensions mime types for validation. (In case that it was not set).

Setup file extensions mime types for validation. (In case that it was not set).
protected
# setWebSafeFileName( )

Set the file name that is safe for web.
The safe for web file name is English and number chacters, no space (replaced with dash), no special characters, allowed dash and underscore.

Set the file name that is safe for web.
The safe for web file name is English and number chacters, no space (replaced with dash), no special characters, allowed dash and underscore.
public string
# testGetUploadedMimetype( string $input_file_name = null )

Test get the real file's mime type using finfo_file.
This is very useful when you want to add new file extension and mime type to validate uploaded files.

Test get the real file's mime type using finfo_file.
This is very useful when you want to add new file extension and mime type to validate uploaded files.

Parameters

$input_file_name
The input file name. This support only one file upload.

Returns

string
Return file's mime type or error message.

Link

More info about finfo_file() function.
public boolean
# upload( )

Start the upload and move uploaded files process.

Start the upload and move uploaded files process.

Returns

boolean
Return true on success, false for otherwise. If upload multiple file and there is error only one it return false.
protected boolean
# uploadSingleFile( )

Start upload process for single file.
Even upload multiple file will call to this method because it will be re-format the uploaded files property to become a single file and then call this.

Start upload process for single file.
Even upload multiple file will call to this method because it will be re-format the uploaded files property to become a single file and then call this.

Returns

boolean
Return true on success, false for otherwise.
protected boolean
# validateExtensionAndMimeType( )

Validate allowed extension and its mime types (if all of these was set).

Validate allowed extension and its mime types (if all of these was set).

Returns

boolean
Return true on success, false on failure.
protected boolean
# validateFileSize( )

Validate uploaded file must not exceed max file size limit. (if max file size limit was set).

Validate uploaded file must not exceed max file size limit. (if max file size limit was set).

Returns

boolean
Return true on success, false on failure.
protected
# validateOptionsProperties( )

Validate that these options properties has properly set in the correct type.

Validate that these options properties has properly set in the correct type.
Properties summary
public array $allowed_file_extensions

Allowed file extensions. Example: array('jpg', 'gif', 'png').

Allowed file extensions. Example: array('jpg', 'gif', 'png').
#
public array $file_extensions_mime_types

The array set of file extensions and its valid mime types for check when process the uploaded files.
Example:

array(
    'jpg' => array('image/jpeg', 'image/pjpeg'),
    'txt' => array('text/plain'),
);

If you don't want to validate mime type, set this property to an empty array. Example: $Upload->file_extensions_mime_types = array();

The array set of file extensions and its valid mime types for check when process the uploaded files.
Example:

array(
    'jpg' => array('image/jpeg', 'image/pjpeg'),
    'txt' => array('text/plain'),
);

If you don't want to validate mime type, set this property to an empty array. Example: $Upload->file_extensions_mime_types = array();
#
public integer $max_file_size

Set max file size to upload. This file size unit is in bytes only.

Set max file size to upload. This file size unit is in bytes only.
#
public string $new_file_name

Set new file name, just set the file name only. No extension.
Important! This property is not recommend to set it if you upload multiple files with same input file name. It is recommended to leave this as null and set overwrite property to true or false.
If you want to set the name while upload multiple files, it is recommended that you set overwrite property to false.

Set new file name, just set the file name only. No extension.
Important! This property is not recommend to set it if you upload multiple files with same input file name. It is recommended to leave this as null and set overwrite property to true or false.
If you want to set the name while upload multiple files, it is recommended that you set overwrite property to false.
#
public boolean $overwrite

To overwrite the uploaded file set it to true, otherwise set it to false.

To overwrite the uploaded file set it to true, otherwise set it to false.
# false
public boolean $web_safe_file_name

To rename uploaded file name to safe for web set it to true, otherwise set it to false.
The safe for web file name is English and number chacters, no space (replaced with dash), no special characters, allowed dash and underscore.

To rename uploaded file name to safe for web set it to true, otherwise set it to false.
The safe for web file name is English and number chacters, no space (replaced with dash), no special characters, allowed dash and underscore.
# true
public boolean $security_scan

Set to true to enable security scan such as php open tag (<?php). Set to false to not scan. This is optional security.

Set to true to enable security scan such as php open tag (<?php). Set to false to not scan. This is optional security.
# false
public boolean $stop_on_failed_upload_multiple

If you upload multiple files and there is at least one file that did not pass the validation, do you want it to stop?
Set to true to stop and delete all uploaded files (all uploaded files must pass validation).
Set to false to skip the error files (failed validation files are report as error, success validation files continue the process).

If you upload multiple files and there is at least one file that did not pass the validation, do you want it to stop?
Set to true to stop and delete all uploaded files (all uploaded files must pass validation).
Set to false to skip the error files (failed validation files are report as error, success validation files continue the process).
# true
public string $move_uploaded_to

Path to store files that was uploaded to move to. Do not end with trailing slash.

Path to store files that was uploaded to move to. Do not end with trailing slash.
# '.'
public array $error_codes

Contain error codes.

Contain error codes.

The array format will be:

array(
    index => array(// the `index` will be the same as it is in error_messages property.
        'code' => 'RDU_1',// this will be error code, start with RDU_ and follow with number or short error message without space. it is easy for check and replace with your translation.
        'errorAttributes' => 'string',// this key contain error attributes as string
            // for example: 9MB > 2MB in case that limit file size to 2MB but uploaded 9MB, or showing file name that have problem.
            // this key may contain empty string so check it before use.
        'errorFileName' => 'filename.ext',// the file name with extension that cause error message.
            // this key may contain empty string.
        'errorFileSize' => '12345',// the file size in bytes.
            // this key may contain empty string.
        'errorFileMime' => 'mime/type',// the file mime type.
            // this key may contain empty string.
    )
)

The error codes and description.

RDU_MOVE_UPLOADED_FAILED = Failed to move uploaded file.
RDU_SEC_ERR_PHP = Security error! Found PHP embedded in the uploaded file.
RDU_SEC_ERR_CGI = Security error! Found CGI/Pearl embedded in the uploaded file.
RDU_MOVE_UPLOADED_TO_NOT_DIR = The target upload location is not folder.
RDU_MOVE_UPLOADED_TO_NOT_WRITABLE = The target upload location is not writable. Please check folder permission.
RDU_UNABLE_VALIDATE_EXT = Unable to validate file extension.
RDU_NOT_ALLOW_EXT = The uploaded file is not in allowed extensions.
RDU_UNABLE_VALIDATE_EXT_AND_MIME = Unable to validate file extension and mime type.
RDU_INVALID_MIME = The uploaded file has invalid mime type.
RDU_UNABLE_VALIDATE_MIME = Unable to validate mime type.

For the RDU_1 to RDU_8 use PHP upload errors. ( http://php.net/manual/en/features.file-upload.errors.php ).
RDU_1 = The uploaded file exceeds the max file size directive.
RDU_2 = The uploaded file exceeds the MAX_FILE_SIZE directive that was specified in the HTML form.
RDU_3 = The uploaded file was only partially uploaded.
RDU_4 = No file was uploaded.
RDU_6 = Missing a temporary folder.
RDU_7 = Failed to write file to disk.
RDU_8 = A PHP extension stopped the file upload.

Since

2.0.1
# array()
public array $error_messages

If there is at least one error message it will be set to here.

If there is at least one error message it will be set to here.
# array()
protected string $input_file_name

The input file name. ($_FILES['input_file_name']).

The input file name. ($_FILES['input_file_name']).
#
protected array $files

Contain all values from $_FILES['input_file_name'] for works with upload process. This will be very useful when upload multiple files.
Example:

$Upload->files['input_file_name'];

is same as

$_FILES['input_file_name']

Contain all values from $_FILES['input_file_name'] for works with upload process. This will be very useful when upload multiple files.
Example:

$Upload->files['input_file_name'];

is same as

$_FILES['input_file_name']
# array()
protected array $move_uploaded_queue

The queue for move uploaded file(s). This is very useful when upload multiple files.

The queue for move uploaded file(s). This is very useful when upload multiple files.
# array()
API documentation generated by ApiGen