ActiveRecord

API reference › yii › db › ActiveRecord

class	`yii\db\ActiveRecord`
Extends	`BaseActiveRecord` » `yii\base\Model` » `yii\base\Component` » `yii\base\BaseObject`
Implements	`yii\base\StaticInstanceInterface`, `IteratorAggregate`, `ArrayAccess`, `yii\base\Arrayable`, `yii\base\Configurable`, `ActiveRecordInterface`
Uses traits	`yii\base\ArrayableTrait`, `yii\base\StaticInstanceTrait`
Since	2.0
Source	`framework/db/ActiveRecord.php`

ActiveRecord is the base class for classes representing relational data in terms of objects.

Active Record implements the Active Record design pattern. The premise behind Active Record is that an individual ActiveRecord object is associated with a specific row in a database table. The object’s attributes are mapped to the columns of the corresponding table. Referencing an Active Record attribute is equivalent to accessing the corresponding table column for that record.

As an example, say that the Customer ActiveRecord class is associated with the customer table. This would mean that the class’s name attribute is automatically mapped to the name column in customer table. Thanks to Active Record, assuming the variable $customer is an object of type Customer, to get the value of the name column for the table row, you can use the expression $customer->name. In this example, Active Record is providing an object-oriented interface for accessing data stored in the database. But Active Record provides much more functionality than this.

To declare an ActiveRecord class you need to extend ActiveRecord and implement the tableName method:

<?php

class Customer extends \yii\db\ActiveRecord
{
    public static function tableName()
    {
        return 'customer';
    }
}

The tableName method only has to return the name of the database table associated with the class.

Tip: You may also use the Gii code generator to generate ActiveRecord classes from your database tables.

Class instances are obtained in one of two ways:

Using the new operator to create a new, empty object
Using a method to fetch an existing record (or records) from the database

Below is an example showing some typical usage of ActiveRecord:

$user = new User();
$user->name = 'Qiang';
$user->save();  // a new row is inserted into user table

// the following will retrieve the user 'CeBe' from the database
$user = User::find()->where(['name' => 'CeBe'])->one();

// this will get related records from orders table when relation is defined
$orders = $user->orders;

For more details and usage information on ActiveRecord, see the guide article on ActiveRecord.

Properties

Property	Type	Description	Defined by
`$activeValidators` read-only	`yii\validators\Validator[]`	The validators applicable to the current `$scenario`.	`yii\base\Model`
`$attributes`	`array<string, mixed>`	Attribute values (name => value).	`yii\base\Model`
`$behaviors` read-only	`array<yii\base\Behavior<static>>`	List of behaviors attached to this component.	`yii\base\Component`
`$dirtyAttributes` read-only	`array`	The changed attribute values (name-value pairs).	`BaseActiveRecord`
`$errors` read-only	`array<string, string[]>`	Errors for all attributes.	`yii\base\Model`
`$firstErrors` read-only	`array<string, string>`	The first errors.	`yii\base\Model`
`$isNewRecord`	`bool`	Whether the record is new and should be inserted when calling `save()`.	`BaseActiveRecord`
`$iterator` read-only	`ArrayIterator<string, mixed>`	An iterator for traversing the items in the list.	`yii\base\Model`
`$oldAttributes`	`array\|null`	Old attribute values to be set.	`BaseActiveRecord`
`$oldPrimaryKey` read-only	`mixed`	The old primary key value.	`BaseActiveRecord`
`$primaryKey` read-only	`mixed`	The primary key value.	`BaseActiveRecord`
`$relatedRecords` read-only	`array`	An array of related records indexed by relation names.	`BaseActiveRecord`
`$scenario`	`string`	The scenario that this model is in.	`yii\base\Model`
`$validators` read-only	`ArrayObject<int,` `yii\validators\Validator>\|yii\validators\Validator[]`	All the validators declared in the model.	`yii\base\Model`

Methods

Method	Description	Defined by
`__construct()`	Constructor.	`yii\base\BaseObject`
`__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`
`__get()`	PHP getter magic method.	`BaseActiveRecord`
`__isset()`	Checks if a property value is null.	`BaseActiveRecord`
`__set()`	PHP setter magic method.	`BaseActiveRecord`
`__unset()`	Sets a component property to be null.	`BaseActiveRecord`
`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`
`afterDelete()`	This method is invoked after deleting a record.	`BaseActiveRecord`
`afterFind()`	This method is called when the AR object is created and populated with the query result.	`BaseActiveRecord`
`afterRefresh()`	This method is called when the AR object is refreshed.	`BaseActiveRecord`
`afterSave()`	This method is called at the end of inserting or updating a record.	`BaseActiveRecord`
`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 all attribute names of the model.	`ActiveRecord`
`beforeDelete()`	This method is invoked before deleting a record.	`BaseActiveRecord`
`beforeSave()`	This method is called at the beginning of inserting or updating a record.	`BaseActiveRecord`
`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.	`BaseActiveRecord`
`canSetOldAttribute()`	Returns if the old named attribute can be set.	`BaseActiveRecord`
`canSetProperty()`	Returns a value indicating whether a property can be set.	`BaseActiveRecord`
`className()` static	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`
`delete()`	Deletes the table row corresponding to this active record.	`ActiveRecord`
`deleteAll()` static	Deletes rows in the table using the provided conditions.	`ActiveRecord`
`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`
`equals()`	Returns a value indicating whether the given active record is the same as the current one.	`ActiveRecord`
`extraFields()`	Returns the list of fields that can be expanded further and returned by `toArray()`.	`BaseActiveRecord`
`fields()`	Returns the list of fields that should be returned by default by `toArray()` when no specific fields are specified.	`BaseActiveRecord`
`find()` static	Creates an `ActiveQueryInterface` instance for query purpose.	`ActiveRecord`
`findAll()` static	Returns a list of active record models that match the specified primary key value(s) or a set of column values.	`BaseActiveRecord`
`findBySql()` static	Creates an `ActiveQuery` instance with a given SQL statement.	`ActiveRecord`
`findOne()` static	Returns a single active record model instance by a primary key or an array of column values.	`BaseActiveRecord`
`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`
`getAttribute()`	Returns the named attribute value.	`BaseActiveRecord`
`getAttributeHint()`	Returns the text hint for the specified attribute.	`BaseActiveRecord`
`getAttributeLabel()`	Returns the text label for the specified attribute.	`BaseActiveRecord`
`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`
`getDb()` static	Returns the database connection used by this AR class.	`ActiveRecord`
`getDirtyAttributes()`	Returns the attribute values that have been modified since they are loaded or saved most recently.	`BaseActiveRecord`
`getErrors()`	Returns the errors for all attributes or a single attribute.	`yii\base\Model`
`getErrorSummary()`	Returns the errors for all attributes as a one-dimensional array.	`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`
`getIsNewRecord()`	Returns a value indicating whether the current record is new.	`BaseActiveRecord`
`getIterator()`	Returns an iterator for traversing the attributes in the model.	`yii\base\Model`
`getOldAttribute()`	Returns the old value of the named attribute.	`BaseActiveRecord`
`getOldAttributes()`	Returns the old attribute values.	`BaseActiveRecord`
`getOldPrimaryKey()`	Returns the old primary key value(s).	`BaseActiveRecord`
`getPrimaryKey()`	Returns the primary key value(s).	`BaseActiveRecord`
`getRelatedRecords()`	Returns all populated related records.	`BaseActiveRecord`
`getRelation()`	Returns the relation object with the specified name.	`BaseActiveRecord`
`getScenario()`	Returns the scenario that this model is used in.	`yii\base\Model`
`getTableSchema()` static	Returns the schema information of the DB table associated with this AR class.	`ActiveRecord`
`getValidators()`	Returns all the validators declared in `rules()`.	`yii\base\Model`
`hasAttribute()`	Returns a value indicating whether the model has an attribute with the specified name.	`BaseActiveRecord`
`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`
`hasMany()`	Declares a `has-many` relation.	`ActiveRecord`
`hasMethod()`	Returns a value indicating whether a method is defined.	`yii\base\Component`
`hasOne()`	Declares a `has-one` relation.	`ActiveRecord`
`hasProperty()`	Returns a value indicating whether a property is defined for this component.	`yii\base\Component`
`init()`	Initializes the object.	`BaseActiveRecord`
`insert()`	Inserts a row into the associated database table using the attribute values of this record.	`ActiveRecord`
`instance()` static	Returns static class instance, which can be used to obtain meta information.	`yii\base\StaticInstanceTrait`
`instantiate()` static	Creates an active record instance.	`BaseActiveRecord`
`isAttributeActive()`	Returns a value indicating whether the attribute is active in the current scenario.	`yii\base\Model`
`isAttributeChanged()`	Returns a value indicating whether the named attribute has been changed.	`BaseActiveRecord`
`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`
`isPrimaryKey()` static	Returns a value indicating whether the given set of attributes represents the primary key for this model.	`BaseActiveRecord`
`isRelationPopulated()`	Check whether the named relation has been populated with records.	`BaseActiveRecord`
`isTransactional()`	Returns a value indicating whether the specified operation is transactional in the current `$scenario`.	`ActiveRecord`
`link()`	Establishes the relationship between two models.	`BaseActiveRecord`
`load()`	Populates the model with input data.	`yii\base\Model`
`loadDefaultValues()`	Loads default values from database table schema.	`ActiveRecord`
`loadMultiple()` static	Populates a set of models with the data from end user.	`yii\base\Model`
`loadRelations()`	Eager loads related models for the already loaded primary model.	`BaseActiveRecord`
`loadRelationsFor()` static	Eager loads related models for the already loaded primary models.	`BaseActiveRecord`
`markAttributeDirty()`	Marks an attribute dirty.	`BaseActiveRecord`
`off()`	Detaches an existing event handler from this component.	`yii\base\Component`
`offsetExists()`	Returns whether there is an element at the specified offset.	`BaseActiveRecord`
`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.	`BaseActiveRecord`
`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`
`optimisticLock()`	Returns the name of the column that stores the lock version for implementing optimistic locking.	`BaseActiveRecord`
`populateRecord()` static	Populates an active record object using a row of data from the database/storage.	`ActiveRecord`
`populateRelation()`	Populates the named relation with the related records.	`BaseActiveRecord`
`primaryKey()` static	Returns the primary key name(s) for this AR class.	`ActiveRecord`
`refresh()`	Repopulates this active record with the latest data.	`ActiveRecord`
`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`
`save()`	Saves the current record.	`BaseActiveRecord`
`scenarios()`	Returns a list of scenarios and the corresponding active attributes.	`yii\base\Model`
`setAttribute()`	Sets the named attribute value.	`BaseActiveRecord`
`setAttributes()`	Sets the attribute values in a massive way.	`yii\base\Model`
`setIsNewRecord()`	Sets the value indicating whether the record is new.	`BaseActiveRecord`
`setOldAttribute()`	Sets the old value of the named attribute.	`BaseActiveRecord`
`setOldAttributes()`	Sets the old attribute values.	`BaseActiveRecord`
`setScenario()`	Sets the scenario for the model.	`yii\base\Model`
`tableName()` static	Declares the name of the database table associated with this AR class.	`ActiveRecord`
`toArray()`	Converts the model into an array.	`yii\base\ArrayableTrait`
`transactions()`	Declares which DB operations should be performed within a transaction in different scenarios.	`ActiveRecord`
`trigger()`	Triggers an event.	`yii\base\Component`
`unlink()`	Destroys the relationship between two models.	`BaseActiveRecord`
`unlinkAll()`	Destroys the relationship in current model.	`BaseActiveRecord`
`update()`	Saves the changes to this active record into the associated database table.	`ActiveRecord`
`updateAll()` static	Updates the whole table using the provided attribute values and conditions.	`ActiveRecord`
`updateAllCounters()` static	Updates the whole table using the provided counter changes and conditions.	`ActiveRecord`
`updateAttributes()`	Updates the specified attributes.	`BaseActiveRecord`
`updateCounters()`	Updates one or several counter columns for the current AR object.	`BaseActiveRecord`
`validate()`	Performs the data validation.	`yii\base\Model`
`validateMultiple()` static	Validates multiple models.	`yii\base\Model`
`createRelationQuery()` protected	Creates a query instance for `has-one` or `has-many` relation.	`BaseActiveRecord`
`deleteInternal()` protected	Deletes an ActiveRecord without considering transaction.	`ActiveRecord`
`extractFieldsFor()` protected	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()` protected	Extracts the root field names from nested fields.	`yii\base\ArrayableTrait`
`insertInternal()` protected	Inserts an ActiveRecord into DB without considering transaction.	`ActiveRecord`
`refreshInternal()` protected	Repopulates this active record with the latest data from a newly fetched instance.	`BaseActiveRecord`
`resolveFields()` protected	Determines which fields can be returned by `toArray()`.	`yii\base\ArrayableTrait`
`updateInternal()` protected		`BaseActiveRecord`

Events

Event	Type	Description	Defined by
`EVENT_INIT`	`yii\db\Event`	An event that is triggered when the record is initialized via `init()`. Event name: `'init'`.	`BaseActiveRecord`
`EVENT_AFTER_FIND`	`yii\db\Event`	An event that is triggered after the record is created and populated with query result. Event name: `'afterFind'`.	`BaseActiveRecord`
`EVENT_BEFORE_INSERT`	`yii\base\ModelEvent`	An event that is triggered before inserting a record. Event name: `'beforeInsert'`.	`BaseActiveRecord`
`EVENT_AFTER_INSERT`	`AfterSaveEvent`	An event that is triggered after a record is inserted. Event name: `'afterInsert'`.	`BaseActiveRecord`
`EVENT_BEFORE_UPDATE`	`yii\base\ModelEvent`	An event that is triggered before updating a record. Event name: `'beforeUpdate'`.	`BaseActiveRecord`
`EVENT_AFTER_UPDATE`	`AfterSaveEvent`	An event that is triggered after a record is updated. Event name: `'afterUpdate'`.	`BaseActiveRecord`
`EVENT_BEFORE_DELETE`	`yii\base\ModelEvent`	An event that is triggered before deleting a record. Event name: `'beforeDelete'`.	`BaseActiveRecord`
`EVENT_AFTER_DELETE`	`yii\db\Event`	An event that is triggered after a record is deleted. Event name: `'afterDelete'`.	`BaseActiveRecord`
`EVENT_AFTER_REFRESH`	`yii\db\Event`	An event that is triggered after a record is refreshed. Event name: `'afterRefresh'`. Available since 2.0.8.	`BaseActiveRecord`
`EVENT_BEFORE_VALIDATE`	`yii\base\ModelEvent`	An event raised at the beginning of `validate()`. Event name: `'beforeValidate'`.	`yii\base\Model`
`EVENT_AFTER_VALIDATE`	`yii\base\Event`	An event raised at the end of `validate()` Event name: `'afterValidate'`.	`yii\base\Model`

Constants

Constant	Value	Description	Defined by
`OP_INSERT`	`0x1`	The insert operation. This is mainly used when overriding `transactions()` to specify which operations are transactional.	`ActiveRecord`
`OP_UPDATE`	`0x2`	The update operation. This is mainly used when overriding `transactions()` to specify which operations are transactional.	`ActiveRecord`
`OP_DELETE`	`0x4`	The delete operation. This is mainly used when overriding `transactions()` to specify which operations are transactional.	`ActiveRecord`
`OP_ALL`	`0x7`	All three operations: insert, update, delete.	`ActiveRecord`
`SCENARIO_DEFAULT`	`'default'`	The name of the default scenario.	`yii\base\Model`

Method details

attributes()

public function attributes(): array

Returns the list of all attribute names of the model.

The default implementation will return all column names of the table associated with this AR class.

Returns

array: List of attribute names.

delete()

public function delete(): int|false

Deletes the table row corresponding to this active record.

This method performs the following steps in order:

call beforeDelete(). If the method returns false, it will skip the rest of the steps;
delete the record from the database;
call afterDelete().

In the above step 1 and 3, events named EVENT_BEFORE_DELETE and EVENT_AFTER_DELETE will be raised by the corresponding methods.

Returns

int|false: The number of rows deleted, or false if the deletion is unsuccessful for some reason. Note that it is possible the number of rows deleted is 0, even though the deletion execution is successful.

Throws

StaleObjectException: if optimistic locking is enabled and the data being deleted is outdated.
Throwable: in case delete failed.

deleteAll()

public static function deleteAll(string|array|null $condition = null, array $params = []): int

Deletes rows in the table using the provided conditions.

For example, to delete all customers whose status is 3:

Customer::deleteAll('status = 3');

Warning: If you do not specify any condition, this method will delete all rows in the table.

Note that this method will not trigger any events. If you need EVENT_BEFORE_DELETE or EVENT_AFTER_DELETE to be triggered, you need to find the models first and then call delete() on each of them. For example an equivalent of the example above would be:

$models = Customer::find()->where('status = 3')->all();
foreach ($models as $model) {
    $model->delete();
}

For a large set of models you might consider using ActiveQuery::each() to keep memory usage within limits.

Parameters

Parameter	Type	Description
`$condition`	`string\|array\|null`	The conditions that will be put in the WHERE part of the DELETE SQL. Please refer to `Query::where()` on how to specify this parameter.
`$params`	`array`	The parameters (name => value) to be bound to the query.

Returns

int: The number of rows deleted

equals()

public function equals(yii\db\ActiveRecord $record): bool

Returns a value indicating whether the given active record is the same as the current one.

The comparison is made by comparing the table names and the primary key values of the two active records. If one of the records is new they are also considered not equal.

Parameters

Parameter	Type	Description
`$record`	`ActiveRecord`	Record to compare to

Returns

bool: Whether the two active records refer to the same row in the same database table.

find()

public static function find(): yii\db\ActiveQuery<static>

Creates an ActiveQueryInterface instance for query purpose.

The returned ActiveQueryInterface instance can be further customized by calling methods defined in ActiveQueryInterface before one() or all() is called to return populated ActiveRecord instances. For example,

// find the customer whose ID is 1
$customer = Customer::find()->where(['id' => 1])->one();

// find all active customers and order them by their age:
$customers = Customer::find()
    ->where(['status' => 1])
    ->orderBy('age')
    ->all();

This method is also called by BaseActiveRecord::hasOne() and BaseActiveRecord::hasMany() to create a relational query.

You may override this method to return a customized query. For example,

class Customer extends ActiveRecord
{
    public static function find()
    {
        // use CustomerQuery instead of the default ActiveQuery
        return new CustomerQuery(get_called_class());
    }
}

The following code shows how to apply a default condition for all queries:

class Customer extends ActiveRecord
{
    public static function find()
    {
        return parent::find()->where(['deleted' => false]);
    }
}

// Use andWhere()/orWhere() to apply the default condition
// SELECT FROM customer WHERE `deleted`=:deleted AND age>30
$customers = Customer::find()->andWhere('age>30')->all();

// Use where() to ignore the default condition
// SELECT FROM customer WHERE age>30
$customers = Customer::find()->where('age>30')->all();

Returns

ActiveQuery<static>: The newly created ActiveQuery instance.

findBySql()

public static function findBySql(string $sql, array $params = []): yii\db\ActiveQuery<static>

Creates an ActiveQuery instance with a given SQL statement.

Note that because the SQL statement is already specified, calling additional query modification methods (such as where(), order()) on the created ActiveQuery instance will have no effect. However, calling with(), asArray() or indexBy() is still fine.

Below is an example:

$customers = Customer::findBySql('SELECT * FROM customer')->all();

Parameters

Parameter	Type	Description
`$sql`	`string`	The SQL statement to be executed
`$params`	`array`	Parameters to be bound to the SQL statement during execution.

Returns

ActiveQuery<static>: The newly created ActiveQuery instance

getDb()

public static function getDb(): yii\db\Connection

Returns the database connection used by this AR class.

By default, the “db” application component is used as the database connection. You may override this method if you want to use a different database connection.

Returns

Connection: The database connection used by this AR class.

getTableSchema()

public static function getTableSchema(yii\db\Connection|null $db = null): yii\db\TableSchema

Returns the schema information of the DB table associated with this AR class.

Parameters

Parameter	Type	Description
`$db`	`Connection\|null`	The database connection used to retrieve the schema. If `null`, the connection returned by `getDb()` will be used.

Returns

TableSchema: The schema information of the DB table associated with this AR class.

Throws

yii\base\InvalidConfigException: if the table for the AR class does not exist.

hasMany()

public function hasMany(class-string<yii\db\T> $class, mixed $link): yii\db\ActiveQuery<yii\db\T>

Declares a has-many relation.

The declaration is returned in terms of a relational ActiveQuery instance through which the related record can be queried and retrieved back.

A has-many relation means that there are multiple related records matching the criteria set by this relation, e.g., a customer has many orders.

For example, to declare the orders relation for Customer class, we can write the following code in the Customer class:

public function getOrders()
{
    return $this->hasMany(Order::class, ['customer_id' => 'id']);
}

Note that in the above, the ‘customer_id’ key in the $link parameter refers to an attribute name in the related class Order, while the ‘id’ value refers to an attribute name in the current AR class.

Call methods declared in ActiveQuery to further customize the relation.

Parameters

Parameter	Type	Description
`$class`	`class-string<yii\db\T>`	The class name of the related record.
`$link`	`mixed`	The primary-foreign key constraint. The keys of the array refer to the attributes of the record associated with the `$class` model, while the values of the array refer to the corresponding attributes in this AR class.

Returns

ActiveQuery<yii\db\T>: The relational query object.

hasOne()

public function hasOne(class-string<yii\db\T> $class, mixed $link): yii\db\ActiveQuery<yii\db\T>

Declares a has-one relation.

The declaration is returned in terms of a relational ActiveQuery instance through which the related record can be queried and retrieved back.

A has-one relation means that there is at most one related record matching the criteria set by this relation, e.g., a customer has one country.

For example, to declare the country relation for Customer class, we can write the following code in the Customer class:

public function getCountry()
{
    return $this->hasOne(Country::class, ['id' => 'country_id']);
}

Note that in the above, the ‘id’ key in the $link parameter refers to an attribute name in the related class Country, while the ‘country_id’ value refers to an attribute name in the current AR class.

Call methods declared in ActiveQuery to further customize the relation.

Parameters

Parameter	Type	Description
`$class`	`class-string<yii\db\T>`	The class name of the related record.
`$link`	`mixed`	The primary-foreign key constraint. The keys of the array refer to the attributes of the record associated with the `$class` model, while the values of the array refer to the corresponding attributes in this AR class.

Returns

ActiveQuery<yii\db\T>: The relational query object.

insert()

public function insert(bool $runValidation = true, array|null $attributes = null): bool

Inserts a row into the associated database table using the attribute values of this record.

This method performs the following steps in order:

call beforeValidate() when $runValidation is true. If beforeValidate() returns false, the rest of the steps will be skipped;
call afterValidate() when $runValidation is true. If validation failed, the rest of the steps will be skipped;
call beforeSave(). If beforeSave() returns false, the rest of the steps will be skipped;
insert the record into database. If this fails, it will skip the rest of the steps;
call afterSave();

In the above step 1, 2, 3 and 5, events EVENT_BEFORE_VALIDATE, EVENT_AFTER_VALIDATE, EVENT_BEFORE_INSERT, and EVENT_AFTER_INSERT will be raised by the corresponding methods.

Only the changed attribute values will be inserted into database.

If the table’s primary key is auto-incremental and is null during insertion, it will be populated with the actual value after insertion.

For example, to insert a customer record:

$customer = new Customer;
$customer->name = $name;
$customer->email = $email;
$customer->insert();

Parameters

Parameter	Type	Description
`$runValidation`	`bool`	Whether to perform validation (calling `validate()`) before saving the record. Defaults to `true`. If the validation fails, the record will not be saved to the database and this method will return `false`.
`$attributes`	`array\|null`	List of attributes that need to be saved. Defaults to `null`, meaning all attributes that are loaded from DB will be saved.

Returns

bool: Whether the attributes are valid and the record is inserted successfully.

Throws

Throwable: in case insert failed.

isTransactional()

public function isTransactional(int $operation): bool

Returns a value indicating whether the specified operation is transactional in the current $scenario.

Parameters

Parameter	Type	Description
`$operation`	`int`	The operation to check. Possible values are `OP_INSERT`, `OP_UPDATE` and `OP_DELETE`.

Returns

bool: Whether the specified operation is transactional in the current $scenario.

loadDefaultValues()

public function loadDefaultValues(bool $skipIfSet = true): $this

Loads default values from database table schema.

You may call this method to load default values after creating a new instance:

// class Customer extends \yii\db\ActiveRecord
$customer = new Customer();
$customer->loadDefaultValues();

Parameters

Parameter	Type	Description
`$skipIfSet`	`bool`	Whether existing value should be preserved. This will only set defaults for attributes that are `null`.

Returns

$this: The model instance itself.

populateRecord()

public static function populateRecord(mixed $record, mixed $row, yii\db\Connection|null $db = null): mixed

Populates an active record object using a row of data from the database/storage.

This is an internal method meant to be called to create active record objects after fetching data from the database. It is mainly used by ActiveQuery to populate the query results into active records.

When calling this method manually you should call afterFind() on the created record to trigger the afterFind Event.

Parameters

Parameter	Type	Description
`$record`	`mixed`	The record to be populated. In most cases this will be an instance created by `instantiate()` beforehand.
`$row`	`mixed`	Attribute values (name => value)
`$db`	`Connection\|null`	The database connection used to retrieve the row and its schema.

Returns

mixed

primaryKey()

public static function primaryKey(): string[]

Returns the primary key name(s) for this AR class.

The default implementation will return the primary key(s) as declared in the DB table that is associated with this AR class.

If the DB table does not declare any primary key, you should override this method to return the attributes that you want to use as primary keys for this AR class.

Note that an array should be returned even for a table with single primary key.

Returns

string[]: The primary keys of the associated database table.

refresh()

public function refresh(): bool

Repopulates this active record with the latest data.

If the refresh is successful, an EVENT_AFTER_REFRESH event will be triggered. This event is available since version 2.0.8.

Returns

bool: Whether the row still exists in the database. If true, the latest data will be populated to this active record. Otherwise, this record will remain unchanged.

tableName()

public static function tableName(): string

Declares the name of the database table associated with this AR class.

By default this method returns the class name as the table name by calling Inflector::camel2id() with prefix Connection::$tablePrefix. For example if Connection::$tablePrefix is tbl_, Customer becomes tbl_customer, and OrderItem becomes tbl_order_item. You may override this method if the table is not named after this convention.

Returns

string: The table name

transactions()

public function transactions(): array

Declares which DB operations should be performed within a transaction in different scenarios.

The supported DB operations are: OP_INSERT, OP_UPDATE and OP_DELETE, which correspond to the insert(), update() and delete() methods, respectively. By default, these methods are NOT enclosed in a DB transaction.

In some scenarios, to ensure data consistency, you may want to enclose some or all of them in transactions. You can do so by overriding this method and returning the operations that need to be transactional. For example,

return [
    'admin' => self::OP_INSERT,
    'api' => self::OP_INSERT | self::OP_UPDATE | self::OP_DELETE,
    // the above is equivalent to the following:
    // 'api' => self::OP_ALL,

];

The above declaration specifies that in the “admin” scenario, the insert operation (insert()) should be done in a transaction; and in the “api” scenario, all the operations should be done in a transaction.

Returns

array: The declarations of transactional operations. The array keys are scenarios names, and the array values are the corresponding transaction operations.

update()

public function update(bool $runValidation = true, array|null $attributeNames = null): int|false

Saves the changes to this active record into the associated database table.

This method performs the following steps in order:

call beforeValidate() when $runValidation is true. If beforeValidate() returns false, the rest of the steps will be skipped;
call afterValidate() when $runValidation is true. If validation failed, the rest of the steps will be skipped;
call beforeSave(). If beforeSave() returns false, the rest of the steps will be skipped;
save the record into database. If this fails, it will skip the rest of the steps;
call afterSave();

In the above step 1, 2, 3 and 5, events EVENT_BEFORE_VALIDATE, EVENT_AFTER_VALIDATE, EVENT_BEFORE_UPDATE, and EVENT_AFTER_UPDATE will be raised by the corresponding methods.

Only the changed attribute values will be saved into database.

For example, to update a customer record:

$customer = Customer::findOne($id);
$customer->name = $name;
$customer->email = $email;
$customer->update();

Note that it is possible the update does not affect any row in the table. In this case, this method will return 0. For this reason, you should use the following code to check if update() is successful or not:

if ($customer->update() !== false) {
    // update successful
} else {
    // update failed
}

Parameters

Parameter	Type	Description
`$runValidation`	`bool`	Whether to perform validation (calling `validate()`) before saving the record. Defaults to `true`. If the validation fails, the record will not be saved to the database and this method will return `false`.
`$attributeNames`	`array\|null`	List of attributes that need to be saved. Defaults to `null`, meaning all attributes that are loaded from DB will be saved.

Returns

int|false: The number of rows affected, or false if validation fails or beforeSave() stops the updating process.

Throws

StaleObjectException: if optimistic locking is enabled and the data being updated is outdated.
Throwable: in case update failed.

updateAll()

public static function updateAll(array $attributes, string|array $condition = '', array $params = []): int

Updates the whole table using the provided attribute values and conditions.

For example, to change the status to be 1 for all customers whose status is 2:

Customer::updateAll(['status' => 1], 'status = 2');

Warning: If you do not specify any condition, this method will update all rows in the table.

Note that this method will not trigger any events. If you need EVENT_BEFORE_UPDATE or EVENT_AFTER_UPDATE to be triggered, you need to find the models first and then call update() on each of them. For example an equivalent of the example above would be:

$models = Customer::find()->where('status = 2')->all();
foreach ($models as $model) {
    $model->status = 1;
    $model->update(false); // skipping validation as no user input is involved
}

For a large set of models you might consider using ActiveQuery::each() to keep memory usage within limits.

Parameters

Parameter	Type	Description
`$attributes`	`array`	Attribute values (name-value pairs) to be saved into the table
`$condition`	`string\|array`	The conditions that will be put in the WHERE part of the UPDATE SQL. Please refer to `Query::where()` on how to specify this parameter.
`$params`	`array`	The parameters (name => value) to be bound to the query.

Returns

int: The number of rows updated

updateAllCounters()

public static function updateAllCounters(array $counters, string|array $condition = '', array $params = []): int

Updates the whole table using the provided counter changes and conditions.

For example, to increment all customers’ age by 1,

Customer::updateAllCounters(['age' => 1]);

Note that this method will not trigger any events.

Parameters

Parameter	Type	Description
`$counters`	`array`	The counters to be updated (attribute name => increment value). Use negative values if you want to decrement the counters.
`$condition`	`string\|array`	The conditions that will be put in the WHERE part of the UPDATE SQL. Please refer to `Query::where()` on how to specify this parameter.
`$params`	`array`	The parameters (name => value) to be bound to the query. Do not name the parameters as `:bp0`, `:bp1`, etc., because they are used internally by this method.

Returns

int: The number of rows updated

deleteInternal()

protected function deleteInternal(): int|false

Deletes an ActiveRecord without considering transaction.

Returns

Throws

StaleObjectException

insertInternal()

protected function insertInternal(array|null $attributes = null): bool

Inserts an ActiveRecord into DB without considering transaction.

Parameters

Parameter	Type	Description
`$attributes`	`array\|null`	List of attributes that need to be saved. Defaults to `null`, meaning all attributes that are loaded from DB will be saved.

Returns

bool: Whether the record is inserted successfully.