Helpful message for esi rendered shortcodes with non-scalar uri attribute values

Author: MalteWunsch

Handler/EmbeddedShortcodeHandler.php

@@ -33,10 +33,10 @@ class EmbeddedShortcodeHandler
 
     /**
      * @param FragmentHandler $fragmentHandler
-     * @param string          $controllerName
-     * @param string          $renderer
+     * @param string $controllerName
+     * @param string $renderer
      * @param LoggerInterface $logger
-     * @param RequestStack    $requestStack
+     * @param RequestStack $requestStack
      */
     public function __construct(
         FragmentHandler $fragmentHandler,
@@ -70,12 +70,31 @@ public function __invoke(ShortcodeInterface $shortcode)
             ]
         );
 
-        return $this->fragmentHandler->render(
-            new ControllerReference(
-                $this->controllerName,
-                array_merge(['request' => $this->requestStack->getCurrentRequest()], $shortcode->getParameters())
-            ),
-            $this->renderer
-        );
+        try {
+            return $this->fragmentHandler->render(
+                new ControllerReference(
+                    $this->controllerName,
+                    array_merge(['request' => $this->requestStack->getCurrentRequest()], $shortcode->getParameters())
+                ),
+                $this->renderer
+            );
+        } catch (\InvalidArgumentException $exception) {
+            if ($this->renderer === 'esi') {
+                throw new \InvalidArgumentException(
+                    'An InvalidArgumentException occured while trying to render the shortcode '
+                    .$shortcode->getShortcodeText().'. You\'ve probably tried to use the ESI rendering  strategy for '
+                    .'your shortcodes while handling a request that contained non-scalar values as part of URI '
+                    .'attributes. This can happen e.g. when using Param Converters for your original controller '
+                    .'action, as the request (containing the conversion result) is automatically passed to the call of '
+                    .'the shortcode controller to allow context sensitive shortcodes. You could use '
+                    .'webfactory.shortcode.embed_inline_for_shortcode_handler as parent in your shortcode\'s service '
+                    .'defintion, so that the inline instead of ESI rendering strategy will be used.',
+                    0,
+                    $exception
+                );
+            }
+
+            throw $exception;
+        }
     }
 }