EZP-28956: Expose lazy loaded Location->getContent() on API for bette…

…r DX (#2328)

* Add SPI ContentHandler::loadContentList() for bulk loading content

Note on cache:
- By design here version is skipped, as use case for loading lots of content is in current version.
- So one downside for cache here is that it won't reuse cache from load() method, causing cache to be duplcated in current design.

Possible ways to remedy:
- Force having to provide versions also on loadContentList() making it less efficient for some use cases (Page builder scenarios for instance)
- Allow $version on load() to be false, or expose a loadContentInCurrentVersion() kind of method, either way adapt usage for this so cache will be shared.

* Add Location->getContent() using lazy properties

* [Integration] Add coverage for Location->getContent()

* Change SearchService->findContent() to bulk load content

Now that we have method to load several at once, take advantage in findContent().

* [ContentViewBuilder] Take advantage of Location->getContent() to avoid duplicate loading

* Refactor for LoadStruct usage in SPI

* fix review comments

* Add internal ContentInfo proxy for ContentProxy usage

* Make Trash item contain Content as well (as it extends Location)

* Fix review comments

* Don't use unset() on properties when they are no longer needed

* Fix phpdoc on Abstract(Cache)Handler

Persistence/Content/Handler.php

@@ -67,6 +67,21 @@ public function createDraftFromVersion($contentId, $srcVersion, $userId);
      */
     public function load($id, $version, array $translations = null);
 
+    /**
+     * Return list of unique Content, with content id as key.
+     *
+     * Missing items (NotFound) will be missing from the array and not cause an exception, it's up
+     * to calling logic to determine if this should cause exception or not.
+     *
+     * NOTE: Even if LoadStruct technically allows to load several versions of same content, this method does not allow
+     * this by design as content is returned as Map with key being content id.
+     *
+     * @param \eZ\Publish\SPI\Persistence\Content\LoadStruct[] $contentLoadStructs
+     *
+     * @return \eZ\Publish\SPI\Persistence\Content[<int>]
+     */
+    public function loadContentList(array $contentLoadStructs): array;
+
     /**
      * Returns the metadata object for a content identified by $contentId.
      *

Persistence/Content/LoadStruct.php

@@ -0,0 +1,48 @@
+<?php
+
+/**
+ * File containing the Content LoadStruct struct.
+ *
+ * @copyright Copyright (C) eZ Systems AS. All rights reserved.
+ * @license For full copyright and license information view LICENSE file distributed with this source code.
+ */
+namespace eZ\Publish\SPI\Persistence\Content;
+
+use eZ\Publish\SPI\Persistence\ValueObject;
+
+/**
+ * Load struct for mass loading content or specific content versions.
+ *
+ * Design implies features such as always available and language logic needs to be done in API layer, so SPI gets
+ * a specifc query to deal with for the lookup that can be safely cached.
+ */
+class LoadStruct extends ValueObject
+{
+    /**
+     * Content's unique ID.
+     *
+     * @var mixed
+     */
+    public $id;
+
+    /**
+     * Version number for version we would like to load, current version will be assumed if null.
+     *
+     * TIP: On usage with content load methods, if you need to be 100% sure current version is loaded, then let this
+     * stay as null. Otherwise there is a corner case possibility someone might have published a new version in-between
+     * loading content info to get version number and loading content, which can result in strange reports about
+     * permission errors as most users don't have version read access.
+     *
+     * @var int|null
+     */
+    public $versionNo;
+
+    /**
+     * List of language code on translated properties of returned object.
+     *
+     * *Should* in the future be treated as prioritized languages by storage engine, returning only the first language matched.
+     *
+     * @var string[]
+     */
+    public $languages = [];
+}