0 follower

CModel

Package system.base
Inheritance abstract class CModel » CComponent
Implements IteratorAggregate, Traversable, ArrayAccess
Subclasses CActiveRecord, CFormModel
Since 1.0
Version $Id$
Source Code framework/base/CModel.php
CModel is the base class providing the common features needed by data model objects.

CModel defines the basic framework for data models that need to be validated.

Public Properties

Hide inherited properties

PropertyTypeDescriptionDefined By
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 in. CModel
validators array list of validators created according to rules. CModel

Public Methods

Hide inherited methods

MethodDescriptionDefined By
__call() Calls the named method which is not a class method. CComponent
__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
__unset() Sets a component property to be null. CComponent
addError() Adds a new error to the specified attribute. CModel
addErrors() Adds a list of errors. CModel
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
attributeLabels() Returns the attribute labels. CModel
attributeNames() Returns the list of attribute names of the model. CModel
behaviors() Returns a list of behaviors that this model should behave as. CModel
canGetProperty() Determines whether a property can be read. CComponent
canSetProperty() Determines whether a property can be set. CComponent
clearErrors() Removes errors for all attributes or a single attribute. CModel
createValidators() CModel
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
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() Returns the list of attached event handlers for an event. 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 in. CModel
getValidators() Returns list of validators created according to rules. CModel
getValidatorsForAttribute() Returns the validators that are applied to the specified attribute under the specified scenario. CModel
hasErrors() Returns a value indicating whether there is any validation error. CModel
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
isAttributeRequired() Returns a value indicating whether the attribute is required. 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
onAfterValidate() This event is raised after the validation is performed. CModel
onBeforeValidate() This event is raised before the validation is performed. CModel
raiseEvent() Raises an event. CComponent
rules() Returns the validation rules for attributes. CModel
safeAttributes() Returns the name of attributes that are safe to be massively assigned. CModel
setAttributes() Sets the attribute values in a massive way. CModel
setScenario() Sets the scenario that this model is in. CModel
validate() Performs the validation. CModel

Protected Methods

Hide inherited methods

MethodDescriptionDefined By
afterValidate() This method is invoked after validation ends. CModel
beforeValidate() This method is invoked before validation starts. CModel

Events

Hide inherited events

EventDescriptionDefined By
onBeforeValidate This event is raised before the validation is performed. CModel
onAfterValidate This event is raised after the validation is performed. CModel

Property Details

attributes property
public array getAttributes(array $names=NULL)
public void setAttributes(array $values, mixed $scenario='')

Returns all attribute values.

errors property read-only
public array getErrors(string $attribute=NULL)

Returns the errors for all attribute or a single attribute.

iterator property read-only

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

safeAttributeNames property read-only (available since v1.0.2)
public array getSafeAttributeNames(string $scenario='')

Returns the attribute names that are safe to be massively assigned. This method is internally used by setAttributes.

Given a scenario, this method will choose the folllowing result from the list returned by safeAttributes:

  • If the scenario is false, attributes specified by attributeNames will be returned.
  • If the scenario is not an empty string, and it is found as a key in safeAttributes, the corresponding attributes will be returned;
  • If the scenario is an empty string, or if it is not found in safeAttributes, the first set of attributes in safeAttributes will be returned.

scenario property (available since v1.0.4)
public string getScenario()
public void setScenario(string $value)

Returns the scenario that this model is in. Scenario affects how massive attribute assignment is carried and which validations should be performed. An attribute can be declared as safe for massive assignment and requiring validation under certain scenarios.

validators property read-only (available since v1.0.1)
public array getValidators()

list of validators created according to rules.

Method Details

addError() method
public void addError(string $attribute, string $error)
$attribute string attribute name
$error string new error message
Source Code: framework/base/CModel.php#372 (show)
public function addError($attribute,$error)
{
    
$this->_errors[$attribute][]=$error;
}

Adds a new error to the specified attribute.

addErrors() method (available since v1.0.5)
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.
Source Code: framework/base/CModel.php#385 (show)
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.

afterValidate() method
protected void afterValidate(string $scenario)
$scenario string the set of the validation rules that should be applied. See validate for more details about this parameter. NOTE: this parameter has been available since version 1.0.1.
Source Code: framework/base/CModel.php#222 (show)
protected function afterValidate($scenario)
{
    
$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() method
public array attributeLabels()
{return} array attribute labels (name=>label)
Source Code: framework/base/CModel.php#151 (show)
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() method (available since v1.0.1)
abstract public array attributeNames()
{return} array list of attribute names.
Source Code: framework/base/CModel.php#33 (show)
abstract public function attributeNames();

Returns the list of attribute names of the model.

beforeValidate() method
protected boolean beforeValidate(string $scenario)
$scenario string the set of the validation rules that should be applied. See validate for more details about this parameter. NOTE: this parameter has been available since version 1.0.1.
{return} boolean whether validation should be executed. Defaults to true.
Source Code: framework/base/CModel.php#206 (show)
protected function beforeValidate($scenario)
{
    
$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() method (available since v1.0.2)
public array behaviors()
{return} array the behavior configurations (behavior name=>behavior configuration)
Source Code: framework/base/CModel.php#134 (show)
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() method
public void clearErrors(string $attribute=NULL)
$attribute string attribute name. Use null to remove errors for all attribute.
Source Code: framework/base/CModel.php#403 (show)
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() method
public array createValidators()
{return} array validators built based on rules().
Source Code: framework/base/CModel.php#414 (show)
public function createValidators()
{
    
$validators=array();
    foreach(
$this->rules() as $rule)
    {
        if(isset(
$rule[0],$rule[1]))  // attributes, validator name
            
$validators[]=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;
}

generateAttributeLabel() method
public string generateAttributeLabel(string $name)
$name string the column name
{return} string the attribute label
Source Code: framework/base/CModel.php#436 (show)
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() method
public string getAttributeLabel(string $attribute)
$attribute string the attribute name
{return} string the attribute label
Source Code: framework/base/CModel.php#321 (show)
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() method
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).
Source Code: framework/base/CModel.php#448 (show)
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() method (available since v1.0.2)
public string getError(string $attribute)
$attribute string attribute name.
{return} string the error message. Null is returned if no error.
Source Code: framework/base/CModel.php#362 (show)
public function getError($attribute)
{
    return isset(
$this->_errors[$attribute]) ? reset($this->_errors[$attribute]) : null;
}

Returns the first error of the specified attribute.

getErrors() method
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.
Source Code: framework/base/CModel.php#348 (show)
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() method
public CMapIterator getIterator()
{return} CMapIterator an iterator for traversing the items in the list.
Source Code: framework/base/CModel.php#574 (show)
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() method (available since v1.0.2)
public array getSafeAttributeNames(string $scenario='')
$scenario string scenario name. Note that as of version 1.0.4, if this parameter is an empty string, it will take the scenario property value.
{return} array safe attribute names
Source Code: framework/base/CModel.php#548 (show)
public function getSafeAttributeNames($scenario='')
{
    if(
$scenario==='')
        
$scenario=$this->getScenario();

    if(
$scenario===false)
        return 
$this->attributeNames();

    
$attributes=$this->safeAttributes();
    if(!
is_array($attributes))
        
$attributes=array($attributes);

    if(
$scenario!=='' && isset($attributes[$scenario]))
        return 
$this->ensureArray($attributes[$scenario]);

    if(isset(
$attributes[0], $attributes[1]))
        return 
$attributes;
    else
        return isset(
$attributes[0]) ? $this->ensureArray($attributes[0]) : array();
}

Returns the attribute names that are safe to be massively assigned. This method is internally used by setAttributes.

Given a scenario, this method will choose the folllowing result from the list returned by safeAttributes:

  • If the scenario is false, attributes specified by attributeNames will be returned.
  • If the scenario is not an empty string, and it is found as a key in safeAttributes, the corresponding attributes will be returned;
  • If the scenario is an empty string, or if it is not found in safeAttributes, the first set of attributes in safeAttributes will be returned.

getScenario() method (available since v1.0.4)
public string getScenario()
{return} string the scenario that this model is in. Defaults to empty.
Source Code: framework/base/CModel.php#511 (show)
public function getScenario()
{
    return 
$this->_se;
}

Returns the scenario that this model is in. Scenario affects how massive attribute assignment is carried and which validations should be performed. An attribute can be declared as safe for massive assignment and requiring validation under certain scenarios.

getValidators() method (available since v1.0.1)
public array getValidators()
{return} array list of validators created according to rules.
Source Code: framework/base/CModel.php#251 (show)
public function getValidators()
{
    return 
$this->createValidators();
}

getValidatorsForAttribute() method (available since v1.0.2)
public array getValidatorsForAttribute(string $attribute, string $scenario='')
$attribute string the attribute name
$scenario string the scenario name. As of version 1.0.4, this parameter is deprecated, and the scenario property is the preferred way of specifying the scenario. In particular, when this parameter is empty, the scenario property value will be used as the effective scenario.
{return} array the validators for the attribute. An empty array is returned if no validator applies to the attribute.
Source Code: framework/base/CModel.php#266 (show)
public function getValidatorsForAttribute($attribute,$scenario='')
{
    if(
$scenario==='')
        
$scenario=$this->getScenario();

    if(
$this->_va===null)
    {
        
$this->_va=array();
        foreach(
$this->getValidators() as $validator)
        {
            foreach(
$validator->attributes as $att)
                
$this->_va[$att][]=$validator;
        }
    }
    
$validators=array();
    if(isset(
$this->_va[$attribute]))
    {
        foreach(
$this->_va[$attribute] as $validator)
        {
            if(
$validator->applyTo($scenario))
                
$validators[]=$validator;
        }
    }
    return 
$validators;
}

Returns the validators that are applied to the specified attribute under the specified scenario.

hasErrors() method
public boolean hasErrors(string $attribute=NULL)
$attribute string attribute name. Use null to check all attributes.
{return} boolean whether there is any error.
Source Code: framework/base/CModel.php#335 (show)
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() method (available since v1.0.2)
public boolean isAttributeRequired(string $attribute, string $scenario='')
$attribute string attribute name
$scenario string validation scenario. As of version 1.0.4, this parameter is deprecated, and the scenario property is the preferred way of specifying the scenario. In particular, when this parameter is empty, the scenario property value will be used as the effective scenario.
{return} boolean whether the attribute is required
Source Code: framework/base/CModel.php#303 (show)
public function isAttributeRequired($attribute,$scenario='')
{
    
$validators=$this->getValidatorsForAttribute($attribute,$scenario);
    foreach(
$validators as $validator)
    {
        if(
$validator instanceof CRequiredValidator)
            return 
true;
    }
    return 
false;
}

Returns a value indicating whether the attribute is required. This is determined based on the validation rules declared in rules.

offsetExists() method (available since v1.0.2)
public boolean offsetExists(mixed $offset)
$offset mixed the offset to check on
{return} boolean
Source Code: framework/base/CModel.php#587 (show)
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() method (available since v1.0.2)
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
Source Code: framework/base/CModel.php#599 (show)
public function offsetGet($offset)
{
    return 
$this->$offset;
}

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

offsetSet() method (available since v1.0.2)
public void offsetSet(integer $offset, mixed $item)
$offset integer the offset to set element
$item mixed the element value
Source Code: framework/base/CModel.php#611 (show)
public function offsetSet($offset,$item)
{
    
$this->$offset=$item;
}

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

offsetUnset() method (available since v1.0.2)
public void offsetUnset(mixed $offset)
$offset mixed the offset to unset element
Source Code: framework/base/CModel.php#622 (show)
public function offsetUnset($offset)
{
    unset(
$this->$offset);
}

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

onAfterValidate() method (available since v1.0.2)
public void onAfterValidate(CEvent $event)
$event CEvent the event parameter
Source Code: framework/base/CModel.php#242 (show)
public function onAfterValidate($event)
{
    
$this->raiseEvent('onAfterValidate',$event);
}

This event is raised after the validation is performed.

onBeforeValidate() method (available since v1.0.2)
public void onBeforeValidate(CModelEvent $event)
$event CModelEvent the event parameter
Source Code: framework/base/CModel.php#232 (show)
public function onBeforeValidate($event)
{
    
$this->raiseEvent('onBeforeValidate',$event);
}

This event is raised before the validation is performed.

rules() method
public array rules()
{return} array validation rules to be applied when validate() is called.
Source Code: framework/base/CModel.php#108 (show)
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 validate for more details about this option.
  • additional parameters are used to initialize the corresponding validator properties. Please refer to inidividal 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().

See Also

safeAttributes() method (available since v1.0.2)
abstract public array safeAttributes()
{return} array list of safe attribute names.
Source Code: framework/base/CModel.php#63 (show)
abstract public function safeAttributes();

Returns the name of attributes that are safe to be massively assigned. For details about massive assignment, see the documentation of child classes (e.g. CActiveRecord::setAttributes, CFormModel::setAttributes).

The returned value of this method should be in the following structure:

array(
   // these attributes can be massively assigned in any scenario
   // that is not explicitly specified below
   'attr1, attr2, ...',

   // these attributes can be massively assigned only in scenario 1
   'scenario1' => 'attr2, attr3, ...',

   // these attributes can be massively assigned only in scenario 2
   'scenario2' => 'attr1, attr3, ...',
);
If the model is not scenario-sensitive (i.e., it is only used in one scenario, or all scenarios share the same set of safe attributes), the return value can be simplified as a single string:
'attr1, attr2, ...'

setAttributes() method
public void setAttributes(array $values, mixed $scenario='')
$values array attribute values (name=>value) to be set.
$scenario mixed scenario name. Note that as of version 1.0.4, if this parameter is an empty string, it will take the scenario property value.
Source Code: framework/base/CModel.php#487 (show)
public function setAttributes($values,$scenario='')
{
    if(
$scenario==='')
        
$scenario=$this->getScenario();

    if(
is_array($values))
    {
        
$attributes=array_flip($this->getSafeAttributeNames($scenario));
        foreach(
$values as $name=>$value)
        {
            if(isset(
$attributes[$name]))
                
$this->$name=$value;
        }
    }
}

Sets the attribute values in a massive way. Only safe attributes will be assigned by this method.

Given a scenario, this method will assign values to the attributes that appear in the list returned by safeAttributes for the specified scenario:

  • If the scenario is false, attributes specified by attributeNames will be assigned.
  • If the scenario is not an empty string, and it is found as a key in safeAttributes, the corresponding attributes will be assigned;
  • If the scenario is an empty string, or if it is not found in safeAttributes, the first set of attributes in safeAttributes will be assigned.

setScenario() method (available since v1.0.4)
public void setScenario(string $value)
$value string the scenario that this model is in.
Source Code: framework/base/CModel.php#521 (show)
public function setScenario($value)
{
    
$this->_se=$value;
}

See Also

validate() method
public boolean validate(string $scenario='', array $attributes=NULL)
$scenario string the scenario that the validation rules should be applied. Defaults to empty string, meaning only those validation rules whose "on" option is empty will be applied. If this is a non-empty string, only the validation rules whose "on" option is empty or contains the specified scenario will be applied. As of version 1.0.4, this parameter is deprecated, and the scenario property is the preferred way of specifying the scenario. In particular, when this parameter is empty, the scenario property value will be used as the effective scenario.
$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.
{return} boolean whether the validation is successful without any error.
Source Code: framework/base/CModel.php#176 (show)
public function validate($scenario='',$attributes=null)
{
    if(
$scenario==='')
        
$scenario=$this->getScenario();

    
$this->clearErrors();
    if(
$this->beforeValidate($scenario))
    {
        foreach(
$this->getValidators() as $validator)
        {
            if(
$validator->applyTo($scenario))
                
$validator->validate($this,$attributes);
        }
        
$this->afterValidate($scenario);
        return !
$this->hasErrors();
    }
    else
        return 
false;
}

Performs the validation. This method executes the validation rule as declared in rules. Errors found during the validation can be retrieved via getErrors.