CUploadedFile
CUploadedFile represents the information for an uploaded file.
Call
getInstance to retrieve the instance of an uploaded file, and then use
saveAs to save it on the server. You may also query other information about the file, including
name,
tempName,
type,
size and
error.
Public Properties
Property |
Type |
Description |
Defined By |
error | integer | Returns an error code describing the status of this file uploading. | CUploadedFile |
extensionName | string | the file extension name for name. | CUploadedFile |
hasError | boolean | whether there is an error with the uploaded file. | CUploadedFile |
name | string | the original name of the file being uploaded | CUploadedFile |
size | integer | the actual size of the uploaded file in bytes | CUploadedFile |
tempName | string | the path of the uploaded file on the server. | CUploadedFile |
type | string | the MIME-type of the uploaded file (such as "image/gif"). | CUploadedFile |
Property Details
public integer getError()
Returns an error code describing the status of this file uploading.
public string getExtensionName()
the file extension name for name. The extension name does not include the dot character. An empty string is returned if name does not have an extension name.
public boolean getHasError()
whether there is an error with the uploaded file. Check error for detailed error code information.
public string getName()
the original name of the file being uploaded
public integer getSize()
the actual size of the uploaded file in bytes
public string getTempName()
the path of the uploaded file on the server. Note, this is a temporary file which will be automatically deleted by PHP after the current request is processed.
public string getType()
the MIME-type of the uploaded file (such as "image/gif"). Since this MIME type is not checked on the server side, do not take this value for granted. Instead, use CFileHelper::getMimeType to determine the exact MIME type.
Method Details
public void __construct(string $name, string $tempName, string $type, integer $size, integer $error) |
$name | string | the original name of the file being uploaded |
$tempName | string | the path of the uploaded file on the server. |
$type | string | the MIME-type of the uploaded file (such as "image/gif"). |
$size | integer | the actual size of the uploaded file in bytes |
$error | integer | the error code |
Source Code: framework/web/CUploadedFile.php#164 (
show)
public function __construct($name,$tempName,$type,$size,$error)
{
$this->_name=$name;
$this->_tempName=$tempName;
$this->_type=$type;
$this->_size=$size;
$this->_error=$error;
}
Constructor. Use getInstance to get an instance of an uploaded file.
public string __toString() |
{return} | string | the string representation of the object |
String output. This is PHP magic method that returns string representation of an object. The implementation here returns the uploaded file's name.
protected static void collectFilesRecursive(string $key, mixed $names, mixed $tmp_names, mixed $types, mixed $sizes, mixed $errors) |
$key | string | key for identifiing uploaded file: class name and subarray indexes |
$names | mixed | file names provided by PHP |
$tmp_names | mixed | temporary file names provided by PHP |
$types | mixed | filetypes provided by PHP |
$sizes | mixed | file sizes provided by PHP |
$errors | mixed | uploading issues provided by PHP |
Source Code: framework/web/CUploadedFile.php#144 (
show)
protected static function collectFilesRecursive($key, $names, $tmp_names, $types, $sizes, $errors)
{
if(is_array($names))
{
foreach($names as $item=>$name)
self::collectFilesRecursive($key.'['.$item.']', $names[$item], $tmp_names[$item], $types[$item], $sizes[$item], $errors[$item]);
}
else
self::$_files[$key] = new CUploadedFile($names, $tmp_names, $types, $sizes, $errors);
}
Processes incoming files for getInstanceByName.
public integer getError() |
{return} | integer | the error code |
Returns an error code describing the status of this file uploading.
public string getExtensionName() |
{return} | string | the file extension name for name. The extension name does not include the dot character. An empty string is returned if name does not have an extension name. |
public boolean getHasError() |
{return} | boolean | whether there is an error with the uploaded file. Check error for detailed error code information. |
public static CUploadedFile getInstance(CModel $model, string $attribute) |
$model | CModel | the model instance |
$attribute | string | the attribute name. For tabular file uploading, this can be in the format of "[$i]attributeName", where $i stands for an integer index. |
{return} | CUploadedFile | the instance of the uploaded file. Null is returned if no file is uploaded for the specified model attribute. |
Returns an instance of the specified uploaded file. The file should be uploaded using CHtml::activeFileField.
public static CUploadedFile getInstanceByName(string $name) |
$name | string | the name of the file input field. |
{return} | CUploadedFile | the instance of the uploaded file. Null is returned if no file is uploaded for the specified name. |
Source Code: framework/web/CUploadedFile.php#81 (
show)
public static function getInstanceByName($name)
{
if(null===self::$_files)
self::prefetchFiles();
return isset(self::$_files[$name]) && self::$_files[$name]->getError()!=UPLOAD_ERR_NO_FILE ? self::$_files[$name] : null;
}
Returns an instance of the specified uploaded file. The name can be a plain string or a string like an array element (e.g. 'Post[imageFile]', or 'Post[0][imageFile]').
public static CUploadedFile[] getInstances(CModel $model, string $attribute) |
$model | CModel | the model instance |
$attribute | string | the attribute name. For tabular file uploading, this can be in the format of "[$i]attributeName", where $i stands for an integer index. |
{return} | CUploadedFile[] | array of CUploadedFile objects. Empty array is returned if no available file was found for the given attribute. |
Returns all uploaded files for the given model attribute.
public static CUploadedFile[] getInstancesByName(string $name) |
$name | string | the name of the array of files |
{return} | CUploadedFile[] | the array of CUploadedFile objects. Empty array is returned if no adequate upload was found. Please note that this array will contain all files from all subarrays regardless how deeply nested they are. |
Source Code: framework/web/CUploadedFile.php#99 (
show)
public static function getInstancesByName($name)
{
if(null===self::$_files)
self::prefetchFiles();
$len=strlen($name);
$results=array();
foreach(array_keys(self::$_files) as $key)
if(0===strncmp($key, $name.'[', $len+1) && self::$_files[$key]->getError()!=UPLOAD_ERR_NO_FILE)
$results[] = self::$_files[$key];
return $results;
}
Returns an array of instances starting with specified array name.
If multiple files were uploaded and saved as 'Files[0]', 'Files[1]', 'Files[n]'..., you can have them all by passing 'Files' as array name.
public string getName() |
{return} | string | the original name of the file being uploaded |
public integer getSize() |
{return} | integer | the actual size of the uploaded file in bytes |
public string getTempName() |
{return} | string | the path of the uploaded file on the server. Note, this is a temporary file which will be automatically deleted by PHP after the current request is processed. |
public string getType() |
{return} | string | the MIME-type of the uploaded file (such as "image/gif"). Since this MIME type is not checked on the server side, do not take this value for granted. Instead, use CFileHelper::getMimeType to determine the exact MIME type. |
protected static void prefetchFiles() |
Source Code: framework/web/CUploadedFile.php#126 (
show)
protected static function prefetchFiles()
{
self::$_files = array();
if(!isset($_FILES) || !is_array($_FILES))
return;
foreach($_FILES as $class=>$info)
self::collectFilesRecursive($class, $info['name'], $info['tmp_name'], $info['type'], $info['size'], $info['error']);
}
Initially processes $_FILES superglobal for easier use. Only for internal usage.
public static void reset() |
Cleans up the loaded CUploadedFile instances. This method is mainly used by test scripts to set up a fixture.
public boolean saveAs(string $file, boolean $deleteTempFile=true) |
$file | string | the file path used to save the uploaded file |
$deleteTempFile | boolean | whether to delete the temporary file after saving. If true, you will not be able to save the uploaded file again in the current request. |
{return} | boolean | true whether the file is saved successfully
In some exceptional cases such as not enough permissions to write to the path specified PHP warning is triggered. |
Source Code: framework/web/CUploadedFile.php#196 (
show)
public function saveAs($file,$deleteTempFile=true)
{
if($this->_error==UPLOAD_ERR_OK)
{
if($deleteTempFile)
return move_uploaded_file($this->_tempName,$file);
elseif(is_uploaded_file($this->_tempName))
return copy($this->_tempName, $file);
else
return false;
}
else
return false;
}
Saves the uploaded file. Note: this method uses php's move_uploaded_file() method. As such, if the target file ($file) already exists it is overwritten.