Yii 2.0 ActiveRecord Explained

Share this article

The ActiveRecord class in Yii provides an object oriented interface (aka ORM) for accessing database stored data. Similar structures can be found in most modern frameworks like Laravel, CodeIgniter, Smyfony and Ruby. Today, we’ll go over the implementation in Yii 2.0 and I’ll show you some of the more advanced features of it.

Database and networking concept

Model class intro

The Yii ActiveRecord is an advanced version of the base yii\base\Modelwhich is the foundation of the Model-View-Controller architecture. I’ll quickly explain the most important functionality that ActiveRecord inherits from the Model class:


The business data is held in attributes. These are publicly available properties of the model instance.
All the attributes can conveniently be assigned massively by assigning any array to the attributes property of a model. This works because the base Component class (the base of almost everything in Yii 2.0) implements the __set() method which in turn calls the setAttributes() method in the Model class. The same goes for retrieving; all attributes can be retrieved by getting the attributes property. Again, built upon the Component class which implements __get() which calls the getAttributes() in the Model class.
Models also supply attribute labels which are used for display purposes which makes using them in forms on pages easier.


Data passed in the model from user input should be checked to see that they satisfy your business logic. This is done by specifying rules() which would normally hold one or more validators for each attribute.
By default, only attributes which are considered ‘safe’, meaning they have a validation rule defined for them, can be assigned massively.


The scenarios allow you to to define different ‘scenarios’ in which you’ll use a model allowing you to change the way it validates and handles its data. The example in the documentation describes how you can use it in a FormModel (which also extends the Model class) by specifying different validation rules for both user registration and login simply by defining two different scenarios in one Model.

Creating an ActiveRecord model

An ActiveRecord instance represents a row in a database table, therefore we need a database. In this article I’ll use the database design in the picture below as as an example. It’s a simple structure for blog articles. Authors can have multiple articles which can have multiple tags. The articles are related through an N:M relation to the tags because we want to be able to show related articles based on the tags. The ‘articles’ table will get our focus because it has the most interesting set of relations.


I’ve used the Gii extension to generate the model based on the table and it’s relations. Here’s what is generated for the articles table from the database structure just by clicking a few buttons:

namespace app\models;

use Yii;

 * This is the model class for table "articles".
 * @property integer $ID
 * @property integer $AuthorsID
 * @property string $LastEdited
 * @property string $Published
 * @property string $Title
 * @property string $Description
 * @property string $Content
 * @property string $Format
 * @property Authors $authors
 * @property Articlestags[] $articlestags
class Articles extends \yii\db\ActiveRecord
     * @inheritdoc
    public static function tableName()
        return 'articles';

     * @inheritdoc
    public function rules()
        return [
            [['AuthorsID'], 'integer'],
            [['LastEdited', 'Title', 'Description', 'Content'], 'required'],
            [['LastEdited', 'Published'], 'safe'],
            [['Description', 'Content'], 'string'],
            [['Format'], 'in', 'range' => ['MD', 'HTML']],
            [['Title'], 'string', 'max' => 250],

     * @inheritdoc
    public function attributeLabels()
        return [
            'ID' => Yii::t('app', 'ID'),
            'AuthorsID' => Yii::t('app', 'Authors ID'),
            'LastEdited' => Yii::t('app', 'Last Edited'),
            'Published' => Yii::t('app', 'Published'),
            'Title' => Yii::t('app', 'Title'),
            'Description' => Yii::t('app', 'Description'),
            'Content' => Yii::t('app', 'Content'),
            'Format' => Yii::t('app', 'Format'),

     * @return \yii\db\ActiveQuery
    public function getAuthors()
        return $this->hasOne(Authors::className(), ['ID' => 'AuthorsID']);

     * @return \yii\db\ActiveQuery
    public function getArticlestags()
        return $this->hasMany(Articlestags::className(), ['ArticlesID' => 'ID']);

The properties listed in the comment before the class definition show which attributes are available on every instance. It is good to notice that because of the relation definitions (defined in this class), you also get properties for the related data; one Authors $authors and multiple Articlestags[] $articlestags.

The tableName() function defines which database table is related to this Model. This allows a decoupling of the class name from the actual table name.

The rules() define the validation rules for the model. There are no scenarios defined so there is only one set of rules. It’s quite readable; showing which fields are required and which require an integer or string. There are quite a few core validators available which suit most people’s needs.

The attributeLabels() function supplies labels to be shown for each attribute should it be used in views. I chose to make mine i18n compatible from Gii which added all the calls to Yii::t(). This basically means that translation of the labels, which end up in the rendered pages, will be much easier later on should we need it.
Finally, the getAuthors() and getArticlestags() functions define the relation of this table to other tables.

Note: I was quite surprised to find the ‘Format’ attribute was missing completely from the properties, validators and labels. Turns out that Gii doesn’t support ENUMs. Besides MySQL (and its forks) only PostgreSQL supports it and therefore it wasn’t implemented. I had to add them manually.

Completing the model

You can probably see that the generated Articles class only has relations defined for the foreign key tables. The N:M relation from Articles to Tags won’t be generated automatically so we’ll have to define that by hand.

The relations are all returned as instances of yii\db\ActiveQuery. To define a relation between Articles and Tags we’ll need to use the ArticlesTags as a junction table. In ActiveQuery, this is done by defining a via table. ActiveQuery has two methods you can use for this:

  • via() allows you to use an already defined relation in the class to define the relation.
  • viaTable() alternatively allows you to define a table to use for a relation.

The via() method allows you to use an already defined relation as via table. In our example, however, the ArticlesTags table holds no information that we care for so I’ll use the viaTable() method.

 * @return \yii\db\ActiveQuery
public function getTags()
    return $this->hasMany(Tags::className(), ['ID' => 'TagsID'])
			    ->viaTable(Articlestags::tableName(), ['ArticlesID' => 'ID']);

Now that we’ve defined all the relations, we can start using the model.

Using the model

I’ll quickly create some database content by hand.

$phpTag = new \app\models\Tags();		//Create a new tag 'PHP'
$phpTag->Tag = 'PHP';

$yiiTag = new \app\models\Tags();		//Create a new tag 'Yii'
$yiiTag->Tag = 'Yii';

$author = new \app\models\Authors();	//Create a new author
$author->Name = 'Arno Slatius';

$article = new \app\models\Articles();	//Create an article and link it to the author
$article->AuthorsID = $author->ID;
$article->Title = 'Yii 2.0 ActiveRecord';
$article->Description = 'Arno Slatius dives into the Yii ActiveRecord class';
$article->Content = '... the article ...';
$article->LastEdited = new \yii\db\Expression('NOW()');

$tagArticle = new \app\models\ArticlesTags();	//Link the 'PHP' tag to the article
$tagArticle->ArticlesID = $article->ID;
$tagArticle->TagsID = $phpTag->ID;

$tagArticle = new \app\models\ArticlesTags();	//Link the 'Yii' tag to the article
$tagArticle->ArticlesID = $article->ID;
$tagArticle->TagsID = $yiiTag->ID;

It should be noted that the code above has some assumptions which I’ll explain;

  • The result of save(), a boolean, isn’t evaluated. This isn’t wise normally, because Yii will actually call validate() on the class before actually saving it in the database. The database INSERT won’t be executed should any of the validation rules fail.
  • You might notice that the ID attributes of the various instances are used while they are not set. This can be done safely because the save() call will INSERT the data and get assigned the primary key back from the database and make the ID property value valid.
  • The $article->LastEdited is a DateTime value in the database. I want to insert the current datetime by calling the NOW() SQL function on it. You can do this by using the Expression class which allows the usage of various SQL expressions with ActiveRecord instances.

You can then retrieve the article again from the database;

//Look up our latest article
$article = \app\models\Articles::findOne(['Title'=>'Yii 2.0 ActiveRecord']);

//Show the title
echo $article->Title;

//The related author, there is none or one because of the hasOne relation
if (isset($article->authors)) {
    echo $article->authors->name

//The related tags, always an array because of the hasMany relations
if (isset($article->tags)) {
    foreach($article->tags as $tag) {
        echo $tag->Tag;

New and advanced usages

The Yii ActiveRecord, as I’ve described it so far, is straight forward. Let’s make it interesting and go into the new and changed functionality in Yii 2.0 a bit more.

Dirty attributes

Yii 2.0 introduced the ability to detect changed attributes. For ActiveRecord, these are called dirty attributes because they require a database update. This ability now by default allows you to see which attributes changed in a model and to act on that. When, for example, you’ve massively assigned all the attributes from a form POST you might want to get only the changed attributes:

//Get a attribute => value array for all changed values
$changedAttributes = $model->getDirtyAttributes();

//Boolean whether the specific attribute changed

//Force an attribute to be marked as dirty to make sure the record is 
// updated in the database

//Get on or all old attributes


The ActiveRecord, being extended from Model, now implements the \yii\base\Arrayable trait with it’s toArray() method. This allows you to convert the model with attributes to an array quickly. It also allows for some nice additions.

Normally a call to toArray() would call the fields() function and convert those to an array. The optional expand parameter of toArray() will additionally call extraFields() which dictates which fields will also be included.

These two fields methods are implemented by BaseActiveRecord and you can implement them in your own model to customize the output of the toArray() call.

I’d like, in my example, to have the extended array contain all the tags of an article available as a comma separated string in my array output as well;

public function extraFields()
	return [
		'tags'=>function() {
			if (isset($this->tags)) {
				$tags = [];
				foreach($this->tags as $articletag) {
					$tags[] = $articletag->Tag;
				return implode(', ', $tags);

And then get an array of all the fields and this extra field from the model;

//Returns all the attributes and the extra tags field
$article->toArray([], ['tags']);


Yii 1.1 already implemented various events on the CActiveRecord and they’re still there in Yii 2.0. The ActiveRecord life cycle in the Yii 2.0 guide shows very nicely how all these events are fired when using an ActiveRecord. All the events are fired surrounding the normal actions of your ActiveRecord instance. The naming of the events is quite obvious so you should be able to figure out when they are fired; afterFind(), beforeValidate(), afterValidate(), beforeSave(), afterSave(), beforeDelete(), afterDelete().

In my example, the LastEdited attribute is a nice way to demonstrate the use of an event. I want to make sure LastEdited always reflects the last time the article was edited. I could set this on two events; beforeSave() and beforeValidate(). My model rules define LastEdited as a required attribute so we need to use the beforeValidate() event to make sure it is also set on new instances of the model;

public function beforeValidate($insert)
    if (parent::beforeValidate($insert)) {
		$this->LastEdited = new \yii\db\Expression('NOW()');
        return true;
    return false;

Note that with all of these events, you should call the parent event handler. Returning false (or nothing!) from a before event in these functions stops the action from happening.


Behavior can be used to enhance the functionality of an existing component without modifying its code. It can also respond to the events in the component that it was attached to. They behave similar to the traits introduced in PHP 5.4.
Yii 2.0 comes with a number of available behaviors;

  • yii\behaviors\AttributeBehavior allows you to specify attributes which need to be updated on a specified event. You can, for example, set an attribute to a value based on an unnamed function on a BEFORE_INSERT event.

  • yii\behaviors\BlameableBehavior does what you’d expect; blame someone. You can set two attributes; a createdByAttribute and updatedByAttribute which will be set to the current user ID when the object is created or updated.

  • yii\behaviors\SluggableBehavior allows you to automatically create a URL slug based on one of the attributes to another attribute in the model.

  • yii\behaviors\TimestampBehavior will allow you to automatically create and update the time stamp in a createdAtAttribute and updatedAtAttribute in your model.

You can probably see that these have some practical applications in my example as well. Assuming that the person currently logged in to the application is the actual author of an article, I could use the BlameableBehavior to make them the author and I can also use the TimestampBehaviour to make sure the LastEdited attribute stays up to date. This would replace my previous implementation of the beforeValidate() event in my model. This is how I attached the behaviors to my Articles model:

public function behaviors()
    return [
            'class' => \yii\behaviors\BlameableBehavior::className(),
            'createdByAttribute' => 'AuthorID',
            'updatedByAttribute' => 'AuthorID',
            'class' => \yii\behaviors\TimestampBehavior::className(),
            'createdAtAttribute' => false,    //or 'LastEdited'
            'updatedAtAttribute' => 'LastEdited',
            'value' => new \yii\db\Expression\Expression('NOW()'),

I assume here of course that the creator and the editor of the article is the same person. Since I don’t have a created timestamp field, I chose not to use it by setting the createdAtAttribute to false. I could of course also set this to 'LastEdited'.

Transactional operations

The last feature I want to touch is the possibility to automatically force the usage of transactions in a model. With the enforcement of foreign keys also comes the possibility for database queries to fail because of that. This can be handled more gracefully by wrapping them in a transaction. Yii allows you to specify operations that should be transactional by implementing a transactions() function in your model that specifies which operations in which scenarios should be enclosed in a transaction. Note that you should return a rule for the SCENARIO_DEFAULT if you want this to be done by default on operations.

public function transactions()
	return [
		//always enclose updates in a transaction
	    \yii\base\Model::SCENARIO_DEFAULT => self::OP_UPDATE,	    
	    //include all operations in a transaction for the 'editor' scenario
	    'editor' => self::OP_INSERT | self::OP_UPDATE | self::OP_DELETE,


The Yii ActiveRecord class already made ORM handling very simple, Yii 2.0 builds upon this great base and extends it even further. The flexibility is huge due to the possibility to define different usage scenarios, attach behaviors and use events.

These are some features in the ActiveRecord that I’ve found most useful over time and most welcome with the arrival of Yii 2.0. Did you miss a feature of ActiveRecord, or perhaps feel that Yii ActiveRecord is missing a great feature from another framework? Please let us know in the comments!

Frequently Asked Questions (FAQs) about Yii 2.0 ActiveRecord

What is the difference between Yii 2.0 ActiveRecord and other ORM tools?

Yii 2.0 ActiveRecord is an Object-Relational Mapping (ORM) tool that provides an interface for accessing data in a database. Unlike other ORM tools, Yii 2.0 ActiveRecord is designed to be simple and easy to use, with a focus on performance. It supports a wide range of database systems, including MySQL, PostgreSQL, SQLite, and more. It also provides a rich set of features, such as lazy loading, eager loading, transaction, and complex query building.

How do I use Yii 2.0 ActiveRecord to perform CRUD operations?

Yii 2.0 ActiveRecord provides a simple and intuitive API for performing CRUD (Create, Read, Update, Delete) operations. To create a new record, you can create a new instance of the ActiveRecord class, set its attributes, and call the save() method. To read a record, you can use the find() method. To update a record, you can find it, change its attributes, and call the save() method again. To delete a record, you can call the delete() method on it.

Can I use Yii 2.0 ActiveRecord with non-relational databases?

Yes, Yii 2.0 ActiveRecord supports both relational and non-relational databases. For non-relational databases, Yii provides a different set of ActiveRecord classes. For example, for MongoDB, you can use yii\mongodb\ActiveRecord.

How do I handle transactions with Yii 2.0 ActiveRecord?

Yii 2.0 ActiveRecord provides a simple API for handling transactions. You can start a transaction by calling the beginTransaction() method on a database connection. Then, you can perform your database operations. If everything goes well, you can commit the transaction by calling the commit() method. If something goes wrong, you can roll back the transaction by calling the rollback() method.

How do I build complex queries with Yii 2.0 ActiveRecord?

Yii 2.0 ActiveRecord provides a powerful query builder that allows you to build complex queries in an intuitive and easy-to-read way. You can use methods like select(), from(), where(), orderBy(), and limit() to build your query. You can also use the andWhere() and orWhere() methods to add additional conditions to your query.

How do I validate data with Yii 2.0 ActiveRecord?

Yii 2.0 ActiveRecord provides a robust validation system. You can define validation rules for your ActiveRecord classes, and Yii will automatically validate your data when you call the save() method. If the validation fails, the save() method will return false, and you can get the validation errors by calling the getErrors() method.

How do I handle relations with Yii 2.0 ActiveRecord?

Yii 2.0 ActiveRecord provides a simple and intuitive way to handle relations between tables. You can define relations by implementing methods in your ActiveRecord classes that return the result of the hasOne() or hasMany() method.

How do I use Yii 2.0 ActiveRecord to perform batch operations?

Yii 2.0 ActiveRecord provides a method called batch() that allows you to perform batch operations. This is particularly useful when you need to process a large amount of data that may not fit into memory.

How do I use Yii 2.0 ActiveRecord to perform aggregate operations?

Yii 2.0 ActiveRecord provides methods like sum(), average(), max(), min(), and count() that allow you to perform aggregate operations.

How do I customize the behavior of Yii 2.0 ActiveRecord?

Yii 2.0 ActiveRecord is highly customizable. You can override its methods to change its behavior, or you can attach event handlers to it to react to certain events. For example, you can override the beforeSave() method to perform some custom processing before a record is saved.

Arno SlatiusArno Slatius
View Author

Arno Slatius is a web developer from the Netherlands. He has a background in electronics and embedded systems and started web development over a decade ago, He works with Yii professionally and loves digging into new things. Arno loves clean, commented and simple code. When he's not coding, he spends most of his time with his family or flying his model helies, planes and quads.

Share this article
Read Next
Get the freshest news and resources for developers, designers and digital creators in your inbox each week