CModel


system.base
继承 abstract class CModel » CComponent
实现 IteratorAggregate, Traversable, ArrayAccess
子类 CActiveRecord, CFormModel
源自 1.0
版本 $Id: CModel.php 3515 2011-12-28 12:29:24Z mdomba $
源码
CModel是为数据模型对象提供共同特性的基类。

CModel定义了数据模型的基本框架,需要对数据验证。

公共属性

属性 类型 描述 定义在
attributes array Returns all attribute values. CModel
errors array Returns the errors for all attribute or a single attribute. CModel
iterator CMapIterator Returns an iterator for traversing the attributes in the model. CModel
safeAttributeNames array Returns the attribute names that are safe to be massively assigned. CModel
scenario string Returns the scenario that this model is used in. CModel
validatorList CList Returns all the validators declared in the model. CModel
validators array Returns the validators applicable to the current scenario. CModel

公共方法

方法 描述 定义在
__call() 如果类中没有调的方法名,则调用这个方法。 CComponent
__get() 返回一个属性值、一个事件处理程序列表或一个行为名称。 CComponent
__isset() 检查一个属性是否为null。 CComponent
__set() 设置一个组件的属性值。 CComponent
__unset() 设置一个组件的属性为null。 CComponent
addError() Adds a new error to the specified attribute. CModel
addErrors() Adds a list of errors. CModel
asa() 返回这个名字的行为对象。 CComponent
attachBehavior() 附加一个行为到组件。 CComponent
attachBehaviors() 附加一个行为列表到组件。 CComponent
attachEventHandler() 为事件附加一个事件处理程序。 CComponent
attributeLabels() Returns the attribute labels. CModel
attributeNames() 返回模型属性名称的列表。 CModel
behaviors() Returns a list of behaviors that this model should behave as. CModel
canGetProperty() 确定属性是否可读。 CComponent
canSetProperty() 确定属性是否可写。 CComponent
clearErrors() Removes errors for all attributes or a single attribute. CModel
createValidators() Creates validator objects based on the specification in rules. CModel
detachBehavior() 从组件中分离一个行为。 CComponent
detachBehaviors() 从组件中分离所有行为。 CComponent
detachEventHandler() 分离一个存在的事件处理程序。 CComponent
disableBehavior() 禁用一个附加行为。 CComponent
disableBehaviors() 禁用组件附加的所有行为。 CComponent
enableBehavior() 启用一个附加行为。 CComponent
enableBehaviors() 启用组件附加的所有行为。 CComponent
evaluateExpression() 计算一个PHP表达式,或根据组件上下文执行回调。 CComponent
generateAttributeLabel() Generates a user friendly attribute label. CModel
getAttributeLabel() Returns the text label for the specified attribute. CModel
getAttributes() Returns all attribute values. CModel
getError() Returns the first error of the specified attribute. CModel
getErrors() Returns the errors for all attribute or a single attribute. CModel
getEventHandlers() 返回一个事件的附加处理程序列表。 CComponent
getIterator() Returns an iterator for traversing the attributes in the model. CModel
getSafeAttributeNames() Returns the attribute names that are safe to be massively assigned. CModel
getScenario() Returns the scenario that this model is used in. CModel
getValidatorList() Returns all the validators declared in the model. CModel
getValidators() Returns the validators applicable to the current scenario. CModel
hasErrors() Returns a value indicating whether there is any validation error. CModel
hasEvent() 确定一个事件是否定义。 CComponent
hasEventHandler() 检查事件是否有附加的处理程序。 CComponent
hasProperty() 确定属性是否被定义。 CComponent
isAttributeRequired() Returns a value indicating whether the attribute is required. CModel
isAttributeSafe() Returns a value indicating whether the attribute is safe for massive assignments. CModel
offsetExists() Returns whether there is an element at the specified offset. CModel
offsetGet() Returns the element at the specified offset. CModel
offsetSet() Sets the element at the specified offset. CModel
offsetUnset() Unsets the element at the specified offset. CModel
onAfterConstruct() This event is raised after the model instance is created by new operator. CModel
onAfterValidate() This event is raised after the validation is performed. CModel
onBeforeValidate() This event is raised before the validation is performed. CModel
onUnsafeAttribute() This method is invoked when an unsafe attribute is being massively assigned. CModel
raiseEvent() 发起一个事件。 CComponent
rules() Returns the validation rules for attributes. CModel
setAttributes() Sets the attribute values in a massive way. CModel
setScenario() Sets the scenario for the model. CModel
unsetAttributes() Sets the attributes to be null. CModel
validate() Performs the validation. CModel

受保护方法

方法 描述 定义在
afterConstruct() This method is invoked after a model instance is created by new operator. CModel
afterValidate() This method is invoked after validation ends. CModel
beforeValidate() This method is invoked before validation starts. CModel

事件

事件 描述 定义在
onAfterConstruct This event is raised after the model instance is created by new operator. CModel
onBeforeValidate This event is raised before the validation is performed. CModel
onAfterValidate This event is raised after the validation is performed. CModel
onUnsafeAttribute This method is invoked when an unsafe attribute is being massively assigned. CModel

属性详细

attributes 属性
public array getAttributes(array $names=NULL)
public void setAttributes(array $values, boolean $safeOnly=true)

Returns all attribute values.

errors 属性 只读
public array getErrors(string $attribute=NULL)

Returns the errors for all attribute or a single attribute.

iterator 属性 只读

Returns an iterator for traversing the attributes in the model. This method is required by the interface IteratorAggregate.

safeAttributeNames 属性 只读
public array getSafeAttributeNames()

Returns the attribute names that are safe to be massively assigned. A safe attribute is one that is associated with a validation rule in the current scenario.

scenario 属性
public string getScenario()
public void setScenario(string $value)

Returns the scenario that this model is used in.

Scenario affects how validation is performed and which attributes can be massively assigned.

A validation rule will be performed when calling validate() if its 'on' option is not set or contains the current scenario value.

And an attribute can be massively assigned if it is associated with a validation rule for the current scenario. Note that an exception is the unsafe validator which marks the associated attributes as unsafe and not allowed to be massively assigned.

validatorList 属性 只读 (可用自 v1.1.2)

Returns all the validators declared in the model. This method differs from getValidators in that the latter would only return the validators applicable to the current scenario. Also, since this method return a CList object, you may manipulate it by inserting or removing validators (useful in behaviors). For example, $model->validatorList->add($newValidator). The change made to the CList object will persist and reflect in the result of the next call of getValidators.

validators 属性 只读
public array getValidators(string $attribute=NULL)

Returns the validators applicable to the current scenario.

方法详细

addError() 方法
public void addError(string $attribute, string $error)
$attribute string attribute name
$error string new error message
public function addError($attribute,$error)
{
    
$this->_errors[$attribute][]=$error;
}

Adds a new error to the specified attribute.

addErrors() 方法
public void addErrors(array $errors)
$errors array a list of errors. The array keys must be attribute names. The array values should be error messages. If an attribute has multiple errors, these errors must be given in terms of an array. You may use the result of getErrors as the value for this parameter.
public function addErrors($errors)
{
    foreach(
$errors as $attribute=>$error)
    {
        if(
is_array($error))
        {
            foreach(
$error as $e)
                
$this->_errors[$attribute][]=$e;
        }
        else
            
$this->_errors[$attribute][]=$error;
    }
}

Adds a list of errors.

afterConstruct() 方法
protected void afterConstruct()
protected function afterConstruct()
{
    if(
$this->hasEventHandler('onAfterConstruct'))
        
$this->onAfterConstruct(new CEvent($this));
}

This method is invoked after a model instance is created by new operator. The default implementation raises the onAfterConstruct event. You may override this method to do postprocessing after model creation. Make sure you call the parent implementation so that the event is raised properly.

afterValidate() 方法
protected void afterValidate()
protected function afterValidate()
{
    
$this->onAfterValidate(new CEvent($this));
}

This method is invoked after validation ends. The default implementation calls onAfterValidate to raise an event. You may override this method to do postprocessing after validation. Make sure the parent implementation is invoked so that the event can be raised.

attributeLabels() 方法
public array attributeLabels()
{return} array attribute labels (name=>label)
public function attributeLabels()
{
    return array();
}

Returns the attribute labels. Attribute labels are mainly used in error messages of validation. By default an attribute label is generated using generateAttributeLabel. This method allows you to explicitly specify attribute labels.

Note, in order to inherit labels defined in the parent class, a child class needs to merge the parent labels with child labels using functions like array_merge().

attributeNames() 方法
abstract public array attributeNames()
{return} array 模型属性名称的列表。
abstract public function attributeNames();

返回模型属性名称的列表。

beforeValidate() 方法
protected boolean beforeValidate()
{return} boolean whether validation should be executed. Defaults to true. If false is returned, the validation will stop and the model is considered invalid.
protected function beforeValidate()
{
    
$event=new CModelEvent($this);
    
$this->onBeforeValidate($event);
    return 
$event->isValid;
}

This method is invoked before validation starts. The default implementation calls onBeforeValidate to raise an event. You may override this method to do preliminary checks before validation. Make sure the parent implementation is invoked so that the event can be raised.

behaviors() 方法
public array behaviors()
{return} array the behavior configurations (behavior name=>behavior configuration)
public function behaviors()
{
    return array();
}

Returns a list of behaviors that this model should behave as. The return value should be an array of behavior configurations indexed by behavior names. Each behavior configuration can be either a string specifying the behavior class or an array of the following structure:

'behaviorName'=>array(
    'class'=>'path.to.BehaviorClass',
    'property1'=>'value1',
    'property2'=>'value2',
)


Note, the behavior classes must implement IBehavior or extend from CBehavior. Behaviors declared in this method will be attached to the model when it is instantiated.

For more details about behaviors, see CComponent.
clearErrors() 方法
public void clearErrors(string $attribute=NULL)
$attribute string attribute name. Use null to remove errors for all attribute.
public function clearErrors($attribute=null)
{
    if(
$attribute===null)
        
$this->_errors=array();
    else
        unset(
$this->_errors[$attribute]);
}

Removes errors for all attributes or a single attribute.

createValidators() 方法
public CList createValidators()
{return} CList validators built based on rules().
public function createValidators()
{
    
$validators=new CList;
    foreach(
$this->rules() as $rule)
    {
        if(isset(
$rule[0],$rule[1]))  // attributes, validator name
            
$validators->add(CValidator::createValidator($rule[1],$this,$rule[0],array_slice($rule,2)));
        else
            throw new 
CException(Yii::t('yii','{class} has an invalid validation rule. The rule must specify attributes to be validated and the validator name.',
                array(
'{class}'=>get_class($this))));
    }
    return 
$validators;
}

Creates validator objects based on the specification in rules. This method is mainly used internally.

generateAttributeLabel() 方法
public string generateAttributeLabel(string $name)
$name string the column name
{return} string the attribute label
public function generateAttributeLabel($name)
{
    return 
ucwords(trim(strtolower(str_replace(array('-','_','.'),' ',preg_replace('/(?<![A-Z])[A-Z]/'' \0'$name)))));
}

Generates a user friendly attribute label. This is done by replacing underscores or dashes with blanks and changing the first letter of each word to upper case. For example, 'department_name' or 'DepartmentName' becomes 'Department Name'.

getAttributeLabel() 方法
public string getAttributeLabel(string $attribute)
$attribute string the attribute name
{return} string the attribute label
public function getAttributeLabel($attribute)
{
    
$labels=$this->attributeLabels();
    if(isset(
$labels[$attribute]))
        return 
$labels[$attribute];
    else
        return 
$this->generateAttributeLabel($attribute);
}

Returns the text label for the specified attribute.

getAttributes() 方法
public array getAttributes(array $names=NULL)
$names array list of attributes whose value needs to be returned. Defaults to null, meaning all attributes as listed in attributeNames will be returned. If it is an array, only the attributes in the array will be returned.
{return} array attribute values (name=>value).
public function getAttributes($names=null)
{
    
$values=array();
    foreach(
$this->attributeNames() as $name)
        
$values[$name]=$this->$name;

    if(
is_array($names))
    {
        
$values2=array();
        foreach(
$names as $name)
            
$values2[$name]=isset($values[$name]) ? $values[$name] : null;
        return 
$values2;
    }
    else
        return 
$values;
}

Returns all attribute values.

getError() 方法
public string getError(string $attribute)
$attribute string attribute name.
{return} string the error message. Null is returned if no error.
public function getError($attribute)
{
    return isset(
$this->_errors[$attribute]) ? reset($this->_errors[$attribute]) : null;
}

Returns the first error of the specified attribute.

getErrors() 方法
public array getErrors(string $attribute=NULL)
$attribute string attribute name. Use null to retrieve errors for all attributes.
{return} array errors for all attributes or the specified attribute. Empty array is returned if no error.
public function getErrors($attribute=null)
{
    if(
$attribute===null)
        return 
$this->_errors;
    else
        return isset(
$this->_errors[$attribute]) ? $this->_errors[$attribute] : array();
}

Returns the errors for all attribute or a single attribute.

getIterator() 方法
public CMapIterator getIterator()
{return} CMapIterator an iterator for traversing the items in the list.
public function getIterator()
{
    
$attributes=$this->getAttributes();
    return new 
CMapIterator($attributes);
}

Returns an iterator for traversing the attributes in the model. This method is required by the interface IteratorAggregate.

getSafeAttributeNames() 方法
public array getSafeAttributeNames()
{return} array safe attribute names
public function getSafeAttributeNames()
{
    
$attributes=array();
    
$unsafe=array();
    foreach(
$this->getValidators() as $validator)
    {
        if(!
$validator->safe)
        {
            foreach(
$validator->attributes as $name)
                
$unsafe[]=$name;
        }
        else
        {
            foreach(
$validator->attributes as $name)
                
$attributes[$name]=true;
        }
    }

    foreach(
$unsafe as $name)
        unset(
$attributes[$name]);
    return 
array_keys($attributes);
}

Returns the attribute names that are safe to be massively assigned. A safe attribute is one that is associated with a validation rule in the current scenario.

getScenario() 方法
public string getScenario()
{return} string the scenario that this model is in.
public function getScenario()
{
    return 
$this->_scenario;
}

Returns the scenario that this model is used in.

Scenario affects how validation is performed and which attributes can be massively assigned.

A validation rule will be performed when calling validate() if its 'on' option is not set or contains the current scenario value.

And an attribute can be massively assigned if it is associated with a validation rule for the current scenario. Note that an exception is the unsafe validator which marks the associated attributes as unsafe and not allowed to be massively assigned.

getValidatorList() 方法 (可用自 v1.1.2)
public CList getValidatorList()
{return} CList all the validators declared in the model.
public function getValidatorList()
{
    if(
$this->_validators===null)
        
$this->_validators=$this->createValidators();
    return 
$this->_validators;
}

Returns all the validators declared in the model. This method differs from getValidators in that the latter would only return the validators applicable to the current scenario. Also, since this method return a CList object, you may manipulate it by inserting or removing validators (useful in behaviors). For example, $model->validatorList->add($newValidator). The change made to the CList object will persist and reflect in the result of the next call of getValidators.

getValidators() 方法
public array getValidators(string $attribute=NULL)
$attribute string the name of the attribute whose validators should be returned. If this is null, the validators for ALL attributes in the model will be returned.
{return} array the validators applicable to the current scenario.
public function getValidators($attribute=null)
{
    if(
$this->_validators===null)
        
$this->_validators=$this->createValidators();

    
$validators=array();
    
$scenario=$this->getScenario();
    foreach(
$this->_validators as $validator)
    {
        if(
$validator->applyTo($scenario))
        {
            if(
$attribute===null || in_array($attribute,$validator->attributes,true))
                
$validators[]=$validator;
        }
    }
    return 
$validators;
}

Returns the validators applicable to the current scenario.

hasErrors() 方法
public boolean hasErrors(string $attribute=NULL)
$attribute string attribute name. Use null to check all attributes.
{return} boolean whether there is any error.
public function hasErrors($attribute=null)
{
    if(
$attribute===null)
        return 
$this->_errors!==array();
    else
        return isset(
$this->_errors[$attribute]);
}

Returns a value indicating whether there is any validation error.

isAttributeRequired() 方法
public boolean isAttributeRequired(string $attribute)
$attribute string attribute name
{return} boolean whether the attribute is required
public function isAttributeRequired($attribute)
{
    foreach(
$this->getValidators($attribute) as $validator)
    {
        if(
$validator instanceof CRequiredValidator)
            return 
true;
    }
    return 
false;
}

Returns a value indicating whether the attribute is required. This is determined by checking if the attribute is associated with a CRequiredValidator validation rule in the current scenario.

isAttributeSafe() 方法 (可用自 v1.1)
public boolean isAttributeSafe(string $attribute)
$attribute string attribute name
{return} boolean whether the attribute is safe for massive assignments
public function isAttributeSafe($attribute)
{
    
$attributes=$this->getSafeAttributeNames();
    return 
in_array($attribute,$attributes);
}

Returns a value indicating whether the attribute is safe for massive assignments.

offsetExists() 方法
public boolean offsetExists(mixed $offset)
$offset mixed the offset to check on
{return} boolean
public function offsetExists($offset)
{
    return 
property_exists($this,$offset);
}

Returns whether there is an element at the specified offset. This method is required by the interface ArrayAccess.

offsetGet() 方法
public mixed offsetGet(integer $offset)
$offset integer the offset to retrieve element.
{return} mixed the element at the offset, null if no element is found at the offset
public function offsetGet($offset)
{
    return 
$this->$offset;
}

Returns the element at the specified offset. This method is required by the interface ArrayAccess.

offsetSet() 方法
public void offsetSet(integer $offset, mixed $item)
$offset integer the offset to set element
$item mixed the element value
public function offsetSet($offset,$item)
{
    
$this->$offset=$item;
}

Sets the element at the specified offset. This method is required by the interface ArrayAccess.

offsetUnset() 方法
public void offsetUnset(mixed $offset)
$offset mixed the offset to unset element
public function offsetUnset($offset)
{
    unset(
$this->$offset);
}

Unsets the element at the specified offset. This method is required by the interface ArrayAccess.

onAfterConstruct() 方法
public void onAfterConstruct(CEvent $event)
$event CEvent the event parameter
public function onAfterConstruct($event)
{
    
$this->raiseEvent('onAfterConstruct',$event);
}

This event is raised after the model instance is created by new operator.

onAfterValidate() 方法
public void onAfterValidate(CEvent $event)
$event CEvent the event parameter
public function onAfterValidate($event)
{
    
$this->raiseEvent('onAfterValidate',$event);
}

This event is raised after the validation is performed.

onBeforeValidate() 方法
public void onBeforeValidate(CModelEvent $event)
$event CModelEvent the event parameter
public function onBeforeValidate($event)
{
    
$this->raiseEvent('onBeforeValidate',$event);
}

This event is raised before the validation is performed.

onUnsafeAttribute() 方法 (可用自 v1.1.1)
public void onUnsafeAttribute(string $name, mixed $value)
$name string the unsafe attribute name
$value mixed the attribute value
public function onUnsafeAttribute($name,$value)
{
    if(
YII_DEBUG)
        
Yii::log(Yii::t('yii','Failed to set unsafe attribute "{attribute}" of "{class}".',array('{attribute}'=>$name'{class}'=>get_class($this))),CLogger::LEVEL_WARNING);
}

This method is invoked when an unsafe attribute is being massively assigned. The default implementation will log a warning message if YII_DEBUG is on. It does nothing otherwise.

rules() 方法
public array rules()
{return} array validation rules to be applied when validate() is called.
public function rules()
{
    return array();
}

Returns the validation rules for attributes.

This method should be overridden to declare validation rules. Each rule is an array with the following structure:

array('attribute list', 'validator name', 'on'=>'scenario name', ...validation parameters...)
where
  • attribute list: specifies the attributes (separated by commas) to be validated;
  • validator name: specifies the validator to be used. It can be the name of a model class method, the name of a built-in validator, or a validator class (or its path alias). A validation method must have the following signature:
    // $params refers to validation parameters given in the rule
    function validatorName($attribute,$params)
    
    A built-in validator refers to one of the validators declared in CValidator::builtInValidators. And a validator class is a class extending CValidator.
  • on: this specifies the scenarios when the validation rule should be performed. Separate different scenarios with commas. If this option is not set, the rule will be applied in any scenario. Please see scenario for more details about this option.
  • additional parameters are used to initialize the corresponding validator properties. Please refer to individal validator class API for possible properties.


The following are some examples:
array(
    array('username', 'required'),
    array('username', 'length', 'min'=>3, 'max'=>12),
    array('password', 'compare', 'compareAttribute'=>'password2', 'on'=>'register'),
    array('password', 'authenticate', 'on'=>'login'),
);


Note, in order to inherit rules defined in the parent class, a child class needs to merge the parent rules with child rules using functions like array_merge().

参见

setAttributes() 方法
public void setAttributes(array $values, boolean $safeOnly=true)
$values array attribute values (name=>value) to be set.
$safeOnly boolean whether the assignments should only be done to the safe attributes. A safe attribute is one that is associated with a validation rule in the current scenario.
public function setAttributes($values,$safeOnly=true)
{
    if(!
is_array($values))
        return;
    
$attributes=array_flip($safeOnly $this->getSafeAttributeNames() : $this->attributeNames());
    foreach(
$values as $name=>$value)
    {
        if(isset(
$attributes[$name]))
            
$this->$name=$value;
        else if(
$safeOnly)
            
$this->onUnsafeAttribute($name,$value);
    }
}

Sets the attribute values in a massive way.

setScenario() 方法
public void setScenario(string $value)
$value string the scenario that this model is in.
public function setScenario($value)
{
    
$this->_scenario=$value;
}

Sets the scenario for the model.

参见

unsetAttributes() 方法 (可用自 v1.1.3)
public void unsetAttributes(array $names=NULL)
$names array list of attributes to be set null. If this parameter is not given, all attributes as specified by attributeNames will have their values unset.
public function unsetAttributes($names=null)
{
    if(
$names===null)
        
$names=$this->attributeNames();
    foreach(
$names as $name)
        
$this->$name=null;
}

Sets the attributes to be null.

validate() 方法
public boolean validate(array $attributes=NULL, boolean $clearErrors=true)
$attributes array list of attributes that should be validated. Defaults to null, meaning any attribute listed in the applicable validation rules should be validated. If this parameter is given as a list of attributes, only the listed attributes will be validated.
$clearErrors boolean whether to call clearErrors before performing validation
{return} boolean whether the validation is successful without any error.
public function validate($attributes=null$clearErrors=true)
{
    if(
$clearErrors)
        
$this->clearErrors();
    if(
$this->beforeValidate())
    {
        foreach(
$this->getValidators() as $validator)
            
$validator->validate($this,$attributes);
        
$this->afterValidate();
        return !
$this->hasErrors();
    }
    else
        return 
false;
}

Performs the validation.

This method executes the validation rules as declared in rules. Only the rules applicable to the current scenario will be executed. A rule is considered applicable to a scenario if its 'on' option is not set or contains the scenario.

Errors found during the validation can be retrieved via getErrors.