EVENT_AFTER_POPULATE_ELEMENTS

Resolves #11262

CHANGELOG-WIP.md

@@ -5,6 +5,8 @@
 - Added a `one()` alias for `first()` to collections. ([#11134](https://github.com/craftcms/cms/discussions/11134))
 - Added `craft\console\controllers\UsersController::$activate`.
 - Added `craft\elements\conditions\ElementCondition::$sourceKey`.
+- Added `craft\elements\db\ElementQuery::EVENT_AFTER_POPULATE_ELEMENTS`. ([#11262](https://github.com/craftcms/cms/discussions/11262))
+- Added `craft\events\PopulateElementsEvent`.
 
 ### Changed
 - Improved pagination UI accessibility. ([#11126](https://github.com/craftcms/cms/pull/11126))

src/elements/db/ElementQuery.php

@@ -23,6 +23,7 @@
 use craft\errors\SiteNotFoundException;
 use craft\events\CancelableEvent;
 use craft\events\PopulateElementEvent;
+use craft\events\PopulateElementsEvent;
 use craft\helpers\ArrayHelper;
 use craft\helpers\Db;
 use craft\helpers\ElementHelper;
@@ -69,6 +70,13 @@ class ElementQuery extends Query implements ElementQueryInterface
      */
     public const EVENT_AFTER_POPULATE_ELEMENT = 'afterPopulateElement';
 
+    /**
+     * @event PopulateElementEvent The event that is triggered after an element is populated.
+     *
+     * If [[PopulateElementEvent::$element]] is replaced by an event handler, the replacement will be returned by [[createElement()]] instead.
+     */
+    public const EVENT_AFTER_POPULATE_ELEMENTS = 'afterPopulateElements';
+
     /**
      * @var string The name of the [[ElementInterface]] class.
      * @phpstan-var class-string<ElementInterface>
@@ -2881,6 +2889,16 @@ private function _createElements(array $rows): array
             if ($this->with) {
                 Craft::$app->getElements()->eagerLoadElements($this->elementType, $elements, $this->with);
             }
+
+            // Fire an 'afterPopulateElements' event
+            if ($this->hasEventHandlers(self::EVENT_AFTER_POPULATE_ELEMENTS)) {
+                $event = new PopulateElementsEvent([
+                    'elements' => $elements,
+                    'rows' => $rows,
+                ]);
+                $this->trigger(self::EVENT_AFTER_POPULATE_ELEMENTS, $event);
+                $elements = $event->elements;
+            }
         }
 
         return $elements;

src/events/PopulateElementsEvent.php

@@ -0,0 +1,30 @@
+<?php
+/**
+ * @link https://craftcms.com/
+ * @copyright Copyright (c) Pixel & Tonic, Inc.
+ * @license https://craftcms.github.io/license/
+ */
+
+namespace craft\events;
+
+use craft\base\ElementInterface;
+use yii\base\Event;
+
+/**
+ * PopulateElementsEvent event class.
+ *
+ * @author Pixel & Tonic, Inc. <[email protected]>
+ * @since 4.1.0
+ */
+class PopulateElementsEvent extends Event
+{
+    /**
+     * @var ElementInterface[] The populated elements
+     */
+    public array $elements;
+
+    /**
+     * @var array[] The element query’s raw result data
+     */
+    public array $rows;
+}