From 8022e516ce9b11499f244cb985dddede6f684208 Mon Sep 17 00:00:00 2001
From: twoldanski <66474451+twoldanski@users.noreply.github.com>
Date: Thu, 20 Feb 2025 12:57:46 +0100
Subject: [PATCH] [TASK] Provide clear messaging with expected colPos with
 grouping enabled (#806)

Resolves: #801
---
 .../ContentObject/JsonContentContentObject.php   | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

diff --git a/Classes/ContentObject/JsonContentContentObject.php b/Classes/ContentObject/JsonContentContentObject.php
index a6ffee69..e97b580a 100755
--- a/Classes/ContentObject/JsonContentContentObject.php
+++ b/Classes/ContentObject/JsonContentContentObject.php
@@ -15,6 +15,7 @@
 use FriendsOfTYPO3\Headless\Json\JsonEncoderInterface;
 use FriendsOfTYPO3\Headless\Utility\HeadlessUserInt;
 use Psr\EventDispatcher\EventDispatcherInterface;
+use RuntimeException;
 use TYPO3\CMS\Backend\View\BackendLayoutView;
 use TYPO3\CMS\Core\Information\Typo3Version;
 use TYPO3\CMS\Core\TimeTracker\TimeTracker;
@@ -182,8 +183,10 @@ protected function groupContentElementsByColPos(array $contentElements, array $c
                 continue;
             }
 
-            if ($groupingEnabled && ($element['colPos'] ?? 0) >= 0) {
-                $data['colPos' . $element['colPos']][] = $element;
+            $colPos = $this->getColPosFromElement($groupingEnabled, $element);
+
+            if ($groupingEnabled && $colPos >= 0) {
+                $data['colPos' . $colPos][] = $element;
             } else {
                 $data[] = $element;
             }
@@ -347,4 +350,13 @@ private function returnSingleRowEnabled(array $conf): bool
     {
         return isset($conf['returnSingleRow']) && (int)$conf['returnSingleRow'] === 1;
     }
+
+    private function getColPosFromElement(bool $groupingEnabled, array $element): int
+    {
+        if ($groupingEnabled && !array_key_exists('colPos', $element)) {
+            throw new RuntimeException('Content element by ID: "' . ($element['id'] ?? 0) . '" does not have "colPos" field defined. Disable grouping or fix TypoScript definition of the element.', 1739347200);
+        }
+
+        return (int)($element['colPos'] ?? 0);
+    }
 }