`yii\db\BaseActiveRecord` now triggers event EVENT_AFTER_REFRESH` after a record is refreshed

fixes #9604
close #10867

docs/guide/db-active-record.md

@@ -570,6 +570,11 @@ life cycle will happen:
 > - [[yii\db\ActiveRecord::updateCounters()]] 
 > - [[yii\db\ActiveRecord::updateAllCounters()]] 
 
+### Refreshing Data Life Cycle <span id="refreshing-data-life-cycle"></span>
+
+When calling [[yii\db\ActiveRecord::refresh()|refresh()]] to refresh an Active Record instance, the
+[[yii\db\ActiveRecord::EVENT_AFTER_REFRESH|EVENT_AFTER_REFRESH]] event is triggered if refresh is successful and the method returns `true`.
+
 
 ## Working with Transactions <span id="transactional-operations"></span>
 

framework/CHANGELOG.md

@@ -48,6 +48,7 @@ Yii Framework 2 Change Log
 - Enh #8779: Automatically set enctype form option when using file input field (pana1990, arogachev)
 - Enh #9340: Adds `after()` and `first()` column schema builder modifiers (df2)
 - Enh #9562: Adds `char` datatype to framework (df2)
+- Enh #9604: `yii\db\BaseActiveRecord` now triggers event `EVENT_AFTER_REFRESH` after a record is refreshed (raoul2000)
 - Enh #9893: `yii.js` handleAction enhanced to support for data-form attribute, so links can trigger specific forms (SamMousa)
 - Enh #10451: Check of existence of `$_SERVER` in `\yii\web\Request` before using it (quantum13)
 - Enh #10487: `yii\helpers\BaseArrayHelper::index()` got a third parameter `$groupBy` to group the input array by the key in one or more dimensions (quantum13, silverfire, samdark)

framework/db/BaseActiveRecord.php

@@ -77,6 +77,11 @@ abstract class BaseActiveRecord extends Model implements ActiveRecordInterface
      * @event Event an event that is triggered after a record is deleted.
      */
     const EVENT_AFTER_DELETE = 'afterDelete';
+    /**
+     * @event Event an event that is triggered after a record is refreshed.
+     * @since 2.0.8
+     */
+    const EVENT_AFTER_REFRESH = 'afterRefresh';
 
     /**
      * @var array attribute values indexed by attribute names
@@ -951,6 +956,10 @@ abstract class BaseActiveRecord extends Model implements ActiveRecordInterface
 
     /**
      * 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.
+     *
      * @return boolean 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.
      */
@@ -966,11 +975,24 @@ abstract class BaseActiveRecord extends Model implements ActiveRecordInterface
         }
         $this->_oldAttributes = $this->_attributes;
         $this->_related = [];
+        $this->afterRefresh();
 
         return true;
     }
 
     /**
+     * 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.
+     * @since 2.0.8
+     */
+    public function afterRefresh()
+    {
+        $this->trigger(self::EVENT_AFTER_REFRESH);
+    }
+
+    /**
      * 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 [[isNewRecord|is new]] they are also considered not equal.

tests/framework/ar/ActiveRecordTestTrait.php

@@ -1126,6 +1126,27 @@ trait ActiveRecordTestTrait
         Event::off(BaseActiveRecord::className(), BaseActiveRecord::EVENT_AFTER_FIND);
     }
 
+    public function testAfterRefresh()
+    {
+        /* @var $customerClass \yii\db\ActiveRecordInterface */
+        $customerClass = $this->getCustomerClass();
+        /* @var $this TestCase|ActiveRecordTestTrait */
+
+        $afterRefreshCalls = [];
+        Event::on(BaseActiveRecord::className(), BaseActiveRecord::EVENT_AFTER_REFRESH, function ($event) use (&$afterRefreshCalls) {
+    	    /* @var $ar BaseActiveRecord */
+    	    $ar = $event->sender;
+    	    $afterRefreshCalls[] = [get_class($ar), $ar->getIsNewRecord(), $ar->getPrimaryKey(), $ar->isRelationPopulated('orders')];
+        });
+
+        $customer = $customerClass::findOne(1);
+        $this->assertNotNull($customer);
+        $customer->refresh();
+        $this->assertEquals([[$customerClass, false, 1, false]], $afterRefreshCalls);
+        $afterRefreshCalls = [];
+        Event::off(BaseActiveRecord::className(), BaseActiveRecord::EVENT_AFTER_REFRESH);
+    }
+
     public function testFindEmptyInCondition()
     {
         /* @var $customerClass \yii\db\ActiveRecordInterface */