[FEATURE] Allow XPath functions to directly return a result, resolves #389

fsuter · fsuter · commit 591d7fcf2c8d · 2026-01-07T20:16:35.000+01:00
diff --git a/ChangeLog b/ChangeLog
@@ -1,3 +1,7 @@
+2026-01-07 Francois Suter (Idéative)  <typo3@ideative.ch>
+
+    * Allow XPath functions to directly return a result, resolves #389
+
 2026-01-04 Francois Suter (Idéative)  <typo3@ideative.ch>
 
     * Expand test coverage of XmlHandler, references #389
diff --git a/Classes/Handler/XmlHandler.php b/Classes/Handler/XmlHandler.php
@@ -21,6 +21,7 @@
 use Cobweb\ExternalImport\Event\SubstructurePreprocessEvent;
 use Cobweb\ExternalImport\Exception\XpathSelectionFailedException;
 use Cobweb\ExternalImport\Importer;
+use DOMNodeList;
 use Psr\EventDispatcher\EventDispatcherInterface;
 use TYPO3\CMS\Core\Type\ContextualFeedbackSeverity;
 
@@ -69,10 +70,16 @@ public function handleData($rawData, Importer $importer): array
         $records = [];
         if (array_key_exists('nodepath', $generalConfiguration)) {
             try {
-                $records = $this->selectNodeWithXpath(
+                $records = $this->selectWithXpath(
                     $xPathObject,
                     $generalConfiguration['nodepath']
                 );
+                // Only a node list makes sense in this context, log an error if anything else was returned
+                if (!($records instanceof \DomNodeList)) {
+                    $importer->addMessage(
+                        'No nodes could be selected with existing configuration',
+                    );
+                }
             } catch (\Exception $e) {
                 $importer->addMessage(
                     $e->getMessage(),
@@ -201,11 +208,15 @@ public function getValue(\DOMNode $record, array $columnConfiguration, \DOMXPath
                 $selectedNode = $nodeList->item(0);
                 // If an XPath expression is defined, apply it (relative to currently selected node)
                 if (!empty($columnConfiguration['xpath'])) {
-                    $nodes = $this->selectNodeWithXpath(
+                    $nodes = $this->selectWithXpath(
                         $xPathObject,
                         $columnConfiguration['xpath'],
                         $selectedNode
                     );
+                    // If result is a string, return it as is
+                    if (is_string($nodes)) {
+                        return $nodes;
+                    }
                     $selectedNode = $nodes->item(0);
                 }
                 $value = $this->extractValueFromNode(
@@ -222,11 +233,15 @@ public function getValue(\DOMNode $record, array $columnConfiguration, \DOMXPath
         } else {
             // If an XPath expression is defined, apply it (relative to current node)
             if (!empty($columnConfiguration['xpath'])) {
-                $nodes = $this->selectNodeWithXpath(
+                $nodes = $this->selectWithXpath(
                     $xPathObject,
                     $columnConfiguration['xpath'],
                     $record
                 );
+                // If result is a string, return it as is
+                if (is_string($nodes)) {
+                    return $nodes;
+                }
                 $selectedNode = $nodes->item(0);
                 $value = $this->extractValueFromNode(
                     $selectedNode,
@@ -267,7 +282,7 @@ public function getNodeList(\DOMNode $record, array $columnConfiguration, \DOMXP
 
             if ($nodeList->length > 0 && !empty($columnConfiguration['xpath'])) {
                 $selectedNode = $nodeList->item(0);
-                $nodeList = $this->selectNodeWithXpath(
+                $nodeList = $this->selectWithXpath(
                     $xPathObject,
                     $columnConfiguration['xpath'],
                     $selectedNode
@@ -282,7 +297,7 @@ public function getNodeList(\DOMNode $record, array $columnConfiguration, \DOMXP
         } else {
             // If an XPath expression is defined, apply it (relative to current node)
             if (!empty($columnConfiguration['xpath'])) {
-                $nodeList = $this->selectNodeWithXpath(
+                $nodeList = $this->selectWithXpath(
                     $xPathObject,
                     $columnConfiguration['xpath'],
                     $record
@@ -291,13 +306,17 @@ public function getNodeList(\DOMNode $record, array $columnConfiguration, \DOMXP
                 // Create a DOMNodeList by querying the current node (record) itself with XPath
                 // (weird, but the alternative is to create a new DOMDocument and import the node into it,
                 // which is not really any better)
-                $nodeList = $this->selectNodeWithXpath(
+                $nodeList = $this->selectWithXpath(
                     $xPathObject,
                     '.',
                     $record
                 );
             }
         }
+        // Only a node list makes sense in this context, create an empty list if anything else was returned
+        if (!($nodeList instanceof \DomNodeList)) {
+            $nodeList = new \DomNodeList();
+        }
         return $nodeList;
     }
 
@@ -361,10 +380,10 @@ public function getXmlValue(\DOMNode $node): string
      * @param \DOMXPath $xPathObject Instantiated DOMXPath object
      * @param string $xPath XPath query to evaluate
      * @param \DOMNode|null $context Node giving the context of the XPath query (null for root node)
-     * @return \DOMNodeList List of found nodes
+     * @return \DOMNodeList|string List of found nodes
      * @throws XpathSelectionFailedException
      */
-    public function selectNodeWithXpath(\DOMXPath $xPathObject, string $xPath, ?\DOMNode $context = null): \DOMNodeList
+    public function selectWithXpath(\DOMXPath $xPathObject, string $xPath, ?\DOMNode $context = null): \DOMNodeList|string
     {
         $resultNodes = $xPathObject->evaluate($xPath, $context);
         if ($resultNodes === false) {
@@ -373,7 +392,7 @@ public function selectNodeWithXpath(\DOMXPath $xPathObject, string $xPath, ?\DOM
                 1767541086
             );
         }
-        if ($resultNodes->length > 0) {
+        if (($resultNodes instanceof \DOMNodeList && $resultNodes->length > 0) || is_string($resultNodes)) {
             return $resultNodes;
         }
         throw new XpathSelectionFailedException(
diff --git a/Documentation/Administration/Columns/Index.rst b/Documentation/Administration/Columns/Index.rst
@@ -218,6 +218,7 @@ Description
   The value will be taken from the first node returned by the query.
   If the :ref:`attribute <administration-columns-properties-attribute>` property is
   also defined, it will be applied to the node returned by the XPath query.
+  If the XPath query is just a function (without selector), the resulting string will be returned.
 
   Please see the :ref:`namespaces <administration-general-tca-properties-namespaces>`
   property for declaring namespaces to use in a XPath query.
diff --git a/Tests/Unit/Handler/XmlHandlerTest.php b/Tests/Unit/Handler/XmlHandlerTest.php
@@ -77,6 +77,16 @@ public static function selectWithXpathValidProvider(): array
 
 XML,
             ],
+            'string selection' => [
+                'structure' => <<<'XML'
+<items>
+    <item id="foo1" quality="poor">foo</item>
+</items>
+XML,
+                'xpath' => 'concat(@id, \'-\', @quality)',
+                'context' => 'item',
+                'result' => 'foo1-poor',
+            ],
         ];
     }
 
@@ -90,16 +100,21 @@ public function selectWithXpathReturnsNodeListOrStringWithValidPath(string $stru
         if (!empty($context)) {
             $contextNode = $dom->getElementsByTagName($context)->item(0);
         }
-        $nodeList = $this->subject->selectNodeWithXpath($xPathObject, $xpath, $contextNode);
-        $resultingDocument = new \DOMDocument();
-        // Test the result by writing the selected nodes to a new document
-        foreach ($nodeList as $node) {
-            $node = $resultingDocument->importNode($node, true);
-            $resultingDocument->appendChild($node);
+        $nodeList = $this->subject->selectWithXpath($xPathObject, $xpath, $contextNode);
+        if (is_string($nodeList)) {
+            $effectiveResult = $nodeList;
+        } else {
+            $resultingDocument = new \DOMDocument();
+            // Test the result by writing the selected nodes to a new document
+            foreach ($nodeList as $node) {
+                $node = $resultingDocument->importNode($node, true);
+                $resultingDocument->appendChild($node);
+            }
+            $effectiveResult = $resultingDocument->saveXML();
         }
         self::assertSame(
             $result,
-            $resultingDocument->saveXML()
+            $effectiveResult,
         );
     }
 
@@ -144,7 +159,7 @@ public function selectWithXpathThrowsExceptionWithInvalidPath(string $structure,
         if (!empty($context)) {
             $contextNode = $dom->getElementsByTagName($context)->item(0);
         }
-        $this->subject->selectNodeWithXpath($xPathObject, $xpath, $contextNode);
+        $this->subject->selectWithXpath($xPathObject, $xpath, $contextNode);
     }
 
     public static function getValueSuccessProvider(): array
@@ -200,6 +215,14 @@ public static function getValueSuccessProvider(): array
                 ],
                 'result' => 'foo',
             ],
+            'xpath value, with function' => [
+                'structure' => '<item id="bar1" name="Foo">foo</item>',
+                'configuration' => [
+                    'field' => 'item',
+                    'xpath' => 'concat(@id, \'-\', @name)',
+                ],
+                'result' => 'bar1-Foo',
+            ],
             'substructure as string' => [
                 'structure' => '<item><foo>me</foo><bar>you</bar></item>',
                 'configuration' => [
