How to Program With Yii2: Timestamp Behavior

Final product image
What You'll Be Creating

If you're asking, "What's Yii?" check out my earlier tutorial: Introduction to the Yii Framework, which reviews the benefits of Yii and includes an overview of what's new in Yii 2.0, released in October 2014.

In this Programming With Yii2 series, I'm guiding readers in use of the newly upgraded Yii2 Framework for PHP. In this tutorial, we'll explore Timestamp Behaviors, which reduce the amount of code you need to write with each new model for the common operation of creating timestamps for inserts and updates. We'll also dive into the Yii2 source code, examining how a behavior is implemented.

For the examples in this tutorial, we'll continue to imagine we're building a framework for posting simple status updates, e.g. our own mini-Twitter.

Just a reminder, I do participate in the comment threads below. I'm especially interested if you have different approaches, additional ideas, or want to suggest topics for future tutorials.

What Is a Behavior?

Yii2 Behaviors are essentially mixins. Wikipedia describes mixins as "a class that contains a combination of methods from other classes. How such a combination is done depends on the language, but it is not by inheritance."

Yii describes them this way:

Attaching a behavior to a component "injects" the behavior's methods and properties into the component, making those methods and properties accessible as if they were defined in the component class itself.

Yii2 offers several built-in behaviors, most of which we'll be documenting, including sluggable, blameable, and timestamp. Behaviors are an easy way to reuse common code across many of your data models without having to repeat the code in many places. Injecting a behavior into a model can often be done with just two lines of code. As the number of models in your application increases, behaviors become more and more useful.

What Is the Timestamp Behavior?

The Timestamp Behavior makes it easy for us to implement the frequently needed task of assigning the current date and time to inserts and updates in an ActiveRecord model, automatically setting the properties for created_at and updated_at.

Earlier in this series, we implemented timestamp behavior manually. Whenever Status models were posted by the user submitting a form, we assigned the current Unix timestamp to both fields:

Implementing the Timestamp behavior will do this automatically for us and can be easily added to all of the ActiveRecord models in a web application.

Implementing the Timestamp Behavior in the Status Model

Almost every model I create in Yii has a created_at and updated_at field. It's good practice. Thus, the Timestamp behavior is useful in nearly every model.

Adding the Timestamp Behavior to the Status Model

In models/Status.php we add the TimestampBehavior after Sluggable and Blameable:

We also have to include the ActiveRecord class at the top of our model (I always forget this part):

Then, we remove the required rule for created_at and updated_at in the model rules:

Like this:

This allows the validation to succeed and continue on to the behaviors.

We also need to remove the StatusController's created_at and updated_at assignments in the create action:

Once all these changes are complete, we can write a new Status post:

Creating a Status entry now that weve attached the Timestamp Behavior

And, the resulting view shows the created_at and updated_at settings made by the Timestamp behavior.

View of the results of Timestamp Behavior on our Status model

The Touch Method

The Timestamp behavior also provides a method named touch() that allows you to assign the current timestamp to the specified attribute(s) and save them to the database.

For example, if you have a background cron job that does some processing on the status table, you might have a last_processed_at timestamp which you attach the behavior to. Whenever the cron job runs, you would touch that field:

The Timestamp Behavior Source Code

Since Yii2 now supports the PSR-4 naming conventions, it's easier to dive right into the framework code to see how it works. Let's take a look at the TimestampBehavior code to understand how it's implemented.

The code is linked to GitHub from the documentation page:

The default attributes are defined here, and they can be customized in our models:

On initialization, the behavior defines which events trigger timestamp updates to the specified attributes:

You can read more about Yii2 ActiveRecord Events here.

The getValue method returns the current timestamp for the attribute if it's undefined:

By default, TimestampBehavior will fill the created_at and updated_at attributes with the current timestamp when the associated object is being inserted. It will fill the updated_at attribute with the timestamp when the object is being updated. If there's no custom function assigned, then it uses the PHP time() function, which returns the current Unix timestamp.

It also implements the touch method for the defined attributes:

Hopefully, this gives you an idea of how to implement your own model behavior. If you do create something new, post a link to the code in the comments so others can check it out.

What's Next?

I hope you've enjoyed learning about Yii2 Timestamp behaviors and exploring the Yii2 source code.

Watch for upcoming tutorials in my Programming With Yii2 series as I continue diving into different aspects of the framework. You may also want to check out my Building Your Startup With PHP series, which is using Yii2's advanced template as I build a real world application.

I welcome feature and topic requests. You can post them in the comments below or email me at my Lookahead Consulting website.

If you'd like to know when the next Yii2 tutorial arrives, follow me @reifman on Twitter or check my instructor page. My instructor page will include all the articles from this series as soon as they are published. 

Related Links

Tags:

Comments

Related Articles