Scorpio Framework for PHP

• Resources

  • Categories
  • News
  • Documentation
  • Tutorials
  • Roadmap

• Links

  • Madagasgar.com
  • SourceForge Project Page
  • Download Releases
  • Bug Tracker
  • Feature Requests
  • API Docs

mvcFileUpload

• You are in »
• Components /
• Documentation /
• MVC /

Provides an interface to the PHP _FILES array to help manipulate file uploads in a consistent manner. Can handle arrays of files as well as single items. File arrays must be uploaded as FieldName[].

As the files are processed, they are converted into individual mvcFileObjects. These are added to a set, and this is returned by the call to process(). This set can be used to obtain the file data.

All file uploads are screened and filenames automatically checked. The original name can be preserved (within limits), otherwise it will be used with the time to create a MD5 hash.

Various options can be set to control how this object handles the uploads. These include: deferring actual file copying which will automatically cause the file data to be placed in the mvcFileObject instead, specifying the file store AND sub-folder pattern for the store, checking folder permissions at runtime etc.

This class has an extensive exception model covering most incidents of bad configuration or problems. When uploading multiple files, the upload will process all files in the batch and then throw an exception with the details of all the files that failed.

// set options via constructor
$oFileUpload = new mvcFileUpload(
    array(
        mvcFileUpload::OPTION_FILE_STORE => system::getConfig()->getPathTemp().'/appName/fileStore',
        mvcFileUpload::OPTION_SUB_FOLDER_FORMAT => date('/Y/m'),
        mvcFileUpload::OPTION_FIELD_NAME => 'FileUploadFieldNameInHTMLForm',
    )
);
// NOTE: initialise() must always be called BEFORE process();
$oFileUpload->initialise();
$oFileSet = $oFileUpload->process();
foreach ( $oFileSet as $oFile ) {
    // now do something with the files
    // each file as an instance of mvcFileObject
}

// set options via methods
$oFileUpload = new mvcFileUpload();
$oFileUpload->setFileStore(system::getConfig()->getPathTemp().'/appName/fileStore');
$oFileUpload->setSubFolderFormat(date('/Y/m'));
$oFileUpload->setFieldName('FileUploadFieldNameInHTMLForm');
$oFileUpload->initialise();
$oFileSet = $oFileUpload->process();
foreach ( $oFileSet as $oFile ) {
    // now do something with the files
    // each file is an instance of mvcFileObject
}

// options can be set via a semi-fluent interface
$oFileUpload = new mvcFileUpload();
$oFileUpload->setFileStore(
    system::getConfig()->getPathTemp().'/appName/fileStore'
)->setSubFolderFormat(
    date('/Y/m')
)->setFieldName(
    'FileUploadFieldNameInHTMLForm'
);

---

Methods

public __construct([$inOptions = array()])

Creates a new mvcFileUpload object; optionally sets up options

public reset()

Resets object to defaults

public init()

Initialises the mvcFileUpload object

public initialise()

Initialises the mvcFileUpload object

public process()

Processes the _FILES array of data

protected _processSingleFile()

Handles a single uploaded file field

protected _processArray()

Handles arrays of uploaded files, note that while this method does throw an exception, it only does so AFTER the array of files has been processed. If any Exception is throw, these will not be handled.

protected checkUploadedFile($inErrorCode, $inOriginalName)

Checks if the file upload completed successfully

protected checkIsValidUploadedFile($inTemporaryFileName, $inOriginalFileName)

Checks if the file ($inOriginalFileName) is a valid uploaded file, requires the temporary file name

protected createUploadFilename($inOriginalFilename)

Creates a target file name from the original filename, or builds an automatic name if set

Note: original filename will be sanitised for URI safety

protected getUploadedFileExtension($inOriginalFilename)

Returns the original files extension, lower cased

protected createUploadFile($inFileName, $inFileType, $inFileSize, $inTmpName)

Creates an mvcFileObject to represent the uploaded file

protected checkFolderPermissions()

Checks if the target folder can be written to by the current process, throws exceptions on error

protected buildFileStore()

Attempts to create the file store folder

protected buildSubFolders()

Attempts to create the sub folder structure in the file store

protected translateErrorCode($inErrorCode)

Translates the PHP upload error code into a string

public isModified()

Returns true if object has been modified

public setModified([$status = true])

Set the status of the object if it has been changed

public getOptionsSet()

Returns the value of $_OptionsSet

public setOptionsSet($inOptionsSet)

Allows for directly setting the baseOptionsSet

public getOption($inOption, [$inDefault = null])

Returns the option $inOption, if not found returns $inDefault

public setOption($inOption, $inValue)

Sets a single option $inOption to value $inValue

public setOptions([$inOptions = array()])

Sets multiple options into an existing options set

public getFieldName()

Returns $_FieldName

public setFieldName($inFieldName)

Set the field name used to upload files from

public getFileStore()

Returns $_FileStore

public setFileStore($inFileStore)

Set the path to the main file store, this may be in /data or in websites/base

public getSubFolderFormat()

Returns $_SubFolderFormat

public setSubFolderFormat($inSubFolderFormat)

Set the sub-folder format to use when storing the files.

This is appended to the file store path default is to use the date /YYYY/mm/dd; path MUST include leading /.

public getUploadTarget()

Returns the upload target (filestore+subfolder format)

public getUploadedFiles()

Returns the upload file set

public setUploadedFiles($inUploadedFiles)

Set the file result set

public getAutoCreateFileStore()

Returns $_AutoCreateFileStore

public setAutoCreateFileStore($inAutoCreateFileStore)

Should the folder store be auto-created, default true

public getCheckFolderPermissions()

Returns $_CheckFolderPermissions

public setCheckFolderPermissions($inCheckFolderPermissions)

Should the folder permissions be checked before processing, default true

public getUseOriginalFileName()

Returns $_UseOriginalFileName

public setUseOriginalFileName($inUseOriginalFileName)

Toggles whether the original file name is kept or not, default false

public getStoreRawFileDataInResult()

Returns $_StoreRawFileDataInResult

public setStoreRawFileDataInResult($inStoreRawFileDataInResult)

Should the raw file data be returned in the result set, default false

public getWriteFilesImmediately()

Returns $_WriteFilesImmediately

public setWriteFilesImmediately($inWriteFilesImmediately)

Set write mode; if not immediately written causes raw data to be placed in result, default true