Yii Framework v1.1.10 Class Reference

CUploadedFile

Package system.web
Inheritance class CUploadedFile » CComponent
Since 1.0
Version $Id: CUploadedFile.php 3515 2011-12-28 12:29:24Z mdomba $
Source Code framework/web/CUploadedFile.php
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

Hide inherited properties

PropertyTypeDescriptionDefined 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

Public Methods

Hide inherited methods

MethodDescriptionDefined By
__call() Calls the named method which is not a class method. CComponent
__construct() Constructor. CUploadedFile
__get() Returns a property value, an event handler list or a behavior based on its name. CComponent
__isset() Checks if a property value is null. CComponent
__set() Sets value of a component property. CComponent
__toString() String output. CUploadedFile
__unset() Sets a component property to be null. CComponent
asa() Returns the named behavior object. CComponent
attachBehavior() Attaches a behavior to this component. CComponent
attachBehaviors() Attaches a list of behaviors to the component. CComponent
attachEventHandler() Attaches an event handler to an event. CComponent
canGetProperty() Determines whether a property can be read. CComponent
canSetProperty() Determines whether a property can be set. CComponent
detachBehavior() Detaches a behavior from the component. CComponent
detachBehaviors() Detaches all behaviors from the component. CComponent
detachEventHandler() Detaches an existing event handler. CComponent
disableBehavior() Disables an attached behavior. CComponent
disableBehaviors() Disables all behaviors attached to this component. CComponent
enableBehavior() Enables an attached behavior. CComponent
enableBehaviors() Enables all behaviors attached to this component. CComponent
evaluateExpression() Evaluates a PHP expression or callback under the context of this component. CComponent
getError() Returns an error code describing the status of this file uploading. CUploadedFile
getEventHandlers() Returns the list of attached event handlers for an event. CComponent
getExtensionName() Returns 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. CUploadedFile
getHasError() Returns whether there is an error with the uploaded file. Check error for detailed error code information. CUploadedFile
getInstance() Returns an instance of the specified uploaded file. CUploadedFile
getInstanceByName() Returns an instance of the specified uploaded file. CUploadedFile
getInstances() Returns all uploaded files for the given model attribute. CUploadedFile
getInstancesByName() Returns an array of instances for the specified array name. CUploadedFile
getName() Returns the original name of the file being uploaded CUploadedFile
getSize() Returns the actual size of the uploaded file in bytes CUploadedFile
getTempName() Returns 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. CUploadedFile
getType() Returns 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. CUploadedFile
hasEvent() Determines whether an event is defined. CComponent
hasEventHandler() Checks whether the named event has attached handlers. CComponent
hasProperty() Determines whether a property is defined. CComponent
raiseEvent() Raises an event. CComponent
reset() Cleans up the loaded CUploadedFile instances. CUploadedFile
saveAs() Saves the uploaded file. CUploadedFile

Protected Methods

Hide inherited methods

MethodDescriptionDefined By
collectFilesRecursive() Processes incoming files for getInstanceByName. CUploadedFile
prefetchFiles() Initially processes $_FILES superglobal for easier use. CUploadedFile

Property Details

error property read-only
public integer getError()

Returns an error code describing the status of this file uploading.

See Also

extensionName property read-only
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.

hasError property read-only
public boolean getHasError()

whether there is an error with the uploaded file. Check error for detailed error code information.

name property read-only
public string getName()

the original name of the file being uploaded

size property read-only
public integer getSize()

the actual size of the uploaded file in bytes

tempName property read-only
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.

type property read-only
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

__construct() method
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#165 (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.

__toString() method
public string __toString()
{return} string the string representation of the object
Source Code: framework/web/CUploadedFile.php#180 (show)
public function __toString()
{
    return $this->_name;
}

String output. This is PHP magic method that returns string representation of an object. The implementation here returns the uploaded file's name.

collectFilesRecursive() method
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#145 (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.

getError() method
public integer getError()
{return} integer the error code
Source Code: framework/web/CUploadedFile.php#248 (show)
public function getError()
{
    return $this->_error;
}

Returns an error code describing the status of this file uploading.

See Also

getExtensionName() method
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.
Source Code: framework/web/CUploadedFile.php#267 (show)
public function getExtensionName()
{
    if(($pos=strrpos($this->_name,'.'))!==false)
        return (string)substr($this->_name,$pos+1);
    else
        return '';
}

getHasError() method
public boolean getHasError()
{return} boolean whether there is an error with the uploaded file. Check error for detailed error code information.
Source Code: framework/web/CUploadedFile.php#257 (show)
public function getHasError()
{
    return $this->_error!=UPLOAD_ERR_OK;
}

getInstance() method
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.
Source Code: framework/web/CUploadedFile.php#58 (show)
public static function getInstance($model, $attribute)
{
    return self::getInstanceByName(CHtml::resolveName($model, $attribute));
}

Returns an instance of the specified uploaded file. The file should be uploaded using CHtml::activeFileField.

See Also

getInstanceByName() method
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#82 (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]').

getInstances() method
public static array 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} array array of CUploadedFile objects. Empty array is returned if no available file was found for the given attribute.
Source Code: framework/web/CUploadedFile.php#70 (show)
public static function getInstances($model, $attribute)
{
    return self::getInstancesByName(CHtml::resolveName($model, $attribute));
}

Returns all uploaded files for the given model attribute.

getInstancesByName() method
public static array getInstancesByName(string $name)
$name string the name of the array of files
{return} array 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#100 (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) && self::$_files[$key]->getError()!=UPLOAD_ERR_NO_FILE)
            $results[] = self::$_files[$key];
    return $results;
}

Returns an array of instances for the 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.

getName() method
public string getName()
{return} string the original name of the file being uploaded
Source Code: framework/web/CUploadedFile.php#210 (show)
public function getName()
{
    return $this->_name;
}

getSize() method
public integer getSize()
{return} integer the actual size of the uploaded file in bytes
Source Code: framework/web/CUploadedFile.php#238 (show)
public function getSize()
{
    return $this->_size;
}

getTempName() method
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.
Source Code: framework/web/CUploadedFile.php#220 (show)
public function getTempName()
{
    return $this->_tempName;
}

getType() method
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.
Source Code: framework/web/CUploadedFile.php#230 (show)
public function getType()
{
    return $this->_type;
}

prefetchFiles() method
protected static void prefetchFiles()
Source Code: framework/web/CUploadedFile.php#127 (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.

reset() method (available since v1.1.4)
public static void reset()
Source Code: framework/web/CUploadedFile.php#118 (show)
public static function reset()
{
    self::$_files=null;
}

Cleans up the loaded CUploadedFile instances. This method is mainly used by test scripts to set up a fixture.

saveAs() method
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
Source Code: framework/web/CUploadedFile.php#192 (show)
public function saveAs($file,$deleteTempFile=true)
{
    if($this->_error==UPLOAD_ERR_OK)
    {
        if($deleteTempFile)
            return move_uploaded_file($this->_tempName,$file);
        else if(is_uploaded_file($this->_tempName))
            return copy($this->_tempName, $file);
        else
            return false;
    }
    else
        return false;
}

Saves the uploaded file.

Copyright © 2008-2011 by Yii Software LLC
All Rights Reserved.