Working with events

Yii's events provide a simple implementation, which allows you to listen and subscribe to various events that occur in your web-application. For example, you may wish to send a notification about a new article to followers each time you publish new material.

Getting ready

1. Create a new application by using the Composer package manager, as described in the official guide at http://www.yiiframework.com/doc-2.0/guide-start-installation.html.
2. Execute the following SQL code on your server to create the article table:

   CREATE TABLE `article` (
   `id` int(11) NOT NULL AUTO_INCREMENT,
   `name` varchar(255) DEFAULT NULL,
   `description` TEXT,
   PRIMARY KEY (`id`)
   ) ENGINE=InnoDB DEFAULT CHARSET=utf8;

3. Generate the Article model using Gii.
4. Run your webserver by ./yii serve command.

How to do it…

1. Add an action test to \controllers\SiteController:

   public function actionTest()
   {
       $article = new Article();
       $article->name = 'Valentine\'s Day\'s coming? Aw crap! I forgot to get a girlfriend again!';
       $article->description = 'Bender is angry at Fry for dating a robot. Stay away from our women.
       You\'ve got metal fever, boy. Metal fever';
   
       // $event is an object of yii\base\Event or a child class
       $article->on(ActiveRecord::EVENT_AFTER_INSERT, function($event) {
           $followers = ['[e-mail]', '[e-mail]', '[e-mail]' ];
           foreach($followers as $follower) {
               Yii::$app->mailer->compose()
                   ->setFrom('[e-mail]')
                   ->setTo($follower)
                   ->setSubject($event->sender->name)
                   ->setTextBody($event->sender->description)
                   ->send();
           }
           echo 'Emails has been sent';
       });
   
       if (!$article->save()) {
           echo VarDumper::dumpAsString($article->getErrors());
       };
   }

2. Update the config/web.php component mailer using the following code.

   'mailer' => [
       'class' => 'yii\swiftmailer\Mailer',
       'useFileTransport' => false,
   ],

3. Run this URL in your browser: http://localhost:8080/index.php?r=site/test.
4. Also check http://www.fakemailgenerator.com/inbox/teleworm.us/john2/.
   

How it works…

We've created an Article model and added a handler for the ActiveRecord::EVENT_AFTER_INSERT event to our Article model. It means that every time we save a new article an event is triggered and our attached handler will be called.

In the real-world, we would like to notify our blog followers each time we publish a new article. In a real application we would have a follower or user table and with different blog sections not only single blog. In this example, after saving our model we notify our followers [e-mail], [e-mail], and [e-mail]. In the last step we just prove that users have received our notifications, particularly john2. You can create your own event with any name. In this example we use a built-in event called ActiveRecord::EVENT_AFTER_INSERT, which is called after each insert to the database.

For example, we can create our own event. Just add a new actionTestNew with the following code:

public function actionTestNew()
{
    $article = new Article();
    $article->name = 'Valentine\'s Day\'s coming? Aw crap! I forgot to get a girlfriend again!';
    $article->description = 'Bender is angry at Fry for dating a robot. Stay away from our women.
    You've got metal fever, boy. Metal fever';

    // $event is an object of yii\base\Event or a child class
    $article->on(Article::EVENT_OUR_CUSTOM_EVENT, function($event) {
        $followers = ['[e-mail]', '[e-mail]', '[e-mail]' ];
        foreach($followers as $follower) {
            Yii::$app->mailer->compose()
                ->setFrom('[e-mail]')
                ->setTo($follower)
                ->setSubject($event->sender->name)
                ->setTextBody($event->sender->description)
                ->send();
        }
        echo 'Emails have been sent';
    });

    if ($article->save()) {
        $article->trigger(Article::EVENT_OUR_CUSTOM_EVENT);
    }
}

Also add the EVENT_OUR_CUSTOM_EVENT constant to models/Article as:

class Article extends \yii\db\ActiveRecord
{
    CONST EVENT_OUR_CUSTOM_EVENT = 'eventOurCustomEvent';
…
}

Run http://localhost:8080/index.php?r=site/test-new.

You should see the same result and all notifications to followers will be sent again. The main difference is we used our custom event name.

After the save, we've triggered our event. Events may be triggered by calling the yii\base\Component::trigger() method. The method requires an event name, and optionally an event object that describes the parameters to be passed to the event handlers.

See also

For more information about events refer to http://www.yiiframework.com/doc-2.0/guide-concept-events.html