[Documents] Introduce interfaces for editables to replace method_exis…

…ts usages (#10607) * [Documents] Editables - introduce IdRewriterinterface for rewriteIds() - resolves #8908 * [Documents] Editables - introduce EditmodeDataInterface for getDataEditmode() - resolves #8908 * [Documents] Editables - introduce LazyLoadInterface for load() - resolves #8908 * [Documents] Editables - introduce additional interfaces - upgrade notes #8908 * Apply suggestions from code review Co-authored-by: Jacob Dreesen <j.dreesen@neusta.de> * Renamed LazyLoadInterface to LazyLoadingInterface to be consistent in naming * Removed type-hint on \Pimcore\Model\Document\Editable\IdRewriterInterface::rewriteIds() as core-editables implement this interface already and would break custom editables extending core editables implementing this interface Co-authored-by: Jacob Dreesen <j.dreesen@neusta.de> Co-authored-by: Bernhard Rusch <bernhard.rusch@elements.at>
pimcore · Oct 20, 2021 · 065e6da · 065e6da
1 parent 705751d
commit 065e6da
Show file tree

Hide file tree

Showing 20 changed files with 201 additions and 162 deletions.
diff --git a/...evelopment_Documentation/23_Installation_and_Upgrade/09_Upgrade_Notes/README.md b/...evelopment_Documentation/23_Installation_and_Upgrade/09_Upgrade_Notes/README.md
@@ -1,4 +1,6 @@
 # Upgrade Notes
+## 10.3.0
+- [Documents] Introduced additional interfaces for editable methods `getDataEditmode()`, `rewriteIds()` & `load()`. Existing `method_exists` calls are deprecated and will be removed in Pimcore 11.
 
 ## 10.2.0
 - [Maintenance] Maintenance tasks are now handled with Symfony Messenger. The `pimcore:maintenance` command will add the maintenance messages to the bus and runs them afterwards immediately from the queue. However it's recommended to setup independent workers that process the queues, by running `bin/console messenger:consume pimcore_core pimcore_maintenance` (using e.g. Supervisor) and adding `--async` option to the `pimcore:maintenance` command that stops the maintenance command to process the queue directly. Details about setting it up for production environments, please check [Symfony Messenger Component docs](https://symfony.com/doc/current/messenger.html#deploying-to-production). 

diff --git a/lib/Templating/Renderer/EditableRenderer.php b/lib/Templating/Renderer/EditableRenderer.php
@@ -18,6 +18,7 @@
 use Pimcore\Document\Editable\EditmodeEditableDefinitionCollector;
 use Pimcore\Http\Request\Resolver\EditmodeResolver;
 use Pimcore\Model\Document\Editable;
+use Pimcore\Model\Document\Editable\LazyLoadingInterface;
 use Pimcore\Model\Document\Editable\Loader\EditableLoaderInterface;
 use Pimcore\Model\Document\PageSnippet;
 use Psr\Log\LoggerAwareInterface;
@@ -90,7 +91,13 @@ public function getEditable(PageSnippet $document, string $type, string $name, a
         $editable = $document->getEditable($name);
         if ($editable instanceof Editable\EditableInterface && $editable->getType() === $type) {
             // call the load() method if it exists to reinitialize the data (eg. from serializing, ...)
-            if (method_exists($editable, 'load')) {
+            //TODO Pimcore 11: remove method_exists BC layer
+            if ($editable instanceof LazyLoadingInterface || method_exists($editable, 'load')) {
+                if (!$editable instanceof LazyLoadingInterface) {
+                    trigger_deprecation('pimcore/pimcore', '10.3',
+                        sprintf('Usage of method_exists is deprecated since version 10.3 and will be removed in Pimcore 11.' .
+                            'Implement the %s interface instead.', LazyLoadingInterface::class));
+                }
                 $editable->load();
             }
         } else {

diff --git a/models/Document/Editable.php b/models/Document/Editable.php
@@ -189,7 +189,13 @@ public function getEditmodeDefinition(): array
     protected function getEditmodeData()
     {
         // get configuration data for admin
-        if (method_exists($this, 'getDataEditmode')) {
+        //TODO Pimcore 11: remove method_exists BC layer
+        if ($this instanceof Document\Editable\EditmodeDataInterface || method_exists($this, 'getDataEditmode')) {
+            if (!$this instanceof Document\Editable\EditmodeDataInterface) {
+                trigger_deprecation('pimcore/pimcore', '10.3',
+                    sprintf('Usage of method_exists is deprecated since version 10.3 and will be removed in Pimcore 11.' .
+                        'Implement the %s interface instead.', Document\Editable\EditmodeDataInterface::class));
+            }
             $data = $this->getDataEditmode();
         } else {
             $data = $this->getData();

diff --git a/models/Document/Editable/Date.php b/models/Document/Editable/Date.php
@@ -20,7 +20,7 @@
 /**
  * @method \Pimcore\Model\Document\Editable\Dao getDao()
  */
-class Date extends Model\Document\Editable
+class Date extends Model\Document\Editable implements EditmodeDataInterface
 {
     /**
      * Contains the date
@@ -56,11 +56,9 @@ public function getDate()
     }
 
     /**
-     * Converts the data so it's suitable for the editmode
-     *
-     * @return int|null
+     * {@inheritdoc}
      */
-    public function getDataEditmode()
+    public function getDataEditmode() /** : mixed */
     {
         if ($this->date) {
             return $this->date->getTimestamp();

diff --git a/models/Document/Editable/EditmodeDataInterface.php b/models/Document/Editable/EditmodeDataInterface.php
@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Pimcore
+ *
+ * This source file is available under two different licenses:
+ * - GNU General Public License version 3 (GPLv3)
+ * - Pimcore Commercial License (PCL)
+ * Full copyright and license information is available in
+ * LICENSE.md which is distributed with this source code.
+ *
+ *  @copyright  Copyright (c) Pimcore GmbH (http://www.pimcore.org)
+ *  @license    http://www.pimcore.org/license     GPLv3 and PCL
+ */
+
+namespace Pimcore\Model\Document\Editable;
+
+interface EditmodeDataInterface
+{
+    /**
+     * Converts the data so it's suitable for the editmode
+     *
+     * @return mixed
+     */
+    public function getDataEditmode() /** : mixed */;
+}
diff --git a/models/Document/Editable/IdRewriterInterface.php b/models/Document/Editable/IdRewriterInterface.php
@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Pimcore
+ *
+ * This source file is available under two different licenses:
+ * - GNU General Public License version 3 (GPLv3)
+ * - Pimcore Commercial License (PCL)
+ * Full copyright and license information is available in
+ * LICENSE.md which is distributed with this source code.
+ *
+ *  @copyright  Copyright (c) Pimcore GmbH (http://www.pimcore.org)
+ *  @license    http://www.pimcore.org/license     GPLv3 and PCL
+ */
+
+namespace Pimcore\Model\Document\Editable;
+
+interface IdRewriterInterface
+{
+    /**
+     * Rewrites id from source to target, $idMapping contains
+     * array(
+     *  "document" => array(
+     *      SOURCE_ID => TARGET_ID,
+     *      SOURCE_ID => TARGET_ID
+     *  ),
+     *  "object" => array(...),
+     *  "asset" => array(...)
+     * )
+     *
+     * @param array $idMapping
+     *
+     * @return void
+     */
+    public function rewriteIds(/*array*/ $idMapping) /** : void */;
+}
diff --git a/models/Document/Editable/Image.php b/models/Document/Editable/Image.php
@@ -23,7 +23,7 @@
 /**
  * @method \Pimcore\Model\Document\Editable\Dao getDao()
  */
-class Image extends Model\Document\Editable
+class Image extends Model\Document\Editable implements IdRewriterInterface, EditmodeDataInterface
 {
     /**
      * ID of the referenced image
@@ -146,11 +146,9 @@ public function getDataForResource()
     }
 
     /**
-     * Converts the data so it's suitable for the editmode
-     *
-     * @return array|null
+     * {@inheritdoc}
      */
-    public function getDataEditmode()
+    public function getDataEditmode() /** : mixed */
     {
         $image = $this->getImage();
 
@@ -741,19 +739,9 @@ public function getMarker()
     }
 
     /**
-     * Rewrites id from source to target, $idMapping contains
-     * array(
-     *  "document" => array(
-     *      SOURCE_ID => TARGET_ID,
-     *      SOURCE_ID => TARGET_ID
-     *  ),
-     *  "object" => array(...),
-     *  "asset" => array(...)
-     * )
-     *
-     * @param array $idMapping
+     * { @inheritdoc }
      */
-    public function rewriteIds($idMapping)
+    public function rewriteIds($idMapping) /** : void */
     {
         if (array_key_exists('asset', $idMapping) && array_key_exists($this->getId(), $idMapping['asset'])) {
             $this->setId($idMapping['asset'][$this->getId()]);

diff --git a/models/Document/Editable/Input.php b/models/Document/Editable/Input.php
@@ -20,7 +20,7 @@
 /**
  * @method \Pimcore\Model\Document\Editable\Dao getDao()
  */
-class Input extends Model\Document\Editable
+class Input extends Model\Document\Editable implements EditmodeDataInterface
 {
     /**
      * Contains the text for this element
@@ -70,7 +70,10 @@ public function frontend()
         return $text;
     }
 
-    public function getDataEditmode()
+    /**
+     * {@inheritdoc}
+     */
+    public function getDataEditmode() /** : mixed */
     {
         return htmlentities($this->text);
     }

diff --git a/models/Document/Editable/LazyLoadingInterface.php b/models/Document/Editable/LazyLoadingInterface.php
@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Pimcore
+ *
+ * This source file is available under two different licenses:
+ * - GNU General Public License version 3 (GPLv3)
+ * - Pimcore Commercial License (PCL)
+ * Full copyright and license information is available in
+ * LICENSE.md which is distributed with this source code.
+ *
+ *  @copyright  Copyright (c) Pimcore GmbH (http://www.pimcore.org)
+ *  @license    http://www.pimcore.org/license     GPLv3 and PCL
+ */
+
+namespace Pimcore\Model\Document\Editable;
+
+interface LazyLoadingInterface
+{
+    /**
+     * this method is called by Document\Service::loadAllDocumentFields() to load all lazy loading fields
+     *
+     * @return void
+     */
+    public function load() /** : void */;
+}
diff --git a/models/Document/Editable/Link.php b/models/Document/Editable/Link.php
@@ -23,7 +23,7 @@
 /**
  * @method \Pimcore\Model\Document\Editable\Dao getDao()
  */
-class Link extends Model\Document\Editable
+class Link extends Model\Document\Editable implements IdRewriterInterface, EditmodeDataInterface
 {
     /**
      * Contains the data for the link
@@ -54,11 +54,9 @@ public function getData()
     }
 
     /**
-     * @see EditableInterface::getDataEditmode
-     *
-     * @return mixed
+     * {@inheritdoc}
      */
-    public function getDataEditmode()
+    public function getDataEditmode() /** : mixed */
     {
         // update path if internal link
         $this->updatePathFromInternal(true, true);
@@ -506,19 +504,9 @@ public function resolveDependencies()
     }
 
     /**
-     * Rewrites id from source to target, $idMapping contains
-     * array(
-     *  "document" => array(
-     *      SOURCE_ID => TARGET_ID,
-     *      SOURCE_ID => TARGET_ID
-     *  ),
-     *  "object" => array(...),
-     *  "asset" => array(...)
-     * )
-     *
-     * @param array $idMapping
+     * { @inheritdoc }
      */
-    public function rewriteIds($idMapping)
+    public function rewriteIds($idMapping) /** : void */
     {
         if (isset($this->data['internal']) && $this->data['internal']) {
             $type = $this->data['internalType'];

diff --git a/models/Document/Editable/Multiselect.php b/models/Document/Editable/Multiselect.php
@@ -20,7 +20,7 @@
 /**
  * @method \Pimcore\Model\Document\Editable\Dao getDao()
  */
-class Multiselect extends Model\Document\Editable
+class Multiselect extends Model\Document\Editable implements EditmodeDataInterface
 {
     /**
      * Contains the current selected values
@@ -64,9 +64,9 @@ public function frontend()
     }
 
     /**
-     * @return array
+     * {@inheritdoc}
      */
-    public function getDataEditmode()
+    public function getDataEditmode() /** : mixed */
     {
         return $this->values;
     }

diff --git a/models/Document/Editable/Pdf.php b/models/Document/Editable/Pdf.php
@@ -22,7 +22,7 @@
 /**
  * @method \Pimcore\Model\Document\Editable\Dao getDao()
  */
-class Pdf extends Model\Document\Editable
+class Pdf extends Model\Document\Editable implements EditmodeDataInterface
 {
     /**
      * @internal
@@ -60,9 +60,9 @@ public function getDataForResource()
     }
 
     /**
-     * @return array
+     * {@inheritdoc}
      */
-    public function getDataEditmode()
+    public function getDataEditmode() /** : mixed */
     {
         $pages = 0;
 

diff --git a/models/Document/Editable/Relation.php b/models/Document/Editable/Relation.php
@@ -24,7 +24,7 @@
 /**
  * @method \Pimcore\Model\Document\Editable\Dao getDao()
  */
-class Relation extends Model\Document\Editable
+class Relation extends Model\Document\Editable implements IdRewriterInterface, EditmodeDataInterface, LazyLoadingInterface
 {
     /**
      * ID of the source object
@@ -84,11 +84,9 @@ public function getData()
     }
 
     /**
-     * Converts the data so it's suitable for the editmode
-     *
-     * @return array|null
+     * {@inheritdoc}
      */
-    public function getDataEditmode()
+    public function getDataEditmode() /** : mixed */
     {
         $this->setElement();
 
@@ -279,9 +277,9 @@ public function __sleep()
     }
 
     /**
-     * this method is called by Document\Service::loadAllDocumentFields() to load all lazy loading fields
+     * {@inheritdoc}
      */
-    public function load()
+    public function load() /** : void */
     {
         if (!$this->element) {
             $this->setElement();
@@ -329,19 +327,9 @@ public function getSubtype()
     }
 
     /**
-     * Rewrites id from source to target, $idMapping contains
-     * array(
-     *  "document" => array(
-     *      SOURCE_ID => TARGET_ID,
-     *      SOURCE_ID => TARGET_ID
-     *  ),
-     *  "object" => array(...),
-     *  "asset" => array(...)
-     * )
-     *
-     * @param array $idMapping
+     * { @inheritdoc }
      */
-    public function rewriteIds($idMapping)
+    public function rewriteIds($idMapping) /** : void */
     {
         if (array_key_exists($this->type, $idMapping) && array_key_exists($this->getId(), $idMapping[$this->type])) {
             $this->id = $idMapping[$this->type][$this->getId()];