From 444222172fee91eb61498a222a3c331248971c23 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Guillaume=20Delr=C3=A9?= <delre.guillaume@gmail.com>
Date: Sun, 10 May 2026 23:46:53 +0200
Subject: [PATCH] feat: add @:text, @:cdata, @:comment to array syntax
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The @ special key already sets text content in the concise array
syntax. This extends it with typed variants:
  - @:text   — explicit alias for @
  - @:cdata  — wraps content in a CDATA section
  - @:comment — inserts an XML comment

Closes #23

Signed-off-by: Guillaume Delré <delre.guillaume@gmail.com>
---
 source/FluidXml/FluidInsertionHandler.php | 28 +++++++++++++++++-
 specs/FluidXml.php                        | 35 +++++++++++++++++++++++
 2 files changed, 62 insertions(+), 1 deletion(-)

diff --git a/source/FluidXml/FluidInsertionHandler.php b/source/FluidXml/FluidInsertionHandler.php
index f47fd46..5b6a3a1 100644
--- a/source/FluidXml/FluidInsertionHandler.php
+++ b/source/FluidXml/FluidInsertionHandler.php
@@ -110,9 +110,15 @@ protected function recognizeStringMixed($k, $v)
                 }
 
                 if ($k[0] === '@') {
-                        if ($k === '@') {
+                        if ($k === '@' || $k === '@:text') {
                                 return 'insertSpecialContent';
                         }
+                        if ($k === '@:cdata') {
+                                return 'insertSpecialCdata';
+                        }
+                        if ($k === '@:comment') {
+                                return 'insertSpecialComment';
+                        }
                         return 'insertSpecialAttribute';
                 }
 
@@ -250,6 +256,26 @@ protected function insertSpecialContent($parent, $k, $v): array
                 return [];
         }
 
+        protected function insertSpecialCdata($parent, $k, $v): array
+        {
+                // The user has passed CDATA content:
+                // [ '@:cdata' => 'Content with <special> chars.' ]
+
+                $this->newContext($parent)->addCdata($v);
+
+                return [];
+        }
+
+        protected function insertSpecialComment($parent, $k, $v): array
+        {
+                // The user has passed a comment:
+                // [ '@:comment' => 'This is a comment.' ]
+
+                $this->newContext($parent)->addComment($v);
+
+                return [];
+        }
+
         protected function insertSpecialAttribute($parent, $k, $v): array
         {
                 // The user has passed an attribute name and an attribute value:
diff --git a/specs/FluidXml.php b/specs/FluidXml.php
index 6cac1ef..ffa2ab3 100644
--- a/specs/FluidXml.php
+++ b/specs/FluidXml.php
@@ -1319,6 +1319,41 @@ function addchild($parent, $i)
                         assert_equal_xml($xml, $expected);
                 });
 
+                it('should add text content using @:text as alias for @', function () {
+                        $xml = new FluidXml();
+                        $xml->addChild(['child1' => [ '@:text' => 'Hello' ]]);
+
+                        $expected = "<doc>\n"
+                                  . "  <child1>Hello</child1>\n"
+                                  . "</doc>";
+                        assert_equal_xml($xml, $expected);
+                });
+
+                it('should add CDATA content using @:cdata syntax', function () {
+                        $xml = new FluidXml();
+                        $xml->addChild(['chapter' => [
+                                '@id'    => '1',
+                                '@:cdata' => 'Ideas About <The> Universe',
+                        ]]);
+
+                        $expected = "<doc>\n"
+                                  . "  <chapter id=\"1\"><![CDATA[Ideas About <The> Universe]]></chapter>\n"
+                                  . "</doc>";
+                        assert_equal_xml($xml, $expected);
+                });
+
+                it('should add comment content using @:comment syntax', function () {
+                        $xml = new FluidXml();
+                        $xml->addChild(['node' => [ '@:comment' => 'This is a comment' ]]);
+
+                        $expected = "<doc>\n"
+                                  . "  <node>\n"
+                                  . "    <!--This is a comment-->\n"
+                                  . "  </node>\n"
+                                  . "</doc>";
+                        assert_equal_xml($xml, $expected);
+                });
+
                 it('should switch context', function () {
                         $xml = new FluidXml();