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

Property Details

Returns all attribute values.

Returns the errors for all attribute or a single attribute.

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

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.

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.

list of validators created according to rules.

Method Details

public void addError(string $attribute, string $error)
$attribute	string	attribute name
$error	string	new error message

Adds a new error to the specified attribute.

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.

Adds a list of errors.

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.

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.

public array attributeLabels()
{return}	array	attribute labels (name=>label)

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

abstract public array attributeNames()
{return}	array	list of attribute names.

Returns the list of attribute names of the model.

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.

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.

public array behaviors()
{return}	array	the behavior configurations (behavior name=>behavior configuration)

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.

public void clearErrors(string $attribute=NULL)
$attribute	string	attribute name. Use null to remove errors for all attribute.

Removes errors for all attributes or a single attribute.

public array createValidators()
{return}	array	validators built based on rules().

public string generateAttributeLabel(string $name)
$name	string	the column name
{return}	string	the attribute label

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

public string getAttributeLabel(string $attribute)
$attribute	string	the attribute name
{return}	string	the attribute label

Returns the text label for the specified attribute.

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

Returns all attribute values.

public string getError(string $attribute)
$attribute	string	attribute name.
{return}	string	the error message. Null is returned if no error.

Returns the first error of the specified attribute.

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.

Returns the errors for all attribute or a single attribute.

public CMapIterator getIterator()
{return}	CMapIterator	an iterator for traversing the items in the list.

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

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

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.

public string getScenario()
{return}	string	the scenario that this model is in. Defaults to empty.

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.

public array getValidators()
{return}	array	list of validators created according to rules.

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.

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

public boolean hasErrors(string $attribute=NULL)
$attribute	string	attribute name. Use null to check all attributes.
{return}	boolean	whether there is any error.

Returns a value indicating whether there is any validation error.

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

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

public boolean offsetExists(mixed $offset)
$offset	mixed	the offset to check on
{return}	boolean

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

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

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

public void offsetSet(integer $offset, mixed $item)
$offset	integer	the offset to set element
$item	mixed	the element value

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

public void offsetUnset(mixed $offset)
$offset	mixed	the offset to unset element

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

public void onAfterValidate(CEvent $event)
$event	CEvent	the event parameter

This event is raised after the validation is performed.

public void onBeforeValidate(CModelEvent $event)
$event	CModelEvent	the event parameter

This event is raised before the validation is performed.

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

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

abstract public array safeAttributes()
{return}	array	list of safe attribute names.

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

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.

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.

public void setScenario(string $value)
$value	string	the scenario that this model is in.

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.

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