CModel

Property Details

attributes property

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

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

public CMapIterator getIterator()

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

safeAttributeNames property read-only

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 property

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 'except' value does not contain current scenario value while '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 property read-only (available since v1.1.2)

public CList getValidatorList()

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

public array getValidators(string $attribute=NULL)

Returns the validators applicable to the current scenario.

Method Details

addError() method

public void addError(string $attribute, string $error)

public function addError($attribute,$error)
{
    $this->_errors[$attribute][]=$error;
}

Adds a new error to the specified attribute.

addErrors() method

public void addErrors(array $errors)

public function addErrors($errors)
{
    foreach($errors as $attribute=>$error)
    {
        if(is_array($error))
        {
            foreach($error as $e)
                $this->addError($attribute, $e);
        }
        else
            $this->addError($attribute, $error);
    }
}

Adds a list of errors.

afterConstruct() method

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() method

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() method

public array attributeLabels()

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

abstract public array attributeNames()

abstract public function attributeNames();

Returns the list of attribute names of the model.

beforeValidate() method

protected boolean beforeValidate()

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() method

public array behaviors()

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',
)

clearErrors() method

public void clearErrors(string $attribute=NULL)

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 CList createValidators()

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() method

public string generateAttributeLabel(string $name)

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)

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)

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

public string getError(string $attribute)

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)

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()

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

public array getSafeAttributeNames()

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() method

public string getScenario()

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 'except' value does not contain current scenario value while '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() method (available since v1.1.2)

public CList getValidatorList()

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() method

public array getValidators(string $attribute=NULL)

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() method

public boolean hasErrors(string $attribute=NULL)

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

public boolean isAttributeRequired(string $attribute)

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() method (available since v1.1)

public boolean isAttributeSafe(string $attribute)

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() method

public boolean offsetExists(mixed $offset)

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

public mixed offsetGet(integer $offset)

public function offsetGet($offset)
{
    return $this->$offset;
}

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

offsetSet() method

public void offsetSet(integer $offset, mixed $item)

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

public void offsetUnset(mixed $offset)

public function offsetUnset($offset)
{
    unset($this->$offset);
}

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

onAfterConstruct() method

public void onAfterConstruct(CEvent $event)

public function onAfterConstruct($event)
{
    $this->raiseEvent('onAfterConstruct',$event);
}

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

onAfterValidate() method

public void onAfterValidate(CEvent $event)

public function onAfterValidate($event)
{
    $this->raiseEvent('onAfterValidate',$event);
}

This event is raised after the validation is performed.

onBeforeValidate() method

public void onBeforeValidate(CModelEvent $event)

public function onBeforeValidate($event)
{
    $this->raiseEvent('onBeforeValidate',$event);
}

This event is raised before the validation is performed.

onUnsafeAttribute() method (available since v1.1.1)

public void onUnsafeAttribute(string $name, mixed $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() method

public array rules()

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...)

• 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 that is not listed in "except". Please see scenario for more details about this option.
• except: this specifies the scenarios when the validation rule should not be performed. Separate different scenarios with commas. Please see scenario for more details about this option.
• additional parameters are used to initialize the corresponding validator properties. Please refer to individual validator class API for possible properties.

array(
    array('username', 'required'),
    array('username', 'length', 'min'=>3, 'max'=>12),
    array('password', 'compare', 'compareAttribute'=>'password2', 'on'=>'register'),
    array('password', 'authenticate', 'on'=>'login'),
);

setAttributes() method

public void setAttributes(array $values, boolean $safeOnly=true)

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;
        elseif($safeOnly)
            $this->onUnsafeAttribute($name,$value);
    }
}

Sets the attribute values in a massive way.

setScenario() method

public void setScenario(string $value)

public function setScenario($value)
{
    $this->_scenario=$value;
}

Sets the scenario for the model.

unsetAttributes() method (available since v1.1.3)

public void unsetAttributes(array $names=NULL)

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() method

public boolean validate(array $attributes=NULL, boolean $clearErrors=true)

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.