PHP Class yii\base\Model

Model implements the following commonly used features: - attribute declaration: by default, every public class member is considered as a model attribute - attribute labels: each attribute may be associated with a label for display purpose - massive attribute assignment - scenario-based validation Model also raises the following events when performing data validation: - [[EVENT_BEFORE_VALIDATE]]: an event raised at the beginning of Model::validate - [[EVENT_AFTER_VALIDATE]]: an event raised at the end of Model::validate You may directly use Model to store model data, or extend it with customization. For more details and usage information on Model, see the guide article on models.

Since: 2.0

Author: Qiang Xue ([email protected])

Inheritance: extends Component, implements IteratorAggregat\IteratorAggregate, implements ArrayAcces\ArrayAccess, implements yii\base\Arrayable, use trait ArrayableTrait

显示文件 Open project: yiisoft/yii2 Class Usage Examples

Public Methods

Method	Description
activeAttributes ( ) : string[]	Returns the attribute names that are subject to validation in the current scenario.
addError ( string $attribute, string $error = '' )	Adds a new error to the specified attribute.
addErrors ( array $items )	Adds a list of errors.
afterValidate ( )	This method is invoked after validation ends.
attributeHints ( ) : array	Returns the attribute hints.
attributeLabels ( ) : array	Returns the attribute labels.
attributes ( ) : array	Returns the list of attribute names.
beforeValidate ( ) : boolean	This method is invoked before validation starts.
clearErrors ( string $attribute = null )	Removes errors for all attributes or a single attribute.
createValidators ( ) : ArrayObject	Creates validator objects based on the validation rules specified in Model::rules.
fields ( ) : array	Returns the list of fields that should be returned by default by [[toArray()]] when no specific fields are specified.
formName ( ) : string	Returns the form name that this model class should use.
generateAttributeLabel ( string $name ) : string	Generates a user friendly attribute label based on the give attribute name.
getActiveValidators ( string $attribute = null ) : Validator[]	Returns the validators applicable to the current [[scenario]].
getAttributeHint ( string $attribute ) : string	Returns the text hint for the specified attribute.
getAttributeLabel ( string $attribute ) : string	Returns the text label for the specified attribute.
getAttributes ( array $names = null, array $except = [] ) : array	Returns attribute values.
getErrors ( string $attribute = null ) : array	Returns the errors for all attributes or a single attribute.
getFirstError ( string $attribute ) : string	Returns the first error of the specified attribute.
getFirstErrors ( ) : array	Returns the first error of every attribute in the model.
getIterator ( ) : ArrayIterator	Returns an iterator for traversing the attributes in the model.
getScenario ( ) : string	Returns the scenario that this model is used in.
getValidators ( ) : ArrayObjec\ArrayObject \| Validator[]	Returns all the validators declared in Model::rules.
hasErrors ( string \| null $attribute = null ) : boolean	Returns a value indicating whether there is any validation error.
isAttributeActive ( string $attribute ) : boolean	Returns a value indicating whether the attribute is active in the current scenario.
isAttributeRequired ( string $attribute ) : boolean	Returns a value indicating whether the attribute is required.
isAttributeSafe ( string $attribute ) : boolean	Returns a value indicating whether the attribute is safe for massive assignments.
load ( array $data, string $formName = null ) : boolean	Populates the model with input data.
loadMultiple ( array $models, array $data, string $formName = null ) : boolean	Populates a set of models with the data from end user.
offsetExists ( mixed $offset ) : boolean	Returns whether there is an element at the specified offset.
offsetGet ( mixed $offset ) : mixed	Returns the element at the specified offset.
offsetSet ( integer $offset, mixed $item )	Sets the element at the specified offset.
offsetUnset ( mixed $offset )	Sets the element value at the specified offset to null.
onUnsafeAttribute ( string $name, mixed $value )	This method is invoked when an unsafe attribute is being massively assigned.
rules ( ) : array	Returns the validation rules for attributes.
safeAttributes ( ) : string[]	Returns the attribute names that are safe to be massively assigned in the current scenario.
scenarios ( ) : array	Returns a list of scenarios and the corresponding active attributes.
setAttributes ( array $values, boolean $safeOnly = true )	Sets the attribute values in a massive way.
setScenario ( string $value )	Sets the scenario for the model.
validate ( array $attributeNames = null, boolean $clearErrors = true ) : boolean	Performs the data validation.
validateMultiple ( array $models, array $attributeNames = null ) : boolean	Validates multiple models.

Method Details

activeAttributes() public method

Returns the attribute names that are subject to validation in the current scenario.

public activeAttributes ( ) : string[]
return	string[]	safe attribute names

addError() public method

Adds a new error to the specified attribute.

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

addErrors() public method

Adds a list of errors.

Since: 2.0.2

public addErrors ( array $items )
$items	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.

afterValidate() public method

The default implementation raises an afterValidate 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 afterValidate ( )

attributeHints() public method

Attribute hints are mainly used for display purpose. For example, given an attribute isPublic, we can declare a hint Whether the post should be visible for not logged in users, which provides user-friendly description of the attribute meaning and can be displayed to end users. Unlike label hint will not be generated, if its explicit declaration is omitted. Note, in order to inherit hints defined in the parent class, a child class needs to merge the parent hints with child hints using functions such as array_merge().

Since: 2.0.4

public attributeHints ( ) : array
return	array	attribute hints (name => hint)

attributeLabels() public method

Attribute labels are mainly used for display purpose. For example, given an attribute firstName, we can declare a label First Name which is more user-friendly and can be displayed to end users. By default an attribute label is generated using Model::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 such as array_merge().

attributes() public method

By default, this method returns all public non-static properties of the class. You may override this method to change the default behavior.

public attributes ( ) : array
return	array	list of attribute names.

beforeValidate() public method

The default implementation raises a beforeValidate 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 beforeValidate ( ) : boolean
return	boolean	whether the validation should be executed. Defaults to true. If false is returned, the validation will stop and the model is considered invalid.

clearErrors() public method

Removes errors for all attributes or a single attribute.

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

createValidators() public method

Unlike Model::getValidators, each time this method is called, a new list of validators will be returned.

public createValidators ( ) : ArrayObject
return	ArrayObject	validators

fields() public method

A field is a named element in the returned array by [[toArray()]]. This method should return an array of field names or field definitions. If the former, the field name will be treated as an object property name whose value will be used as the field value. If the latter, the array key should be the field name while the array value should be the corresponding field definition which can be either an object property name or a PHP callable returning the corresponding field value. The signature of the callable should be: php function ($model, $field) { return field value } For example, the following code declares four fields: - email: the field name is the same as the property name email; - firstName and lastName: the field names are firstName and lastName, and their values are obtained from the first_name and last_name properties; - fullName: the field name is fullName. Its value is obtained by concatenating first_name and last_name. php return [ 'email', 'firstName' => 'first_name', 'lastName' => 'last_name', 'fullName' => function ($model) { return $model->first_name . ' ' . $model->last_name; }, ]; In this method, you may also want to return different lists of fields based on some context information. For example, depending on [[scenario]] or the privilege of the current application user, you may return different sets of visible fields or filter out some fields. The default implementation of this method returns Model::attributes indexed by the same attribute names.

formName() public method

The form name is mainly used by ActiveForm to determine how to name the input fields for the attributes in a model. If the form name is "A" and an attribute name is "b", then the corresponding input name would be "A[b]". If the form name is an empty string, then the input name would be "b". The purpose of the above naming schema is that for forms which contain multiple different models, the attributes of each model are grouped in sub-arrays of the POST-data and it is easier to differentiate between them. By default, this method returns the model class name (without the namespace part) as the form name. You may override it when the model is used in different forms.

generateAttributeLabel() public method

This is done by replacing underscores, dashes and dots with blanks and changing the first letter of each word to upper case. For example, 'department_name' or 'DepartmentName' will generate 'Department Name'.

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

getActiveValidators() public method

Returns the validators applicable to the current [[scenario]].

public getActiveValidators ( string $attribute = null ) : Validator[]
$attribute	string	the name of the attribute whose applicable validators should be returned. If this is null, the validators for ALL attributes in the model will be returned.
return	yii\validators\Validator[]	the validators applicable to the current [[scenario]].

getAttributeHint() public method

Returns the text hint for the specified attribute.

getAttributeLabel() public method

Returns the text label for the specified attribute.

getAttributes() public method

Returns attribute values.

public getAttributes ( array $names = null, array $except = [] ) : array
$names	array	list of attributes whose value needs to be returned. Defaults to null, meaning all attributes listed in [[attributes()]] will be returned. If it is an array, only the attributes in the array will be returned.
$except	array	list of attributes whose value should NOT be returned.
return	array	attribute values (name => value).

getErrors() public method

Returns the errors for all attributes or a single attribute.

getFirstError() public method

Returns the first error of the specified attribute.

getFirstErrors() public method

Returns the first error of every attribute in the model.

getIterator() public method

This method is required by the interface [[\IteratorAggregate]].

public getIterator ( ) : ArrayIterator
return	ArrayIterator	an iterator for traversing the items in the list.

getScenario() public method

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

public getScenario ( ) : string
return	string	the scenario that this model is in. Defaults to [[SCENARIO_DEFAULT]].

getValidators() public method

This method differs from Model::getActiveValidators in that the latter only returns the validators applicable to the current [[scenario]]. Because this method returns an ArrayObject object, you may manipulate it by inserting or removing validators (useful in model behaviors). For example, php $model->validators[] = $newValidator;

public getValidators ( ) : ArrayObjec\ArrayObject \| Validator[]
return	ArrayObjec\ArrayObject \| yii\validators\Validator[]	all the validators declared in the model.

hasErrors() public method

Returns a value indicating whether there is any validation error.

public hasErrors ( string \| null $attribute = null ) : boolean
$attribute	string \| null	attribute name. Use null to check all attributes.
return	boolean	whether there is any error.

isAttributeActive() public method

Returns a value indicating whether the attribute is active in the current scenario.

isAttributeRequired() public method

This is determined by checking if the attribute is associated with a [[\yii\validators\RequiredValidator|required]] validation rule in the current [[scenario]]. Note that when the validator has a conditional validation applied using [[\yii\validators\RequiredValidator::$when|$when]] this method will return false regardless of the when condition because it may be called be before the model is loaded with data.

public isAttributeRequired ( string $attribute ) : boolean
$attribute	string	attribute name
return	boolean	whether the attribute is required

isAttributeSafe() public method

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

load() public method

This method provides a convenient shortcut for: php if (isset($_POST['FormName'])) { $model->attributes = $_POST['FormName']; if ($model->save()) { handle success } } which, with load() can be written as: php if ($model->load($_POST) && $model->save()) { handle success } load() gets the 'FormName' from the model's Model::formName method (which you may override), unless the $formName parameter is given. If the form name is empty, load() populates the model with the whole of $data, instead of $data['FormName']. Note, that the data being populated is subject to the safety check by Model::setAttributes.

public load ( array $data, string $formName = null ) : boolean
$data	array	the data array to load, typically `$_POST` or `$_GET`.
$formName	string	the form name to use to load the data into the model. If not set, [[formName()]] is used.
return	boolean	whether `load()` found the expected form in `$data`.

loadMultiple() public static method

This method is mainly used to collect tabular data input. The data to be loaded for each model is $data[formName][index], where formName refers to the value of Model::formName, and index the index of the model in the $models array. If Model::formName is empty, $data[index] will be used to populate each model. The data being populated to each model is subject to the safety check by Model::setAttributes.

public static loadMultiple ( array $models, array $data, string $formName = null ) : boolean
$models	array	the models to be populated. Note that all models should have the same class.
$data	array	the data array. This is usually `$_POST` or `$_GET`, but can also be any valid array supplied by end user.
$formName	string	the form name to be used for loading the data into the models. If not set, it will use the [[formName()]] value of the first model in `$models`. This parameter is available since version 2.0.1.
return	boolean	whether at least one of the models is successfully populated.

offsetExists() public method

This method is required by the SPL interface [[\ArrayAccess]]. It is implicitly called when you use something like isset($model[$offset]).

public offsetExists ( mixed $offset ) : boolean
$offset	mixed	the offset to check on.
return	boolean	whether or not an offset exists.

offsetGet() public method

This method is required by the SPL interface [[\ArrayAccess]]. It is implicitly called when you use something like $value = $model[$offset];.

public offsetGet ( mixed $offset ) : mixed
$offset	mixed	the offset to retrieve element.
return	mixed	the element at the offset, null if no element is found at the offset

offsetSet() public method

This method is required by the SPL interface [[\ArrayAccess]]. It is implicitly called when you use something like $model[$offset] = $item;.

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

offsetUnset() public method

This method is required by the SPL interface [[\ArrayAccess]]. It is implicitly called when you use something like unset($model[$offset]).

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

onUnsafeAttribute() public method

The default implementation will log a warning message if YII_DEBUG is on. It does nothing otherwise.

public onUnsafeAttribute ( string $name, mixed $value )
$name	string	the unsafe attribute name
$value	mixed	the attribute value

rules() public method

Validation rules are used by Model::validate to check if attribute values are valid. Child classes may override this method to declare different validation rules. Each rule is an array with the following structure: php [ ['attribute1', 'attribute2'], 'validator type', 'on' => ['scenario1', 'scenario2'], ...other parameters... ] where - attribute list: required, specifies the attributes array to be validated, for single attribute you can pass a string; - validator type: required, specifies the validator to be used. It can be a built-in validator name, a method name of the model class, an anonymous function, or a validator class name. - on: optional, specifies the [[scenario|scenarios]] array in which the validation rule can be applied. If this option is not set, the rule will apply to all scenarios. - additional name-value pairs can be specified to initialize the corresponding validator properties. Please refer to individual validator class API for possible properties. A validator can be either an object of a class extending [[Validator]], or a model class method (called *inline validator*) that has the following signature: php $params refers to validation parameters given in the rule function validatorName($attribute, $params) In the above $attribute refers to the attribute currently being validated while $params contains an array of validator configuration options such as max in case of string validator. The value of the attribute currently being validated can be accessed as $this->$attribute. Note the $ before attribute; this is taking the value of the variable $attribute and using it as the name of the property to access. Yii also provides a set of [[Validator::builtInValidators|built-in validators]]. Each one has an alias name which can be used when specifying a validation rule. Below are some examples: php [ built-in "required" validator [['username', 'password'], 'required'], built-in "string" validator customized with "min" and "max" properties ['username', 'string', 'min' => 3, 'max' => 12], built-in "compare" validator that is used in "register" scenario only ['password', 'compare', 'compareAttribute' => 'password2', 'on' => 'register'], an inline validator defined via the "authenticate()" method in the model class ['password', 'authenticate', 'on' => 'login'], a validator of class "DateRangeValidator" ['dateRange', 'DateRangeValidator'], ]; 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 such as array_merge().

safeAttributes() public method

Returns the attribute names that are safe to be massively assigned in the current scenario.

public safeAttributes ( ) : string[]
return	string[]	safe attribute names

scenarios() public method

An active attribute is one that is subject to validation in the current scenario. The returned array should be in the following format: php [ 'scenario1' => ['attribute11', 'attribute12', ...], 'scenario2' => ['attribute21', 'attribute22', ...], ... ] By default, an active attribute is considered safe and can be massively assigned. If an attribute should NOT be massively assigned (thus considered unsafe), please prefix the attribute with an exclamation character (e.g. '!rank'). The default implementation of this method will return all scenarios found in the Model::rules declaration. A special scenario named [[SCENARIO_DEFAULT]] will contain all attributes found in the Model::rules. Each scenario will be associated with the attributes that are being validated by the validation rules that apply to the scenario.

public scenarios ( ) : array
return	array	a list of scenarios and the corresponding active attributes.

setAttributes() public method

Sets the attribute values in a massive way.

setScenario() public method

Note that this method does not check if the scenario exists or not. The method Model::validate will perform this check.

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

validate() public method

This method executes the validation rules applicable to the current [[scenario]]. The following criteria are used to determine whether a rule is currently applicable: - the rule must be associated with the attributes relevant to the current scenario; - the rules must be effective for the current scenario. This method will call Model::beforeValidate and Model::afterValidate before and after the actual validation, respectively. If Model::beforeValidate returns false, the validation will be cancelled and Model::afterValidate will not be called. Errors found during the validation can be retrieved via Model::getErrors, Model::getFirstErrors and Model::getFirstError.

public validate ( array $attributeNames = null, boolean $clearErrors = true ) : boolean
$attributeNames	array	list of attribute names that should be validated. If this parameter is empty, it means any attribute listed in the applicable validation rules should be validated.
$clearErrors	boolean	whether to call [[clearErrors()]] before performing validation
return	boolean	whether the validation is successful without any error.

validateMultiple() public static method

This method will validate every model. The models being validated may be of the same or different types.

public static validateMultiple ( array $models, array $attributeNames = null ) : boolean
$models	array	the models to be validated
$attributeNames	array	list of attribute names that should be validated. If this parameter is empty, it means any attribute listed in the applicable validation rules should be validated.
return	boolean	whether all models are valid. False will be returned if one or multiple models have validation error.

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

public fields ( ) : array
return	array	the list of field names or field definitions.

public formName ( ) : string
return	string	the form name of this model class.

public getAttributeHint ( string $attribute ) : string
$attribute	string	the attribute name
return	string	the attribute hint

public getAttributeLabel ( string $attribute ) : string
$attribute	string	the attribute name
return	string	the attribute label

public getErrors ( string $attribute = null ) : array
$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. Note that when returning errors for all attributes, the result is a two-dimensional array, like the following: ```php [ 'username' => [ 'Username is required.', 'Username must contain only word characters.', ], 'email' => [ 'Email address is invalid.', ] ] ```

public getFirstError ( string $attribute ) : string
$attribute	string	attribute name.
return	string	the error message. Null is returned if no error.

public getFirstErrors ( ) : array
return	array	the first errors. The array keys are the attribute names, and the array values are the corresponding error messages. An empty array will be returned if there is no error.

public isAttributeActive ( string $attribute ) : boolean
$attribute	string	attribute name
return	boolean	whether the attribute is active in the current scenario

public isAttributeSafe ( string $attribute ) : boolean
$attribute	string	attribute name
return	boolean	whether the attribute is safe for massive assignments

public setAttributes ( array $values, boolean $safeOnly = true )
$values	array	attribute values (name => value) to be assigned to the model.
$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]].