Class yii\db\ActiveRecord

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.

Defined in: yii\base\Model::__clone()

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.

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.

Defined in: yii\db\BaseActiveRecord::__get()

PHP getter magic method.

This method is overridden so that attributes and related objects can be accessed like properties.

See also getAttribute().

Defined in: yii\db\BaseActiveRecord::__isset()

Checks if a property value is null.

This method overrides the parent implementation by checking if the named attribute is null or not.

Defined in: yii\db\BaseActiveRecord::__set()

PHP setter magic method.

This method is overridden so that AR attributes can be accessed like properties.

Defined in: yii\db\BaseActiveRecord::__unset()

Sets a component property to be null.

This method overrides the parent implementation by clearing the specified attribute value.

Defined in: yii\base\Model::activeAttributes()

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

Defined in: yii\base\Model::addError()

Adds a new error to the specified attribute.

Defined in: yii\base\Model::addErrors()

Adds a list of errors.

Defined in: yii\db\BaseActiveRecord::afterDelete()

This method is invoked after deleting a record.

The default implementation raises the EVENT_AFTER_DELETE event. You may override this method to do postprocessing after the record is deleted. Make sure you call the parent implementation so that the event is raised properly.

Defined in: yii\db\BaseActiveRecord::afterFind()

This method is called when the AR object is created and populated with the query result.

The default implementation will trigger an EVENT_AFTER_FIND event. When overriding this method, make sure you call the parent implementation to ensure the event is triggered.

Defined in: yii\db\BaseActiveRecord::afterRefresh()

This method is called when the AR object is refreshed.

The default implementation will trigger an EVENT_AFTER_REFRESH event. When overriding this method, make sure you call the parent implementation to ensure the event is triggered.

Defined in: yii\db\BaseActiveRecord::afterSave()

This method is called at the end of inserting or updating a record.

The default implementation will trigger an EVENT_AFTER_INSERT event when $insert is true, or an EVENT_AFTER_UPDATE event if $insert is false. The event class used is yii\db\AfterSaveEvent. When overriding this method, make sure you call the parent implementation so that the event is triggered.

Defined in: yii\base\Model::afterValidate()

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.

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

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

Defined in: yii\base\Model::attributeHints()

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

Defined in: yii\base\Model::attributeLabels()

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

Defined in: yii\db\BaseActiveRecord::beforeDelete()

This method is invoked before deleting a record.

The default implementation raises the EVENT_BEFORE_DELETE event. When overriding this method, make sure you call the parent implementation like the following:

public function beforeDelete()
{
    if (!parent::beforeDelete()) {
        return false;
    }

    // ...custom code here...
    return true;
}

Defined in: yii\db\BaseActiveRecord::beforeSave()

This method is called at the beginning of inserting or updating a record.

The default implementation will trigger an EVENT_BEFORE_INSERT event when $insert is true, or an EVENT_BEFORE_UPDATE event if $insert is false. When overriding this method, make sure you call the parent implementation like the following:

public function beforeSave($insert)
{
    if (!parent::beforeSave($insert)) {
        return false;
    }

    // ...custom code here...
    return true;
}

Defined in: yii\base\Model::beforeValidate()

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.

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

Defined in: yii\db\BaseActiveRecord::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).

Defined in: yii\db\BaseActiveRecord::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).

Defined in: yii\base\BaseObject::className()

Returns the fully qualified name of this class.

Defined in: yii\base\Model::clearErrors()

Removes errors for all attributes or a single attribute.

Defined in: yii\db\BaseActiveRecord::createRelationQuery()

Creates a query instance for has-one or has-many relation.

See also:

• hasOne()
• hasMany()

Defined in: yii\base\Model::createValidators()

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.

Defined in: yii\base\Component::detachBehavior()

Detaches a behavior from the component.

The behavior's yii\base\Behavior::detach() method will be invoked.

Defined in: yii\base\Component::detachBehaviors()

Detaches all behaviors from the component.

Defined in: yii\base\Component::ensureBehaviors()

Makes sure that the behaviors declared in behaviors() are attached to this component.

Defined in: yii\db\BaseActiveRecord::extraFields()

Returns the list of fields that can be expanded further and returned by toArray().

The default implementation returns the names of the relations that have been populated into this record.

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

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

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

Defined in: yii\db\BaseActiveRecord::fields()

Returns the list of fields that should be returned by default by toArray() when no specific fields are specified.

The default implementation returns the names of the columns whose values have been populated into this record.

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

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.

Defined in: yii\db\BaseActiveRecord::findAll()

Returns a list of active record models that match the specified primary key value(s) or a set of column values.

The method accepts:

• a scalar value (integer or string): query by a single primary key value and return an array containing the corresponding record (or an empty array if not found).
• a non-associative array: query by a list of primary key values and return the corresponding records (or an empty array if none was found). Note that an empty condition will result in an empty result as it will be interpreted as a search for primary keys and not an empty WHERE condition.
• an associative array of name-value pairs: query by a set of attribute values and return an array of records matching all of them (or an empty array if none was found). Note that ['id' => 1, 2] is treated as a non-associative array. Column names are limited to current records table columns for SQL DBMS, or filtered otherwise to be limted to simple filter conditions.
• a yii\db\Expression: The expression will be used directly. (@since 2.0.37)

This method will automatically call the all() method and return an array of ActiveRecord instances.

Note: As this is a short-hand method only, using more complex conditions, like ['!=', 'id', 1] will not work. If you need to specify more complex conditions, use find() in combination with where() instead.

See the following code for usage examples:

// find the customers whose primary key value is 10
$customers = Customer::findAll(10);

// the above code is equivalent to:
$customers = Customer::find()->where(['id' => 10])->all();

// find the customers whose primary key value is 10, 11 or 12.
$customers = Customer::findAll([10, 11, 12]);

// the above code is equivalent to:
$customers = Customer::find()->where(['id' => [10, 11, 12]])->all();

// find customers whose age is 30 and whose status is 1
$customers = Customer::findAll(['age' => 30, 'status' => 1]);

// the above code is equivalent to:
$customers = Customer::find()->where(['age' => 30, 'status' => 1])->all();

If you need to pass user input to this method, make sure the input value is scalar or in case of array condition, make sure the array structure can not be changed from the outside:

// yii\web\Controller ensures that $id is scalar
public function actionView($id)
{
    $model = Post::findOne($id);
    // ...
}

// explicitly specifying the colum to search, passing a scalar or array here will always result in finding a single record
$model = Post::findOne(['id' => Yii::$app->request->get('id')]);

// do NOT use the following code! it is possible to inject an array condition to filter by arbitrary column values!
$model = Post::findOne(Yii::$app->request->get('id'));

Defined in: yii\db\BaseActiveRecord::findOne()

Returns a single active record model instance by a primary key or an array of column values.

The method accepts:

• a scalar value (integer or string): query by a single primary key value and return the corresponding record (or null if not found).
• a non-associative array: query by a list of primary key values and return the first record (or null if not found).
• an associative array of name-value pairs: query by a set of attribute values and return a single record matching all of them (or null if not found). Note that ['id' => 1, 2] is treated as a non-associative array. Column names are limited to current records table columns for SQL DBMS, or filtered otherwise to be limited to simple filter conditions.
• a yii\db\Expression: The expression will be used directly. (@since 2.0.37)

That this method will automatically call the one() method and return an ActiveRecord instance.

Note: As this is a short-hand method only, using more complex conditions, like ['!=', 'id', 1] will not work. If you need to specify more complex conditions, use find() in combination with where() instead.

See the following code for usage examples:

// find a single customer whose primary key value is 10
$customer = Customer::findOne(10);

// the above code is equivalent to:
$customer = Customer::find()->where(['id' => 10])->one();

// find the customers whose primary key value is 10, 11 or 12.
$customers = Customer::findOne([10, 11, 12]);

// the above code is equivalent to:
$customers = Customer::find()->where(['id' => [10, 11, 12]])->one();

// find the first customer whose age is 30 and whose status is 1
$customer = Customer::findOne(['age' => 30, 'status' => 1]);

// the above code is equivalent to:
$customer = Customer::find()->where(['age' => 30, 'status' => 1])->one();

If you need to pass user input to this method, make sure the input value is scalar or in case of array condition, make sure the array structure can not be changed from the outside:

// yii\web\Controller ensures that $id is scalar
public function actionView($id)
{
    $model = Post::findOne($id);
    // ...
}

// explicitly specifying the colum to search, passing a scalar or array here will always result in finding a single record
$model = Post::findOne(['id' => Yii::$app->request->get('id')]);

// do NOT use the following code! it is possible to inject an array condition to filter by arbitrary column values!
$model = Post::findOne(Yii::$app->request->get('id'));

Defined in: yii\base\Model::formName()

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

Defined in: yii\base\Model::generateAttributeLabel()

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

Defined in: yii\base\Model::getActiveValidators()

Returns the validators applicable to the current $scenario.

Defined in: yii\db\BaseActiveRecord::getAttribute()

Returns the named attribute value.

If this record is the result of a query and the attribute is not loaded, null will be returned.

See also hasAttribute().

Defined in: yii\db\BaseActiveRecord::getAttributeHint()

Returns the text hint for the specified attribute.

If the attribute looks like relatedModel.attribute, then the attribute will be received from the related model.

See also attributeHints().

Defined in: yii\db\BaseActiveRecord::getAttributeLabel()

Returns the text label for the specified attribute.

If the attribute looks like relatedModel.attribute, then the attribute will be received from the related model.

See also:

• generateAttributeLabel()
• attributeLabels()

Defined in: yii\base\Model::getAttributes()

Returns attribute values.

Defined in: yii\base\Component::getBehavior()

Returns the named behavior object.

Defined in: yii\base\Component::getBehaviors()

Returns all behaviors attached to this component.

Defined in: yii\db\BaseActiveRecord::getDirtyAttributes()

Returns the attribute values that have been modified since they are loaded or saved most recently.

The comparison of new and old values is made for identical values using ===.

Defined in: yii\base\Model::getErrorSummary()

Returns the errors for all attributes as a one-dimensional array.

See also:

• getErrors()
• getFirstErrors()

Defined in: yii\base\Model::getErrors()

Returns the errors for all attributes or a single attribute.

See also:

• getFirstErrors()
• getFirstError()

Defined in: yii\base\Model::getFirstError()

Returns the first error of the specified attribute.

See also:

• getErrors()
• getFirstErrors()

Defined in: yii\base\Model::getFirstErrors()

Returns the first error of every attribute in the model.

See also:

• getErrors()
• getFirstError()

Defined in: yii\db\BaseActiveRecord::getIsNewRecord()

Returns a value indicating whether the current record is new.

Defined in: yii\base\Model::getIterator()

Returns an iterator for traversing the attributes in the model.

This method is required by the interface IteratorAggregate.

Defined in: yii\db\BaseActiveRecord::getOldAttribute()

Returns the old value of the named attribute.

If this record is the result of a query and the attribute is not loaded, null will be returned.

See also hasAttribute().

Defined in: yii\db\BaseActiveRecord::getOldAttributes()

Returns the old attribute values.

Defined in: yii\db\BaseActiveRecord::getOldPrimaryKey()

Returns the old primary key value(s).

This refers to the primary key value that is populated into the record after executing a find method (e.g. find(), findOne()). The value remains unchanged even if the primary key attribute is manually assigned with a different value.

Defined in: yii\db\BaseActiveRecord::getPrimaryKey()

Returns the primary key value(s).

Defined in: yii\db\BaseActiveRecord::getRelatedRecords()

Returns all populated related records.

See also getRelation().

Defined in: yii\db\BaseActiveRecord::getRelation()

Returns the relation object with the specified name.

A relation is defined by a getter method which returns an yii\db\ActiveQueryInterface object. It can be declared in either the Active Record class itself or one of its behaviors.

Defined in: yii\base\Model::getScenario()

Returns the scenario that this model is used in.

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

Defined in: yii\base\Model::getValidators()

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;

Defined in: yii\db\BaseActiveRecord::hasAttribute()

Returns a value indicating whether the model has an attribute with the specified name.

Defined in: yii\base\Model::hasErrors()

Returns a value indicating whether there is any validation error.

Defined in: yii\base\Component::hasEventHandlers()

Returns a value indicating whether there is any handler attached to the named event.

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

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:

• canGetProperty()
• canSetProperty()

Defined in: yii\db\BaseActiveRecord::init()

Initializes the object.

This method is called at the end of the constructor. The default implementation will trigger an EVENT_INIT event.

Defined in: yii\base\StaticInstanceTrait::instance()

Returns static class instance, which can be used to obtain meta information.

Defined in: yii\db\BaseActiveRecord::instantiate()

Creates an active record instance.

This method is called together with populateRecord() by yii\db\ActiveQuery. It is not meant to be used for creating new records directly.

You may override this method if the instance being created depends on the row data to be populated into the record. For example, by creating a record based on the value of a column, you may implement the so-called single-table inheritance mapping.

Defined in: yii\base\Model::isAttributeActive()

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

See also activeAttributes().

Defined in: yii\db\BaseActiveRecord::isAttributeChanged()

Returns a value indicating whether the named attribute has been changed.

Defined in: yii\base\Model::isAttributeRequired()

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.

Defined in: yii\base\Model::isAttributeSafe()

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

See also safeAttributes().

Defined in: yii\db\BaseActiveRecord::isPrimaryKey()

Returns a value indicating whether the given set of attributes represents the primary key for this model.

Defined in: yii\db\BaseActiveRecord::isRelationPopulated()

Check whether the named relation has been populated with records.

See also getRelation().

Defined in: yii\db\BaseActiveRecord::link()

Establishes the relationship between two models.

The relationship is established by setting the foreign key value(s) in one model to be the corresponding primary key value(s) in the other model. The model with the foreign key will be saved into database without performing validation and without events/behaviors.

If the relationship involves a junction table, a new row will be inserted into the junction table which contains the primary key values from both models.

Note that this method requires that the primary key value is not null.

Defined in: yii\base\Model::load()

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

Defined in: yii\base\Model::loadMultiple()

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

Defined in: yii\db\BaseActiveRecord::markAttributeDirty()

Marks an attribute dirty.

This method may be called to force updating a record when calling update(), even if there is no change being made to the record.

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

Defined in: yii\db\BaseActiveRecord::offsetExists()

Returns whether there is an element at the specified offset.

This method is required by the interface ArrayAccess.

Defined in: yii\base\Model::offsetGet()

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];.

Defined in: yii\base\Model::offsetSet()

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

Defined in: yii\db\BaseActiveRecord::offsetUnset()

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

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