Class yii\base\Model
Inheritance | yii\base\Model » yii\base\Component » yii\base\BaseObject |
---|---|
Implements | ArrayAccess, IteratorAggregate, yii\base\Arrayable, yii\base\Configurable, yii\base\StaticInstanceInterface |
Uses Traits | yii\base\ArrayableTrait, yii\base\StaticInstanceTrait |
Subclasses | yii\base\DynamicModel, yii\data\ActiveDataFilter, yii\data\DataFilter, yii\db\ActiveRecord, yii\db\BaseActiveRecord |
Available since version | 2.0 |
Source Code | https://github.com/yiisoft/yii2/blob/master/framework/base/Model.php |
Model is the base class for data models.
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 validate()
- EVENT_AFTER_VALIDATE: an event raised at the end of 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.
Public Properties
Property | Type | Description | Defined By |
---|---|---|---|
$activeValidators | yii\validators\Validator[] | The validators applicable to the current $scenario. | yii\base\Model |
$attributes | array | Attribute values (name => value). | yii\base\Model |
$behaviors | yii\base\Behavior[] | List of behaviors attached to this component. | yii\base\Component |
$errors | array | Errors for all attributes or the specified attribute. | yii\base\Model |
$firstErrors | array | The first errors. | yii\base\Model |
$iterator | ArrayIterator | An iterator for traversing the items in the list. | yii\base\Model |
$scenario | string | The scenario that this model is in. | yii\base\Model |
$validators | ArrayObject|yii\validators\Validator[] | All the validators declared in the model. | yii\base\Model |
Public Methods
Method | Description | Defined By |
---|---|---|
__call() | Calls the named method which is not a class method. | yii\base\Component |
__clone() | This method is called after the object is created by cloning an existing one. | yii\base\Model |
__construct() | Constructor. | yii\base\BaseObject |
__get() | Returns the value of a component property. | yii\base\Component |
__isset() | Checks if a property is set, i.e. defined and not null. | yii\base\Component |
__set() | Sets the value of a component property. | yii\base\Component |
__unset() | Sets a component property to be null. | yii\base\Component |
activeAttributes() | Returns the attribute names that are subject to validation in the current scenario. | yii\base\Model |
addError() | Adds a new error to the specified attribute. | yii\base\Model |
addErrors() | Adds a list of errors. | yii\base\Model |
afterValidate() | This method is invoked after validation ends. | yii\base\Model |
attachBehavior() | Attaches a behavior to this component. | yii\base\Component |
attachBehaviors() | Attaches a list of behaviors to the component. | yii\base\Component |
attributeHints() | Returns the attribute hints. | yii\base\Model |
attributeLabels() | Returns the attribute labels. | yii\base\Model |
attributes() | Returns the list of attribute names. | yii\base\Model |
beforeValidate() | This method is invoked before validation starts. | yii\base\Model |
behaviors() | Returns a list of behaviors that this component should behave as. | yii\base\Component |
canGetProperty() | Returns a value indicating whether a property can be read. | yii\base\Component |
canSetProperty() | Returns a value indicating whether a property can be set. | yii\base\Component |
className() | Returns the fully qualified name of this class. | yii\base\BaseObject |
clearErrors() | Removes errors for all attributes or a single attribute. | yii\base\Model |
createValidators() | Creates validator objects based on the validation rules specified in rules(). | yii\base\Model |
detachBehavior() | Detaches a behavior from the component. | yii\base\Component |
detachBehaviors() | Detaches all behaviors from the component. | yii\base\Component |
ensureBehaviors() | Makes sure that the behaviors declared in behaviors() are attached to this component. | yii\base\Component |
extraFields() | Returns the list of fields that can be expanded further and returned by toArray(). | yii\base\ArrayableTrait |
fields() | Returns the list of fields that should be returned by default by toArray() when no specific fields are specified. | yii\base\Model |
formName() | Returns the form name that this model class should use. | yii\base\Model |
generateAttributeLabel() | Generates a user friendly attribute label based on the give attribute name. | yii\base\Model |
getActiveValidators() | Returns the validators applicable to the current $scenario. | yii\base\Model |
getAttributeHint() | Returns the text hint for the specified attribute. | yii\base\Model |
getAttributeLabel() | Returns the text label for the specified attribute. | yii\base\Model |
getAttributes() | Returns attribute values. | yii\base\Model |
getBehavior() | Returns the named behavior object. | yii\base\Component |
getBehaviors() | Returns all behaviors attached to this component. | yii\base\Component |
getErrorSummary() | Returns the errors for all attributes as a one-dimensional array. | yii\base\Model |
getErrors() | Returns the errors for all attributes or a single attribute. | yii\base\Model |
getFirstError() | Returns the first error of the specified attribute. | yii\base\Model |
getFirstErrors() | Returns the first error of every attribute in the model. | yii\base\Model |
getIterator() | Returns an iterator for traversing the attributes in the model. | yii\base\Model |
getScenario() | Returns the scenario that this model is used in. | yii\base\Model |
getValidators() | Returns all the validators declared in rules(). | yii\base\Model |
hasErrors() | Returns a value indicating whether there is any validation error. | yii\base\Model |
hasEventHandlers() | Returns a value indicating whether there is any handler attached to the named event. | yii\base\Component |
hasMethod() | Returns a value indicating whether a method is defined. | yii\base\Component |
hasProperty() | Returns a value indicating whether a property is defined for this component. | yii\base\Component |
init() | Initializes the object. | yii\base\BaseObject |
instance() | Returns static class instance, which can be used to obtain meta information. | yii\base\StaticInstanceTrait |
isAttributeActive() | Returns a value indicating whether the attribute is active in the current scenario. | yii\base\Model |
isAttributeRequired() | Returns a value indicating whether the attribute is required. | yii\base\Model |
isAttributeSafe() | Returns a value indicating whether the attribute is safe for massive assignments. | yii\base\Model |
load() | Populates the model with input data. | yii\base\Model |
loadMultiple() | Populates a set of models with the data from end user. | yii\base\Model |
off() | Detaches an existing event handler from this component. | yii\base\Component |
offsetExists() | Returns whether there is an element at the specified offset. | yii\base\Model |
offsetGet() | Returns the element at the specified offset. | yii\base\Model |
offsetSet() | Sets the element at the specified offset. | yii\base\Model |
offsetUnset() | Sets the element value at the specified offset to null. | yii\base\Model |
on() | Attaches an event handler to an event. | yii\base\Component |
onUnsafeAttribute() | This method is invoked when an unsafe attribute is being massively assigned. | yii\base\Model |
rules() | Returns the validation rules for attributes. | yii\base\Model |
safeAttributes() | Returns the attribute names that are safe to be massively assigned in the current scenario. | yii\base\Model |
scenarios() | Returns a list of scenarios and the corresponding active attributes. | yii\base\Model |
setAttributes() | Sets the attribute values in a massive way. | yii\base\Model |
setScenario() | Sets the scenario for the model. | yii\base\Model |
toArray() | Converts the model into an array. | yii\base\ArrayableTrait |
trigger() | Triggers an event. | yii\base\Component |
validate() | Performs the data validation. | yii\base\Model |
validateMultiple() | Validates multiple models. | yii\base\Model |
Protected Methods
Method | Description | Defined By |
---|---|---|
extractFieldsFor() | Extract nested fields from a fields collection for a given root field Nested fields are separated with dots (.). e.g: "item.id" The previous example would extract "id". | yii\base\ArrayableTrait |
extractRootFields() | Extracts the root field names from nested fields. | yii\base\ArrayableTrait |
resolveFields() | Determines which fields can be returned by toArray(). | yii\base\ArrayableTrait |
Events
Event | Type | Description | Defined By |
---|---|---|---|
EVENT_AFTER_VALIDATE | yii\base\Event | An event raised at the end of validate() | yii\base\Model |
EVENT_BEFORE_VALIDATE | yii\base\ModelEvent | An event raised at the beginning of validate(). | yii\base\Model |
Constants
Constant | Value | Description | Defined By |
---|---|---|---|
SCENARIO_DEFAULT | 'default' | The name of the default scenario. | yii\base\Model |
Property Details
The validators applicable to the current $scenario.
Errors for all attributes or the specified attribute. Empty array is returned
if no error. See getErrors() for detailed description. 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.', ] ] `
.
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.
An iterator for traversing the items in the list.
The scenario that this model is in. Defaults to SCENARIO_DEFAULT.
All the validators declared in the model.
Method Details
Defined in: yii\base\Component::__call()
Calls the named method which is not a class method.
This method will check if any attached behavior has the named method and will execute it if available.
Do not call this method directly as it is a PHP magic method that will be implicitly called when an unknown method is being invoked.
public mixed __call ( $name, $params ) | ||
$name | string |
The method name |
$params | array |
Method parameters |
return | mixed |
The method return value |
---|---|---|
throws | yii\base\UnknownMethodException |
when calling unknown method |
public function __call($name, $params)
{
$this->ensureBehaviors();
foreach ($this->_behaviors as $object) {
if ($object->hasMethod($name)) {
return call_user_func_array([$object, $name], $params);
}
}
throw new UnknownMethodException('Calling unknown method: ' . get_class($this) . "::$name()");
}
This method is called after the object is created by cloning an existing one.
It removes all behaviors because they are attached to the old object.
public void __clone ( ) |
public function __clone()
{
parent::__clone();
$this->_errors = null;
$this->_validators = null;
}
Defined in: yii\base\BaseObject::__construct()
Constructor.
The default implementation does two things:
- Initializes the object with the given configuration
$config
. - Call init().
If this method is overridden in a child class, it is recommended that
- the last parameter of the constructor is a configuration array, like
$config
here. - call the parent implementation at the end of the constructor.
public void __construct ( $config = [] ) | ||
$config | array |
Name-value pairs that will be used to initialize the object properties |
public function __construct($config = [])
{
if (!empty($config)) {
Yii::configure($this, $config);
}
$this->init();
}
Defined in: yii\base\Component::__get()
Returns the value of a component property.
This method will check in the following order and act accordingly:
- a property defined by a getter: return the getter result
- a property of a behavior: return the behavior property value
Do not call this method directly as it is a PHP magic method that
will be implicitly called when executing $value = $component->property;
.
See also __set().
public mixed __get ( $name ) | ||
$name | string |
The property name |
return | mixed |
The property value or the value of a behavior's property |
---|---|---|
throws | yii\base\UnknownPropertyException |
if the property is not defined |
throws | yii\base\InvalidCallException |
if the property is write-only. |
public function __get($name)
{
$getter = 'get' . $name;
if (method_exists($this, $getter)) {
// read property, e.g. getName()
return $this->$getter();
}
// behavior property
$this->ensureBehaviors();
foreach ($this->_behaviors as $behavior) {
if ($behavior->canGetProperty($name)) {
return $behavior->$name;
}
}
if (method_exists($this, 'set' . $name)) {
throw new InvalidCallException('Getting write-only property: ' . get_class($this) . '::' . $name);
}
throw new UnknownPropertyException('Getting unknown property: ' . get_class($this) . '::' . $name);
}
Defined in: yii\base\Component::__isset()
Checks if a property is set, i.e. defined and not null.
This method will check in the following order and act accordingly:
- a property defined by a setter: return whether the property is set
- a property of a behavior: return whether the property is set
- return
false
for non existing properties
Do not call this method directly as it is a PHP magic method that
will be implicitly called when executing isset($component->property)
.
public boolean __isset ( $name ) | ||
$name | string |
The property name or the event name |
return | boolean |
Whether the named property is set |
---|
public function __isset($name)
{
$getter = 'get' . $name;
if (method_exists($this, $getter)) {
return $this->$getter() !== null;
}
// behavior property
$this->ensureBehaviors();
foreach ($this->_behaviors as $behavior) {
if ($behavior->canGetProperty($name)) {
return $behavior->$name !== null;
}
}
return false;
}
Defined in: yii\base\Component::__set()
Sets the value of a component property.
This method will check in the following order and act accordingly:
- a property defined by a setter: set the property value
- an event in the format of "on xyz": attach the handler to the event "xyz"
- a behavior in the format of "as xyz": attach the behavior named as "xyz"
- a property of a behavior: set the behavior property value
Do not call this method directly as it is a PHP magic method that
will be implicitly called when executing $component->property = $value;
.
See also __get().
public void __set ( $name, $value ) | ||
$name | string |
The property name or the event name |
$value | mixed |
The property value |
throws | yii\base\UnknownPropertyException |
if the property is not defined |
---|---|---|
throws | yii\base\InvalidCallException |
if the property is read-only. |
public function __set($name, $value)
{
$setter = 'set' . $name;
if (method_exists($this, $setter)) {
// set property
$this->$setter($value);
return;
} elseif (strncmp($name, 'on ', 3) === 0) {
// on event: attach event handler
$this->on(trim(substr($name, 3)), $value);
return;
} elseif (strncmp($name, 'as ', 3) === 0) {
// as behavior: attach behavior
$name = trim(substr($name, 3));
$this->attachBehavior($name, $value instanceof Behavior ? $value : Yii::createObject($value));
return;
}
// behavior property
$this->ensureBehaviors();
foreach ($this->_behaviors as $behavior) {
if ($behavior->canSetProperty($name)) {
$behavior->$name = $value;
return;
}
}
if (method_exists($this, 'get' . $name)) {
throw new InvalidCallException('Setting read-only property: ' . get_class($this) . '::' . $name);
}
throw new UnknownPropertyException('Setting unknown property: ' . get_class($this) . '::' . $name);
}
Defined in: yii\base\Component::__unset()
Sets a component property to be null.
This method will check in the following order and act accordingly:
- a property defined by a setter: set the property value to be null
- a property of a behavior: set the property value to be null
Do not call this method directly as it is a PHP magic method that
will be implicitly called when executing unset($component->property)
.
public void __unset ( $name ) | ||
$name | string |
The property name |
throws | yii\base\InvalidCallException |
if the property is read only. |
---|
public function __unset($name)
{
$setter = 'set' . $name;
if (method_exists($this, $setter)) {
$this->$setter(null);
return;
}
// behavior property
$this->ensureBehaviors();
foreach ($this->_behaviors as $behavior) {
if ($behavior->canSetProperty($name)) {
$behavior->$name = null;
return;
}
}
throw new InvalidCallException('Unsetting an unknown or read-only property: ' . get_class($this) . '::' . $name);
}
Returns the attribute names that are subject to validation in the current scenario.
public string[] activeAttributes ( ) | ||
return | string[] |
Safe attribute names |
---|
public function activeAttributes()
{
$scenario = $this->getScenario();
$scenarios = $this->scenarios();
if (!isset($scenarios[$scenario])) {
return [];
}
$attributes = array_keys(array_flip($scenarios[$scenario]));
foreach ($attributes as $i => $attribute) {
if (strncmp($attribute, '!', 1) === 0) {
$attributes[$i] = substr($attribute, 1);
}
}
return $attributes;
}
Adds a new error to the specified attribute.
public void addError ( $attribute, $error = '' ) | ||
$attribute | string |
Attribute name |
$error | string |
New error message |
public function addError($attribute, $error = '')
{
$this->_errors[$attribute][] = $error;
}
Adds a list of errors.
public void 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. |
public function addErrors(array $items)
{
foreach ($items as $attribute => $errors) {
if (is_array($errors)) {
foreach ($errors as $error) {
$this->addError($attribute, $error);
}
} else {
$this->addError($attribute, $errors);
}
}
}
This method is invoked after validation ends.
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 void afterValidate ( ) |
public function afterValidate()
{
$this->trigger(self::EVENT_AFTER_VALIDATE);
}
Defined in: yii\base\Component::attachBehavior()
Attaches a behavior to this component.
This method will create the behavior object based on the given configuration. After that, the behavior object will be attached to this component by calling the yii\base\Behavior::attach() method.
See also detachBehavior().
public yii\base\Behavior attachBehavior ( $name, $behavior ) | ||
$name | string |
The name of the behavior. |
$behavior | string|array|yii\base\Behavior |
The behavior configuration. This can be one of the following:
|
return | yii\base\Behavior |
The behavior object |
---|
public function attachBehavior($name, $behavior)
{
$this->ensureBehaviors();
return $this->attachBehaviorInternal($name, $behavior);
}
Defined in: yii\base\Component::attachBehaviors()
Attaches a list of behaviors to the component.
Each behavior is indexed by its name and should be a yii\base\Behavior object, a string specifying the behavior class, or an configuration array for creating the behavior.
See also attachBehavior().
public void attachBehaviors ( $behaviors ) | ||
$behaviors | array |
List of behaviors to be attached to the component |
public function attachBehaviors($behaviors)
{
$this->ensureBehaviors();
foreach ($behaviors as $name => $behavior) {
$this->attachBehaviorInternal($name, $behavior);
}
}
Returns the attribute hints.
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()
.
public array attributeHints ( ) | ||
return | array |
Attribute hints (name => hint) |
---|
public function attributeHints()
{
return [];
}
Returns the attribute labels.
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 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()
.
See also generateAttributeLabel().
public array attributeLabels ( ) | ||
return | array |
Attribute labels (name => label) |
---|
public function attributeLabels()
{
return [];
}
Returns the list of attribute names.
By default, this method returns all public non-static properties of the class. You may override this method to change the default behavior.
public string[] attributes ( ) | ||
return | string[] |
List of attribute names. |
---|
public function attributes()
{
$class = new ReflectionClass($this);
$names = [];
foreach ($class->getProperties(\ReflectionProperty::IS_PUBLIC) as $property) {
if (!$property->isStatic()) {
$names[] = $property->getName();
}
}
return $names;
}
This method is invoked before validation starts.
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 boolean beforeValidate ( ) | ||
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. |
---|
public function beforeValidate()
{
$event = new ModelEvent();
$this->trigger(self::EVENT_BEFORE_VALIDATE, $event);
return $event->isValid;
}
Defined in: yii\base\Component::behaviors()
Returns a list of behaviors that this component should behave as.
Child classes may override this method to specify the behaviors they want to behave as.
The return value of this method should be an array of behavior objects or configurations indexed by behavior names. A behavior configuration can be either a string specifying the behavior class or an array of the following structure:
'behaviorName' => [
'class' => 'BehaviorClass',
'property1' => 'value1',
'property2' => 'value2',
]
Note that a behavior class must extend from yii\base\Behavior. Behaviors can be attached using a name or anonymously. When a name is used as the array key, using this name, the behavior can later be retrieved using getBehavior() or be detached using detachBehavior(). Anonymous behaviors can not be retrieved or detached.
Behaviors declared in this method will be attached to the component automatically (on demand).
public array behaviors ( ) | ||
return | array |
The behavior configurations. |
---|
public function behaviors()
{
return [];
}
Defined in: yii\base\Component::canGetProperty()
Returns a value indicating whether a property can be read.
A property can be read if:
- the class has a getter method associated with the specified name (in this case, property name is case-insensitive);
- the class has a member variable with the specified name (when
$checkVars
is true); - an attached behavior has a readable property of the given name (when
$checkBehaviors
is true).
See also canSetProperty().
public boolean canGetProperty ( $name, $checkVars = true, $checkBehaviors = true ) | ||
$name | string |
The property name |
$checkVars | boolean |
Whether to treat member variables as properties |
$checkBehaviors | boolean |
Whether to treat behaviors' properties as properties of this component |
return | boolean |
Whether the property can be read |
---|
public function canGetProperty($name, $checkVars = true, $checkBehaviors = true)
{
if (method_exists($this, 'get' . $name) || $checkVars && property_exists($this, $name)) {
return true;
} elseif ($checkBehaviors) {
$this->ensureBehaviors();
foreach ($this->_behaviors as $behavior) {
if ($behavior->canGetProperty($name, $checkVars)) {
return true;
}
}
}
return false;
}
Defined in: yii\base\Component::canSetProperty()
Returns a value indicating whether a property can be set.
A property can be written if:
- the class has a setter method associated with the specified name (in this case, property name is case-insensitive);
- the class has a member variable with the specified name (when
$checkVars
is true); - an attached behavior has a writable property of the given name (when
$checkBehaviors
is true).
See also canGetProperty().
public boolean canSetProperty ( $name, $checkVars = true, $checkBehaviors = true ) | ||
$name | string |
The property name |
$checkVars | boolean |
Whether to treat member variables as properties |
$checkBehaviors | boolean |
Whether to treat behaviors' properties as properties of this component |
return | boolean |
Whether the property can be written |
---|
public function canSetProperty($name, $checkVars = true, $checkBehaviors = true)
{
if (method_exists($this, 'set' . $name) || $checkVars && property_exists($this, $name)) {
return true;
} elseif ($checkBehaviors) {
$this->ensureBehaviors();
foreach ($this->_behaviors as $behavior) {
if ($behavior->canSetProperty($name, $checkVars)) {
return true;
}
}
}
return false;
}
::class
instead.
Defined in: yii\base\BaseObject::className()
Returns the fully qualified name of this class.
public static string className ( ) | ||
return | string |
The fully qualified name of this class. |
---|
public static function className()
{
return get_called_class();
}
Removes errors for all attributes or a single attribute.
public void clearErrors ( $attribute = null ) | ||
$attribute | string|null |
Attribute name. Use null to remove errors for all attributes. |
public function clearErrors($attribute = null)
{
if ($attribute === null) {
$this->_errors = [];
} else {
unset($this->_errors[$attribute]);
}
}
Creates validator objects based on the validation rules specified in rules().
Unlike getValidators(), each time this method is called, a new list of validators will be returned.
public ArrayObject createValidators ( ) | ||
return | ArrayObject |
Validators |
---|---|---|
throws | yii\base\InvalidConfigException |
if any validation rule configuration is invalid |
public function createValidators()
{
$validators = new ArrayObject();
foreach ($this->rules() as $rule) {
if ($rule instanceof Validator) {
$validators->append($rule);
} elseif (is_array($rule) && isset($rule[0], $rule[1])) { // attributes, validator type
$validator = Validator::createValidator($rule[1], $this, (array) $rule[0], array_slice($rule, 2));
$validators->append($validator);
} else {
throw new InvalidConfigException('Invalid validation rule: a rule must specify both attribute names and validator type.');
}
}
return $validators;
}
Defined in: yii\base\Component::detachBehavior()
Detaches a behavior from the component.
The behavior's yii\base\Behavior::detach() method will be invoked.
public yii\base\Behavior|null detachBehavior ( $name ) | ||
$name | string |
The behavior's name. |
return | yii\base\Behavior|null |
The detached behavior. Null if the behavior does not exist. |
---|
public function detachBehavior($name)
{
$this->ensureBehaviors();
if (isset($this->_behaviors[$name])) {
$behavior = $this->_behaviors[$name];
unset($this->_behaviors[$name]);
$behavior->detach();
return $behavior;
}
return null;
}
Defined in: yii\base\Component::detachBehaviors()
Detaches all behaviors from the component.
public void detachBehaviors ( ) |
public function detachBehaviors()
{
$this->ensureBehaviors();
foreach ($this->_behaviors as $name => $behavior) {
$this->detachBehavior($name);
}
}
Defined in: yii\base\Component::ensureBehaviors()
Makes sure that the behaviors declared in behaviors() are attached to this component.
public void ensureBehaviors ( ) |
public function ensureBehaviors()
{
if ($this->_behaviors === null) {
$this->_behaviors = [];
foreach ($this->behaviors() as $name => $behavior) {
$this->attachBehaviorInternal($name, $behavior);
}
}
}
Defined in: yii\base\ArrayableTrait::extraFields()
Returns the list of fields that can be expanded further and returned by toArray().
This method is similar to fields() except that the list of fields returned by this method are not returned by default by toArray(). Only when field names to be expanded are explicitly specified when calling toArray(), will their values be exported.
The default implementation returns an empty array.
You may override this method to return a list of expandable fields based on some context information (e.g. the current application user).
See also:
public array extraFields ( ) | ||
return | array |
The list of expandable field names or field definitions. Please refer to fields() on the format of the return value. |
---|
public function extraFields()
{
return [];
}
Defined in: yii\base\ArrayableTrait::extractFieldsFor()
Extract nested fields from a fields collection for a given root field Nested fields are separated with dots (.). e.g: "item.id" The previous example would extract "id".
protected array extractFieldsFor ( array $fields, $rootField ) | ||
$fields | array |
The fields requested for extraction |
$rootField | string |
The root field for which we want to extract the nested fields |
return | array |
Nested fields extracted for the given field |
---|
protected function extractFieldsFor(array $fields, $rootField)
{
$result = [];
foreach ($fields as $field) {
if (0 === strpos($field, "{$rootField}.")) {
$result[] = preg_replace('/^' . preg_quote($rootField, '/') . '\./i', '', $field);
}
}
return array_unique($result);
}
Defined in: yii\base\ArrayableTrait::extractRootFields()
Extracts the root field names from nested fields.
Nested fields are separated with dots (.). e.g: "item.id" The previous example would extract "item".
protected array extractRootFields ( array $fields ) | ||
$fields | array |
The fields requested for extraction |
return | array |
Root fields extracted from the given nested fields |
---|
protected function extractRootFields(array $fields)
{
$result = [];
foreach ($fields as $field) {
$result[] = current(explode('.', $field, 2));
}
if (in_array('*', $result, true)) {
$result = [];
}
return array_unique($result);
}
Returns the list of fields that should be returned by default by toArray() when no specific fields are specified.
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:
function ($model, $field) {
// return field value
}
For example, the following code declares four fields:
email
: the field name is the same as the property nameemail
;firstName
andlastName
: the field names arefirstName
andlastName
, and their values are obtained from thefirst_name
andlast_name
properties;fullName
: the field name isfullName
. Its value is obtained by concatenatingfirst_name
andlast_name
.
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 attributes() indexed by the same attribute names.
See also toArray().
public array fields ( ) | ||
return | array |
The list of field names or field definitions. |
---|
public function fields()
{
$fields = $this->attributes();
return array_combine($fields, $fields);
}
Returns the form name that this model class should use.
The form name is mainly used by yii\widgets\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.
See also load().
public string formName ( ) | ||
return | string |
The form name of this model class. |
---|---|---|
throws | yii\base\InvalidConfigException |
when form is defined with anonymous class and |
public function formName()
{
$reflector = new ReflectionClass($this);
if (PHP_VERSION_ID >= 70000 && $reflector->isAnonymous()) {
throw new InvalidConfigException('The "formName()" method should be explicitly defined for anonymous models');
}
return $reflector->getShortName();
}
Generates a user friendly attribute label based on the give attribute name.
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 string generateAttributeLabel ( $name ) | ||
$name | string |
The column name |
return | string |
The attribute label |
---|
public function generateAttributeLabel($name)
{
return Inflector::camel2words($name, true);
}
Returns the validators applicable to the current $scenario.
public yii\validators\Validator[] getActiveValidators ( $attribute = null ) | ||
$attribute | string|null |
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. |
---|
public function getActiveValidators($attribute = null)
{
$activeAttributes = $this->activeAttributes();
if ($attribute !== null && !in_array($attribute, $activeAttributes, true)) {
return [];
}
$scenario = $this->getScenario();
$validators = [];
foreach ($this->getValidators() as $validator) {
if ($attribute === null) {
$validatorAttributes = $validator->getValidationAttributes($activeAttributes);
$attributeValid = !empty($validatorAttributes);
} else {
$attributeValid = in_array($attribute, $validator->getValidationAttributes($attribute), true);
}
if ($attributeValid && $validator->isActive($scenario)) {
$validators[] = $validator;
}
}
return $validators;
}
Returns the text hint for the specified attribute.
See also attributeHints().
public string getAttributeHint ( $attribute ) | ||
$attribute | string |
The attribute name |
return | string |
The attribute hint |
---|
public function getAttributeHint($attribute)
{
$hints = $this->attributeHints();
return isset($hints[$attribute]) ? $hints[$attribute] : '';
}
Returns the text label for the specified attribute.
See also:
public string getAttributeLabel ( $attribute ) | ||
$attribute | string |
The attribute name |
return | string |
The attribute label |
---|
public function getAttributeLabel($attribute)
{
$labels = $this->attributeLabels();
return isset($labels[$attribute]) ? $labels[$attribute] : $this->generateAttributeLabel($attribute);
}
Returns attribute values.
public array getAttributes ( $names = null, $except = [] ) | ||
$names | array|null |
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). |
---|
public function getAttributes($names = null, $except = [])
{
$values = [];
if ($names === null) {
$names = $this->attributes();
}
foreach ($names as $name) {
$values[$name] = $this->$name;
}
foreach ($except as $name) {
unset($values[$name]);
}
return $values;
}
Defined in: yii\base\Component::getBehavior()
Returns the named behavior object.
public yii\base\Behavior|null getBehavior ( $name ) | ||
$name | string |
The behavior name |
return | yii\base\Behavior|null |
The behavior object, or null if the behavior does not exist |
---|
public function getBehavior($name)
{
$this->ensureBehaviors();
return isset($this->_behaviors[$name]) ? $this->_behaviors[$name] : null;
}
Defined in: yii\base\Component::getBehaviors()
Returns all behaviors attached to this component.
public yii\base\Behavior[] getBehaviors ( ) | ||
return | yii\base\Behavior[] |
List of behaviors attached to this component |
---|
public function getBehaviors()
{
$this->ensureBehaviors();
return $this->_behaviors;
}
Returns the errors for all attributes as a one-dimensional array.
See also:
public array getErrorSummary ( $showAllErrors ) | ||
$showAllErrors | boolean |
Boolean, if set to true every error message for each attribute will be shown otherwise only the first error message for each attribute will be shown. |
return | array |
Errors for all attributes as a one-dimensional array. Empty array is returned if no error. |
---|
public function getErrorSummary($showAllErrors)
{
$lines = [];
$errors = $showAllErrors ? $this->getErrors() : $this->getFirstErrors();
foreach ($errors as $es) {
$lines = array_merge($lines, (array)$es);
}
return $lines;
}
Returns the errors for all attributes or a single attribute.
See also:
public array getErrors ( $attribute = null ) | ||
$attribute | string|null |
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. See getErrors() for detailed description. Note that when returning errors for all attributes, the result is a two-dimensional array, like the following:
|
---|
public function getErrors($attribute = null)
{
if ($attribute === null) {
return $this->_errors === null ? [] : $this->_errors;
}
return isset($this->_errors[$attribute]) ? $this->_errors[$attribute] : [];
}
public string|null getFirstError ( $attribute ) | ||
$attribute | string |
Attribute name. |
return | string|null |
The error message. Null is returned if no error. |
---|
public function getFirstError($attribute)
{
return isset($this->_errors[$attribute]) ? reset($this->_errors[$attribute]) : null;
}
public array getFirstErrors ( ) | ||
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 function getFirstErrors()
{
if (empty($this->_errors)) {
return [];
}
$errors = [];
foreach ($this->_errors as $name => $es) {
if (!empty($es)) {
$errors[$name] = reset($es);
}
}
return $errors;
}
Returns an iterator for traversing the attributes in the model.
This method is required by the interface IteratorAggregate.
public ArrayIterator getIterator ( ) | ||
return | ArrayIterator |
An iterator for traversing the items in the list. |
---|
#[\ReturnTypeWillChange]
public function getIterator()
{
$attributes = $this->getAttributes();
return new ArrayIterator($attributes);
}
Returns the scenario that this model is used in.
Scenario affects how validation is performed and which attributes can be massively assigned.
public string getScenario ( ) | ||
return | string |
The scenario that this model is in. Defaults to SCENARIO_DEFAULT. |
---|
public function getScenario()
{
return $this->_scenario;
}
Returns all the validators declared in rules().
This method differs from 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,
$model->validators[] = $newValidator;
public ArrayObject|yii\validators\Validator[] getValidators ( ) | ||
return | ArrayObject|yii\validators\Validator[] |
All the validators declared in the model. |
---|
public function getValidators()
{
if ($this->_validators === null) {
$this->_validators = $this->createValidators();
}
return $this->_validators;
}
Returns a value indicating whether there is any validation error.
public boolean hasErrors ( $attribute = null ) | ||
$attribute | string|null |
Attribute name. Use null to check all attributes. |
return | boolean |
Whether there is any error. |
---|
public function hasErrors($attribute = null)
{
return $attribute === null ? !empty($this->_errors) : isset($this->_errors[$attribute]);
}
Defined in: yii\base\Component::hasEventHandlers()
Returns a value indicating whether there is any handler attached to the named event.
public boolean hasEventHandlers ( $name ) | ||
$name | string |
The event name |
return | boolean |
Whether there is any handler attached to the event. |
---|
public function hasEventHandlers($name)
{
$this->ensureBehaviors();
if (!empty($this->_events[$name])) {
return true;
}
foreach ($this->_eventWildcards as $wildcard => $handlers) {
if (!empty($handlers) && StringHelper::matchWildcard($wildcard, $name)) {
return true;
}
}
return Event::hasHandlers($this, $name);
}
Defined in: yii\base\Component::hasMethod()
Returns a value indicating whether a method is defined.
A method is defined if:
- the class has a method with the specified name
- an attached behavior has a method with the given name (when
$checkBehaviors
is true).
public boolean hasMethod ( $name, $checkBehaviors = true ) | ||
$name | string |
The property name |
$checkBehaviors | boolean |
Whether to treat behaviors' methods as methods of this component |
return | boolean |
Whether the method is defined |
---|
public function hasMethod($name, $checkBehaviors = true)
{
if (method_exists($this, $name)) {
return true;
} elseif ($checkBehaviors) {
$this->ensureBehaviors();
foreach ($this->_behaviors as $behavior) {
if ($behavior->hasMethod($name)) {
return true;
}
}
}
return false;
}
Defined in: yii\base\Component::hasProperty()
Returns a value indicating whether a property is defined for this component.
A property is defined if:
- the class has a getter or setter method associated with the specified name (in this case, property name is case-insensitive);
- the class has a member variable with the specified name (when
$checkVars
is true); - an attached behavior has a property of the given name (when
$checkBehaviors
is true).
See also:
public boolean hasProperty ( $name, $checkVars = true, $checkBehaviors = true ) | ||
$name | string |
The property name |
$checkVars | boolean |
Whether to treat member variables as properties |
$checkBehaviors | boolean |
Whether to treat behaviors' properties as properties of this component |
return | boolean |
Whether the property is defined |
---|
public function hasProperty($name, $checkVars = true, $checkBehaviors = true)
{
return $this->canGetProperty($name, $checkVars, $checkBehaviors) || $this->canSetProperty($name, false, $checkBehaviors);
}
Defined in: yii\base\BaseObject::init()
Initializes the object.
This method is invoked at the end of the constructor after the object is initialized with the given configuration.
public void init ( ) |
public function init()
{
}
Defined in: yii\base\StaticInstanceTrait::instance()
Returns static class instance, which can be used to obtain meta information.
public static static instance ( $refresh = false ) | ||
$refresh | boolean |
Whether to re-create static instance even, if it is already cached. |
return | yii\base\Model |
Class instance. |
---|
public static function instance($refresh = false)
{
$className = get_called_class();
if ($refresh || !isset(self::$_instances[$className])) {
self::$_instances[$className] = Yii::createObject($className);
}
return self::$_instances[$className];
}
Returns a value indicating whether the attribute is active in the current scenario.
See also activeAttributes().
public boolean isAttributeActive ( $attribute ) | ||
$attribute | string |
Attribute name |
return | boolean |
Whether the attribute is active in the current scenario |
---|
public function isAttributeActive($attribute)
{
return in_array($attribute, $this->activeAttributes(), true);
}
Returns a value indicating whether the attribute is required.
This is determined by checking if the attribute is associated with a required validation rule in the current $scenario.
Note that when the validator has a conditional validation applied using
$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 boolean isAttributeRequired ( $attribute ) | ||
$attribute | string |
Attribute name |
return | boolean |
Whether the attribute is required |
---|
public function isAttributeRequired($attribute)
{
foreach ($this->getActiveValidators($attribute) as $validator) {
if ($validator instanceof RequiredValidator && $validator->when === null) {
return true;
}
}
return false;
}
Returns a value indicating whether the attribute is safe for massive assignments.
See also safeAttributes().
public boolean isAttributeSafe ( $attribute ) | ||
$attribute | string |
Attribute name |
return | boolean |
Whether the attribute is safe for massive assignments |
---|
public function isAttributeSafe($attribute)
{
return in_array($attribute, $this->safeAttributes(), true);
}
Populates the model with input data.
This method provides a convenient shortcut for:
if (isset($_POST['FormName'])) {
$model->attributes = $_POST['FormName'];
if ($model->save()) {
// handle success
}
}
which, with load()
can be written as:
if ($model->load($_POST) && $model->save()) {
// handle success
}
load()
gets the 'FormName'
from the model's 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 setAttributes().
public boolean load ( $data, $formName = null ) | ||
$data | array |
The data array to load, typically |
$formName | string|null |
The form name to use to load the data into the model, empty string when form not use. If not set, formName() is used. |
return | boolean |
Whether |
---|
public function load($data, $formName = null)
{
$scope = $formName === null ? $this->formName() : $formName;
if ($scope === '' && !empty($data)) {
$this->setAttributes($data);
return true;
} elseif (isset($data[$scope])) {
$this->setAttributes($data[$scope]);
return true;
}
return false;
}
Populates a set of models with the data from end user.
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 formName(), and index
the index of the model in the $models
array.
If 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 setAttributes().
public static boolean loadMultiple ( $models, $data, $formName = null ) | ||
$models | array |
The models to be populated. Note that all models should have the same class. |
$data | array |
The data array. This is usually |
$formName | string|null |
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 |
return | boolean |
Whether at least one of the models is successfully populated. |
---|
public static function loadMultiple($models, $data, $formName = null)
{
if ($formName === null) {
/* @var $first Model|false */
$first = reset($models);
if ($first === false) {
return false;
}
$formName = $first->formName();
}
$success = false;
foreach ($models as $i => $model) {
/* @var $model Model */
if ($formName == '') {
if (!empty($data[$i]) && $model->load($data[$i], '')) {
$success = true;
}
} elseif (!empty($data[$formName][$i]) && $model->load($data[$formName][$i], '')) {
$success = true;
}
}
return $success;
}
Defined in: yii\base\Component::off()
Detaches an existing event handler from this component.
This method is the opposite of on().
Note: in case wildcard pattern is passed for event name, only the handlers registered with this wildcard will be removed, while handlers registered with plain names matching this wildcard will remain.
See also on().
public boolean off ( $name, $handler = null ) | ||
$name | string |
Event name |
$handler | callable|null |
The event handler to be removed. If it is null, all handlers attached to the named event will be removed. |
return | boolean |
If a handler is found and detached |
---|
public function off($name, $handler = null)
{
$this->ensureBehaviors();
if (empty($this->_events[$name]) && empty($this->_eventWildcards[$name])) {
return false;
}
if ($handler === null) {
unset($this->_events[$name], $this->_eventWildcards[$name]);
return true;
}
$removed = false;
// plain event names
if (isset($this->_events[$name])) {
foreach ($this->_events[$name] as $i => $event) {
if ($event[0] === $handler) {
unset($this->_events[$name][$i]);
$removed = true;
}
}
if ($removed) {
$this->_events[$name] = array_values($this->_events[$name]);
return true;
}
}
// wildcard event names
if (isset($this->_eventWildcards[$name])) {
foreach ($this->_eventWildcards[$name] as $i => $event) {
if ($event[0] === $handler) {
unset($this->_eventWildcards[$name][$i]);
$removed = true;
}
}
if ($removed) {
$this->_eventWildcards[$name] = array_values($this->_eventWildcards[$name]);
// remove empty wildcards to save future redundant regex checks:
if (empty($this->_eventWildcards[$name])) {
unset($this->_eventWildcards[$name]);
}
}
}
return $removed;
}
Returns whether there is an element at the specified offset.
This method is required by the SPL interface ArrayAccess.
It is implicitly called when you use something like isset($model[$offset])
.
public boolean offsetExists ( $offset ) | ||
$offset | string |
The offset to check on. |
return | boolean |
Whether or not an offset exists. |
---|
#[\ReturnTypeWillChange]
public function offsetExists($offset)
{
return isset($this->$offset);
}
Returns the element at the specified offset.
This method is required by the SPL interface ArrayAccess.
It is implicitly called when you use something like $value = $model[$offset];
.
public mixed offsetGet ( $offset ) | ||
$offset | string |
The offset to retrieve element. |
return | mixed |
The element at the offset, null if no element is found at the offset |
---|
#[\ReturnTypeWillChange]
public function offsetGet($offset)
{
return $this->$offset;
}
Sets the element at the specified offset.
This method is required by the SPL interface ArrayAccess.
It is implicitly called when you use something like $model[$offset] = $value;
.
public void offsetSet ( $offset, $value ) | ||
$offset | string |
The offset to set element |
$value | mixed |
The element value |
#[\ReturnTypeWillChange]
public function offsetSet($offset, $value)
{
$this->$offset = $value;
}
Sets the element value at the specified offset to null.
This method is required by the SPL interface ArrayAccess.
It is implicitly called when you use something like unset($model[$offset])
.
public void offsetUnset ( $offset ) | ||
$offset | string |
The offset to unset element |
#[\ReturnTypeWillChange]
public function offsetUnset($offset)
{
$this->$offset = null;
}
Defined in: yii\base\Component::on()
Attaches an event handler to an event.
The event handler must be a valid PHP callback. The following are some examples:
function ($event) { ... } // anonymous function
[$object, 'handleClick'] // $object->handleClick()
['Page', 'handleClick'] // Page::handleClick()
'handleClick' // global function handleClick()
The event handler must be defined with the following signature,
function ($event)
where $event
is an yii\base\Event object which includes parameters associated with the event.
Since 2.0.14 you can specify event name as a wildcard pattern:
$component->on('event.group.*', function ($event) {
Yii::trace($event->name . ' is triggered.');
});
See also off().
public void on ( $name, $handler, $data = null, $append = true ) | ||
$name | string |
The event name |
$handler | callable |
The event handler |
$data | mixed |
The data to be passed to the event handler when the event is triggered. When the event handler is invoked, this data can be accessed via yii\base\Event::$data. |
$append | boolean |
Whether to append new event handler to the end of the existing handler list. If false, the new handler will be inserted at the beginning of the existing handler list. |
public function on($name, $handler, $data = null, $append = true)
{
$this->ensureBehaviors();
if (strpos($name, '*') !== false) {
if ($append || empty($this->_eventWildcards[$name])) {
$this->_eventWildcards[$name][] = [$handler, $data];
} else {
array_unshift($this->_eventWildcards[$name], [$handler, $data]);
}
return;
}
if ($append || empty($this->_events[$name])) {
$this->_events[$name][] = [$handler, $data];
} else {
array_unshift($this->_events[$name], [$handler, $data]);
}
}
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.
public void onUnsafeAttribute ( $name, $value ) | ||
$name | string |
The unsafe attribute name |
$value | mixed |
The attribute value |
public function onUnsafeAttribute($name, $value)
{
if (YII_DEBUG) {
Yii::debug("Failed to set unsafe attribute '$name' in '" . get_class($this) . "'.", __METHOD__);
}
}
Defined in: yii\base\ArrayableTrait::resolveFields()
Determines which fields can be returned by toArray().
This method will first extract the root fields from the given fields. Then it will check the requested root fields against those declared in fields() and extraFields() to determine which fields can be returned.
protected array resolveFields ( array $fields, array $expand ) | ||
$fields | array |
The fields being requested for exporting |
$expand | array |
The additional fields being requested for exporting |
return | array |
The list of fields to be exported. The array keys are the field names, and the array values are the corresponding object property names or PHP callables returning the field values. |
---|
protected function resolveFields(array $fields, array $expand)
{
$fields = $this->extractRootFields($fields);
$expand = $this->extractRootFields($expand);
$result = [];
foreach ($this->fields() as $field => $definition) {
if (is_int($field)) {
$field = $definition;
}
if (empty($fields) || in_array($field, $fields, true)) {
$result[$field] = $definition;
}
}
if (empty($expand)) {
return $result;
}
foreach ($this->extraFields() as $field => $definition) {
if (is_int($field)) {
$field = $definition;
}
if (in_array($field, $expand, true)) {
$result[$field] = $definition;
}
}
return $result;
}
Returns the validation rules for attributes.
Validation rules are used by 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:
[
['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 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 yii\validators\Validator, or a model class method (called inline validator) that has the following signature:
// $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 built-in validators. Each one has an alias name which can be used when specifying a validation rule.
Below are some examples:
[
// 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()
.
See also scenarios().
public array rules ( ) | ||
return | array |
Validation rules |
---|
public function rules()
{
return [];
}
Returns the attribute names that are safe to be massively assigned in the current scenario.
public string[] safeAttributes ( ) | ||
return | string[] |
Safe attribute names |
---|
public function safeAttributes()
{
$scenario = $this->getScenario();
$scenarios = $this->scenarios();
if (!isset($scenarios[$scenario])) {
return [];
}
$attributes = [];
foreach ($scenarios[$scenario] as $attribute) {
if (
$attribute !== ''
&& strncmp($attribute, '!', 1) !== 0
&& !in_array('!' . $attribute, $scenarios[$scenario])
) {
$attributes[] = $attribute;
}
}
return $attributes;
}
Returns a list of scenarios and the corresponding active attributes.
An active attribute is one that is subject to validation in the current scenario. The returned array should be in the following format:
[
'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 rules() declaration. A special scenario named SCENARIO_DEFAULT will contain all attributes found in the rules(). Each scenario will be associated with the attributes that are being validated by the validation rules that apply to the scenario.
public array scenarios ( ) | ||
return | array |
A list of scenarios and the corresponding active attributes. |
---|
public function scenarios()
{
$scenarios = [self::SCENARIO_DEFAULT => []];
foreach ($this->getValidators() as $validator) {
foreach ($validator->on as $scenario) {
$scenarios[$scenario] = [];
}
foreach ($validator->except as $scenario) {
$scenarios[$scenario] = [];
}
}
$names = array_keys($scenarios);
foreach ($this->getValidators() as $validator) {
if (empty($validator->on) && empty($validator->except)) {
foreach ($names as $name) {
foreach ($validator->attributes as $attribute) {
$scenarios[$name][$attribute] = true;
}
}
} elseif (empty($validator->on)) {
foreach ($names as $name) {
if (!in_array($name, $validator->except, true)) {
foreach ($validator->attributes as $attribute) {
$scenarios[$name][$attribute] = true;
}
}
}
} else {
foreach ($validator->on as $name) {
foreach ($validator->attributes as $attribute) {
$scenarios[$name][$attribute] = true;
}
}
}
}
foreach ($scenarios as $scenario => $attributes) {
if (!empty($attributes)) {
$scenarios[$scenario] = array_keys($attributes);
}
}
return $scenarios;
}
public void setAttributes ( $values, $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. |
public function setAttributes($values, $safeOnly = true)
{
if (is_array($values)) {
$attributes = array_flip($safeOnly ? $this->safeAttributes() : $this->attributes());
foreach ($values as $name => $value) {
if (isset($attributes[$name])) {
$this->$name = $value;
} elseif ($safeOnly) {
$this->onUnsafeAttribute($name, $value);
}
}
}
}
Sets the scenario for the model.
Note that this method does not check if the scenario exists or not. The method validate() will perform this check.
public void setScenario ( $value ) | ||
$value | string |
The scenario that this model is in. |
public function setScenario($value)
{
$this->_scenario = $value;
}
Defined in: yii\base\ArrayableTrait::toArray()
Converts the model into an array.
This method will first identify which fields to be included in the resulting array by calling resolveFields().
It will then turn the model into an array with these fields. If $recursive
is true,
any embedded objects will also be converted into arrays.
When embedded objects are yii\base\Arrayable, their respective nested fields will be extracted and passed to toArray().
If the model implements the yii\web\Linkable interface, the resulting array will also have a _link
element
which refers to a list of links as specified by the interface.
public array toArray ( array $fields = [], array $expand = [], $recursive = true ) | ||
$fields | array |
The fields being requested.
If empty or if it contains '*', all fields as specified by fields() will be returned.
Fields can be nested, separated with dots (.). e.g.: item.field.sub-field
|
$expand | array |
The additional fields being requested for exporting. Only fields declared in extraFields()
will be considered.
Expand can also be nested, separated with dots (.). e.g.: item.expand1.expand2
|
$recursive | boolean |
Whether to recursively return array representation of embedded objects. |
return | array |
The array representation of the object |
---|
public function toArray(array $fields = [], array $expand = [], $recursive = true)
{
$data = [];
foreach ($this->resolveFields($fields, $expand) as $field => $definition) {
$attribute = is_string($definition) ? $this->$definition : $definition($this, $field);
if ($recursive) {
$nestedFields = $this->extractFieldsFor($fields, $field);
$nestedExpand = $this->extractFieldsFor($expand, $field);
if ($attribute instanceof Arrayable) {
$attribute = $attribute->toArray($nestedFields, $nestedExpand);
} elseif ($attribute instanceof \JsonSerializable) {
$attribute = $attribute->jsonSerialize();
} elseif (is_array($attribute)) {
$attribute = array_map(
function ($item) use ($nestedFields, $nestedExpand) {
if ($item instanceof Arrayable) {
return $item->toArray($nestedFields, $nestedExpand);
} elseif ($item instanceof \JsonSerializable) {
return $item->jsonSerialize();
}
return $item;
},
$attribute
);
}
}
$data[$field] = $attribute;
}
if ($this instanceof Linkable) {
$data['_links'] = Link::serialize($this->getLinks());
}
return $recursive ? ArrayHelper::toArray($data) : $data;
}
Defined in: yii\base\Component::trigger()
Triggers an event.
This method represents the happening of an event. It invokes all attached handlers for the event including class-level handlers.
public void trigger ( $name, yii\base\Event $event = null ) | ||
$name | string |
The event name |
$event | yii\base\Event|null |
The event instance. If not set, a default yii\base\Event object will be created. |
public function trigger($name, Event $event = null)
{
$this->ensureBehaviors();
$eventHandlers = [];
foreach ($this->_eventWildcards as $wildcard => $handlers) {
if (StringHelper::matchWildcard($wildcard, $name)) {
$eventHandlers[] = $handlers;
}
}
if (!empty($this->_events[$name])) {
$eventHandlers[] = $this->_events[$name];
}
if (!empty($eventHandlers)) {
$eventHandlers = call_user_func_array('array_merge', $eventHandlers);
if ($event === null) {
$event = new Event();
}
if ($event->sender === null) {
$event->sender = $this;
}
$event->handled = false;
$event->name = $name;
foreach ($eventHandlers as $handler) {
$event->data = $handler[1];
call_user_func($handler[0], $event);
// stop further handling if the event is handled
if ($event->handled) {
return;
}
}
}
// invoke class-level attached handlers
Event::trigger($this, $name, $event);
}
Performs the data validation.
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 beforeValidate() and afterValidate() before and after the actual validation, respectively. If beforeValidate() returns false, the validation will be cancelled and afterValidate() will not be called.
Errors found during the validation can be retrieved via getErrors(), getFirstErrors() and getFirstError().
public boolean validate ( $attributeNames = null, $clearErrors = true ) | ||
$attributeNames | string[]|string|null |
Attribute name or 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. |
---|---|---|
throws | yii\base\InvalidArgumentException |
if the current scenario is unknown. |
public function validate($attributeNames = null, $clearErrors = true)
{
if ($clearErrors) {
$this->clearErrors();
}
if (!$this->beforeValidate()) {
return false;
}
$scenarios = $this->scenarios();
$scenario = $this->getScenario();
if (!isset($scenarios[$scenario])) {
throw new InvalidArgumentException("Unknown scenario: $scenario");
}
if ($attributeNames === null) {
$attributeNames = $this->activeAttributes();
}
$attributeNames = (array)$attributeNames;
foreach ($this->getActiveValidators() as $validator) {
$validator->validateAttributes($this, $attributeNames);
}
$this->afterValidate();
return !$this->hasErrors();
}
Validates multiple models.
This method will validate every model. The models being validated may be of the same or different types.
public static boolean validateMultiple ( $models, $attributeNames = null ) | ||
$models | array |
The models to be validated |
$attributeNames | array|null |
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 static function validateMultiple($models, $attributeNames = null)
{
$valid = true;
/* @var $model Model */
foreach ($models as $model) {
$valid = $model->validate($attributeNames) && $valid;
}
return $valid;
}
Event Details
An event raised at the end of validate()
An event raised at the beginning of validate(). You may set yii\base\ModelEvent::$isValid to be false to stop the validation.
Signup or Login in order to comment.