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 $ |
源码 | framework/base/CModel.php |
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 属性 只读 public CMapIterator getIterator()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.
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.
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 |
publicfunctionaddError($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. |
publicfunctionaddErrors($errors)
{
foreach($errorsas$attribute=>$error)
{
if(is_array($error))
{
foreach($erroras$e)
$this->_errors[$attribute][]=$e;
}
else
$this->_errors[$attribute][]=$error;
}
}
Adds a list of errors.
afterConstruct() 方法protected void afterConstruct() |
protectedfunctionafterConstruct()
{
if($this->hasEventHandler('onAfterConstruct'))
$this->onAfterConstruct(newCEvent($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() |
protectedfunctionafterValidate()
{
$this->onAfterValidate(newCEvent($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) |
publicfunctionattributeLabels()
{
returnarray();
}
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().
参见
- generateAttributeLabel
abstract public array attributeNames() | ||
{return} | array | 模型属性名称的列表。 |
abstractpublicfunctionattributeNames();
返回模型属性名称的列表。
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. |
protectedfunctionbeforeValidate()
{
$event=newCModelEvent($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) |
publicfunctionbehaviors()
{
returnarray();
}
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. |
publicfunctionclearErrors($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(). |
publicfunctioncreateValidators()
{
$validators=newCList;
foreach($this->rules()as$rule)
{
if(isset($rule[0],$rule[1]))//attributes,validatorname
$validators->add(CValidator::createValidator($rule[1],$this,$rule[0],array_slice($rule,2)));
else
thrownewCException(Yii::t('yii','{class}hasaninvalidvalidationrule.Therulemustspecifyattributestobevalidatedandthevalidatorname.',
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 |
publicfunctiongenerateAttributeLabel($name)
{
returnucwords(trim(strtolower(str_replace(array('-','_','.'),'',preg_replace('/(?<![A-Z])[A-Z]/','',$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 |
publicfunctiongetAttributeLabel($attribute)
{
$labels=$this->attributeLabels();
if(isset($labels[$attribute]))
return$labels[$attribute];
else
return$this->generateAttributeLabel($attribute);
}
Returns the text label for the specified attribute.
参见
- generateAttributeLabel
- attributeLabels
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). |
publicfunctiongetAttributes($names=null)
{
$values=array();
foreach($this->attributeNames()as$name)
$values[$name]=$this->$name;
if(is_array($names))
{
$values2=array();
foreach($namesas$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. |
publicfunctiongetError($attribute)
{
returnisset($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. |
publicfunctiongetErrors($attribute=null)
{
if($attribute===null)
return$this->_errors;
else
returnisset($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. |
publicfunctiongetIterator()
{
$attributes=$this->getAttributes();
returnnewCMapIterator($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 |
publicfunctiongetSafeAttributeNames()
{
$attributes=array();
$unsafe=array();
foreach($this->getValidators()as$validator)
{
if(!$validator->safe)
{
foreach($validator->attributesas$name)
$unsafe[]=$name;
}
else
{
foreach($validator->attributesas$name)
$attributes[$name]=true;
}
}
foreach($unsafeas$name)
unset($attributes[$name]);
returnarray_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. |
publicfunctiongetScenario()
{
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.
public CList getValidatorList() | ||
{return} | CList | all the validators declared in the model. |
publicfunctiongetValidatorList()
{
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.
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. |
publicfunctiongetValidators($attribute=null)
{
if($this->_validators===null)
$this->_validators=$this->createValidators();
$validators=array();
$scenario=$this->getScenario();
foreach($this->_validatorsas$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. |
publicfunctionhasErrors($attribute=null)
{
if($attribute===null)
return$this->_errors!==array();
else
returnisset($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 |
publicfunctionisAttributeRequired($attribute)
{
foreach($this->getValidators($attribute)as$validator)
{
if($validatorinstanceofCRequiredValidator)
returntrue;
}
returnfalse;
}
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 |
publicfunctionisAttributeSafe($attribute)
{
$attributes=$this->getSafeAttributeNames();
returnin_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 |
publicfunctionoffsetExists($offset)
{
returnproperty_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 |
publicfunctionoffsetGet($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 |
publicfunctionoffsetSet($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 |
publicfunctionoffsetUnset($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 |
publicfunctiononAfterConstruct($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 |
publicfunctiononAfterValidate($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 |
publicfunctiononBeforeValidate($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 |
publicfunctiononUnsafeAttribute($name,$value)
{
if(YII_DEBUG)
Yii::log(Yii::t('yii','Failedtosetunsafeattribute"{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. |
publicfunctionrules()
{
returnarray();
}
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 classmethod, 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 rulewill 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().
参见
- scenario
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. |
publicfunctionsetAttributes($values,$safeOnly=true)
{
if(!is_array($values))
return;
$attributes=array_flip($safeOnly?$this->getSafeAttributeNames():$this->attributeNames());
foreach($valuesas$name=>$value)
{
if(isset($attributes[$name]))
$this->$name=$value;
elseif($safeOnly)
$this->onUnsafeAttribute($name,$value);
}
}
Sets the attribute values in a massive way.
参见
- getSafeAttributeNames
- attributeNames
public void setScenario(string $value) | ||
$value | string | the scenario that this model is in. |
publicfunctionsetScenario($value)
{
$this->_scenario=$value;
}
Sets the scenario for the model.
参见
- getScenario
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. |
publicfunctionunsetAttributes($names=null)
{
if($names===null)
$names=$this->attributeNames();
foreach($namesas$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. |
publicfunctionvalidate($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
returnfalse;
}
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.
参见
- beforeValidate
- afterValidate