Merge pull request #9755 from craftcms/feature/dev-65-integrate-collections-library

Collections

Author: brandonkelly

CHANGELOG.md

@@ -22,6 +22,7 @@
 - Added `craft\db\Migration::dropForeignKeyIfExists()`.
 - Added `craft\db\Migration::dropIndexIfExists()`.
 - Added `craft\db\Migration::renameTable()`.
+- Added `craft\db\Query::collect()`, which returns the query results as an `Illuminate\Support\Collection` object rather than an array. ([#8513](https://github.com/craftcms/cms/discussions/8513))
 - Added `craft\db\Table::ASSETINDEXINGSESSIONS`.
 - Added `craft\elements\Asset::setFilename()`.
 - Added `craft\elements\User::$active`.
@@ -59,6 +60,7 @@
 - Added `craft\services\Users::ensureUserByEmail()`, which will return a user for the given email, creating one if it didn’t exist yet.
 - Added `craft\services\Users::EVENT_AFTER_DEACTIVATE_USER`.
 - Added `craft\services\Users::EVENT_BEFORE_DEACTIVATE_USER`.
+- Added the Illuminate Collections package. ([#8475](https://github.com/craftcms/cms/discussions/8475))
 
 ### Changed
 - Craft now requires PHP 7.4 or later.
@@ -134,6 +136,7 @@
 - Widgets’ `getTitle()` methods can now have a `?string` return type declaration.
 - Widgets’ `icon()` methods must now have a `?string` return type declaration.
 - Widgets’ `maxColspan()` methods must now have an `?int` return type declaration.
+- `craft\base\ElementInterface::getEagerLoadedElements()` now returns an `Illuminate\Support\Collection` object instead of an array. ([#8513](https://github.com/craftcms/cms/discussions/8513))
 - `craft\base\MemoizableArray` no longer extends `ArrayObject`, and now implements `IteratorAggregate` and `Countable` directly.
 - `craft\base\Model::datetimeAttributes()` is now called from the constructor, instead of the `init()` method.
 - `craft\base\Model::setAttributes()` now normalizes date attributes into `DateTime` objects.

composer.json

@@ -41,6 +41,7 @@
     "elvanto/litemoji": "^3.0.1",
     "enshrined/svg-sanitize": "~0.14.0",
     "guzzlehttp/guzzle": "^7.2.0",
+    "illuminate/collections": "^8.55",
     "league/oauth2-client": "^2.6.0",
     "mikehaertl/php-shellcommand": "^1.6.3",
     "pixelandtonic/imagine": "~1.2.4.1",

composer.lock

@@ -59,6 +59,7 @@
 use craft\validators\StringValidator;
 use craft\web\UploadedFile;
 use DateTime;
+use Illuminate\Support\Collection;
 use Twig\Markup;
 use yii\base\ErrorHandler;
 use yii\base\Event;
@@ -1546,7 +1547,7 @@ private static function _indexOrderByColumns(string $sourceKey, array $viewState
     private $_nextSibling;
 
     /**
-     * @var ElementInterface[][]
+     * @var Collection[]
      */
     private array $_eagerLoadedElements = [];
 
@@ -3394,7 +3395,7 @@ public function hasEagerLoadedElements(string $handle): bool
     /**
      * @inheritdoc
      */
-    public function getEagerLoadedElements(string $handle): ?array
+    public function getEagerLoadedElements(string $handle): ?Collection
     {
         if (!isset($this->_eagerLoadedElements[$handle])) {
             return null;
@@ -3438,7 +3439,7 @@ public function setEagerLoadedElements(string $handle, array $elements): void
                 $this->trigger(self::EVENT_SET_EAGER_LOADED_ELEMENTS, $event);
                 if (!$event->handled) {
                     // No takers. Just store it in the internal array then.
-                    $this->_eagerLoadedElements[$handle] = $elements;
+                    $this->_eagerLoadedElements[$handle] = new Collection($elements);
                 }
         }
     }

src/base/Element.php

@@ -11,6 +11,7 @@
 use craft\errors\InvalidFieldException;
 use craft\models\FieldLayout;
 use craft\models\Site;
+use Illuminate\Support\Collection;
 use Twig\Markup;
 
 
@@ -1283,9 +1284,9 @@ public function hasEagerLoadedElements(string $handle): bool;
      * Returns the eager-loaded elements for a given handle.
      *
      * @param string $handle The handle of the eager-loaded elements
-     * @return ElementInterface[]|null The eager-loaded elements, or null if they hadn't been eager-loaded
+     * @return Collection|null The eager-loaded elements, or null if they hadn't been eager-loaded
      */
-    public function getEagerLoadedElements(string $handle): ?array;
+    public function getEagerLoadedElements(string $handle): ?Collection;
 
     /**
      * Sets some eager-loaded elements on a given handle.

src/base/ElementInterface.php

@@ -10,6 +10,7 @@
 use craft\base\ClonefixTrait;
 use craft\events\DefineBehaviorsEvent;
 use craft\helpers\ArrayHelper;
+use Illuminate\Support\Collection;
 use yii\base\Exception;
 use yii\base\Model;
 use yii\db\Connection as YiiConnection;
@@ -156,6 +157,19 @@ public function all($db = null): array
         }
     }
 
+    /**
+     * Executes the query and returns all results as a collection.
+     *
+     * @param YiiConnection|null $db The database connection used to generate the SQL statement.
+     * If this parameter is not given, the `db` application component will be used.
+     * @return Collection A collection of the resulting elements.
+     * @since 4.0.0
+     */
+    public function collect(?YiiConnection $db = null): Collection
+    {
+        return new Collection($this->all($db));
+    }
+
     /**
      * @inheritdoc
      * @return array|Model|null first row of the query result array, or `null` if there are no query results.

src/db/Query.php

@@ -22,6 +22,7 @@
 use craft\models\MatrixBlockType as MatrixBlockTypeModel;
 use craft\records\MatrixBlock as MatrixBlockRecord;
 use craft\web\assets\matrix\MatrixAsset;
+use Illuminate\Support\Collection;
 use yii\base\Exception;
 use yii\base\InvalidConfigException;
 
@@ -373,7 +374,7 @@ public function hasEagerLoadedElements(string $handle): bool
     /**
      * @inheritdoc
      */
-    public function getEagerLoadedElements(string $handle): ?array
+    public function getEagerLoadedElements(string $handle): ?Collection
     {
         // See if we have this stored with a block type-specific handle
         $blockTypeHandle = $this->getType()->handle . ':' . $handle;

src/elements/MatrixBlock.php

@@ -13,6 +13,7 @@
 use craft\db\Query;
 use craft\models\Site;
 use craft\search\SearchQuery;
+use Illuminate\Support\Collection;
 use IteratorAggregate;
 use yii\base\Arrayable;
 use yii\db\Connection;
@@ -1434,6 +1435,16 @@ public function positionedAfter($value): self;
      */
     public function all($db = null): array;
 
+    /**
+     * Executes the query and returns all results as a collection.
+     *
+     * @param Connection|null $db The database connection used to generate the SQL statement.
+     * If this parameter is not given, the `db` application component will be used.
+     * @return Collection A collection of the resulting elements.
+     * @since 4.0.0
+     */
+    public function collect(?Connection $db = null): Collection;
+
     /**
      * Executes the query and returns a single row of result.
      *

src/elements/db/ElementQueryInterface.php

@@ -33,6 +33,7 @@
 use craft\services\Gql as GqlService;
 use craft\web\UploadedFile;
 use GraphQL\Type\Definition\Type;
+use Illuminate\Support\Collection;
 use yii\base\InvalidConfigException;
 
 /**
@@ -486,9 +487,9 @@ public function getContentGqlType()
     /**
      * @inheritdoc
      */
-    protected function tableAttributeHtml(array $elements): string
+    protected function tableAttributeHtml(Collection $elements): string
     {
-        return Cp::elementPreviewHtml($elements, Cp::ELEMENT_SIZE_SMALL, false, true, $this->previewMode === self::PREVIEW_MODE_FULL);
+        return Cp::elementPreviewHtml($elements->all(), Cp::ELEMENT_SIZE_SMALL, false, true, $this->previewMode === self::PREVIEW_MODE_FULL);
     }
 
     // Events