Merge pull request #53 from veewee/cdata

Cdata functions
veewee · Jul 20, 2023 · ad6651f · ad6651f
2 parents 1c6b946 + 40d58d6
commit ad6651f
Show file tree

Hide file tree

Showing 13 changed files with 267 additions and 4 deletions.
diff --git a/docs/dom.md b/docs/dom.md
@@ -75,6 +75,21 @@ try {
 }
 ```
 
+#### assert_cdata
+
+Assert if a node is of type `DOMCdataSection`.
+
+```php
+use Psl\Type\Exception\AssertException;
+use function VeeWee\Xml\Dom\Assert\assert_cdata;
+
+try {
+    assert_cdata($someNode)
+} catch (AssertException $e) {
+    // Deal with it
+}
+```
+
 #### assert_document
 
 Assert if a node is of type `DOMDocument`.
@@ -205,6 +220,26 @@ element('foo',
 <foo hello="world" bar="baz" />
 ```
 
+#### cdata
+
+Operates on a `DOMNode` and creates a `DOMCdataSection`.
+It can contain a set of configurators that can be used to dynamically change the cdata's contents.
+
+```php
+use function VeeWee\Xml\Dom\Builder\attribute;
+use function VeeWee\Xml\Dom\Builder\element;
+use function VeeWee\Xml\Dom\Builder\cdata;
+use function VeeWee\Xml\Dom\Builder\children;
+
+element('hello', children(
+    cdata('<html>world</html>')
+));
+```
+
+```xml
+<hello><![CDATA[<html>world</html>]]></hello>
+```
+
 #### children
 
 Operates on a `DOMNode` and attaches multiple child nodes.
@@ -1157,6 +1192,18 @@ if (is_attribute($someNode)) {
 }
 ```
 
+#### is_cdata
+
+Checks if a node is of type `DOMCdataSection`.
+
+```php
+use function VeeWee\Xml\Dom\Predicate\is_cdata;
+
+if (is_cdata($someNode)) {
+   // ...
+}
+```
+
 #### is_default_xmlns_attribute
 
 Checks if a node is of type `DOMNameSpaceNode` and is the default xmlns.

diff --git a/docs/encoding.md b/docs/encoding.md
@@ -232,7 +232,7 @@ More information about [the PHP format can be found here](#php-format).
                     'id' => 2,
                     'test:type' => 'hello'  
                 ],
-                '@value' => 'Moon'
+                '@cdata' => '<html>Moon</html>'
             ]
         ]
     ]
@@ -253,6 +253,10 @@ More information about [the PHP format can be found here](#php-format).
     - You can provide any value that can be coerced to a string as an element value.
     - If the element does not have attributes, you can directly pass the value to the element name. In that case there is no need for the `@value` section.
     - All XML entities `<>"'` will be encoded before inserting a value into XML.
+- The `@cdata` section can be used for escaping HTML/XML content inside your XML element.
+  - You can provide any value that can be coerced to a string as an element value.
+  - The content will be wrapped with `<[CDATA[ ]]>`, special XML entities will not be escaped
+  - During decoding, cdata information will get lost: the element's `@value` will contain escaped XML entities. This is because an element can contain a mix of cdata and text nodes.
 - You can nest a single element or an array of elements into a parent element.
 
 #### Decoded types

diff --git a/src/Xml/Dom/Assert/assert_cdata.php b/src/Xml/Dom/Assert/assert_cdata.php
@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace VeeWee\Xml\Dom\Assert;
+
+use DOMCdataSection;
+use Psl\Type\Exception\AssertException;
+use function Psl\Type\instance_of;
+
+/**
+ * @psalm-assert DOMCdataSection $node
+ * @throws AssertException
+ */
+function assert_cdata(mixed $node): DOMCdataSection
+{
+    return instance_of(DOMCdataSection::class)->assert($node);
+}
diff --git a/src/Xml/Dom/Builder/cdata.php b/src/Xml/Dom/Builder/cdata.php
@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace VeeWee\Xml\Dom\Builder;
+
+use Closure;
+use DOMCdataSection;
+use DOMDocument;
+use DOMNode;
+use Webmozart\Assert\Assert;
+use function VeeWee\Xml\Dom\Assert\assert_cdata;
+use function VeeWee\Xml\Dom\Predicate\is_document;
+use function VeeWee\Xml\Internal\configure;
+
+/**
+ * @param list<callable(DOMCdataSection): DOMCdataSection> $configurators
+ *
+ * @return \Closure(DOMNode): DOMCdataSection
+ */
+function cdata(string $data, ...$configurators): Closure
+{
+    return static function (DOMNode $node) use ($data, $configurators): DOMCdataSection {
+        $document = is_document($node) ? $node : $node->ownerDocument;
+        Assert::isInstanceOf($document, DOMDocument::class, 'Can not create cdata without a DOM document.');
+
+        return assert_cdata(
+            configure(...$configurators)($document->createCDATASection($data))
+        );
+    };
+}
diff --git a/src/Xml/Dom/Predicate/is_cdata.php b/src/Xml/Dom/Predicate/is_cdata.php
@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace VeeWee\Xml\Dom\Predicate;
+
+use DOMCdataSection;
+use DOMNode;
+
+/**
+ * @psalm-assert-if-true DOMCdataSection $node
+ */
+function is_cdata(DOMNode $node): bool
+{
+    return $node instanceof DOMCdataSection;
+}
diff --git a/src/Xml/Encoding/Internal/Encoder/Builder/element.php b/src/Xml/Encoding/Internal/Encoder/Builder/element.php
@@ -17,6 +17,8 @@
 use function Psl\Vec\filter_nulls;
 use function Psl\Vec\values;
 use function VeeWee\Xml\Dom\Builder\attributes;
+use function VeeWee\Xml\Dom\Builder\cdata;
+use function VeeWee\Xml\Dom\Builder\children as childrenBuilder;
 use function VeeWee\Xml\Dom\Builder\element as elementBuilder;
 use function VeeWee\Xml\Dom\Builder\escaped_value;
 use function VeeWee\Xml\Dom\Builder\namespaced_element as namespacedElementBuilder;
@@ -36,19 +38,22 @@ function element(string $name, array $data): Closure
     $nullableMap = union(dict(string(), string()), null());
     $attributes = $nullableMap->assert($data['@attributes'] ?? null);
     $namespaces = $nullableMap->assert($data['@namespaces'] ?? null);
+    $cdata = union(string(), null())->assert($data['@cdata'] ?? null);
     $value = union(string(), null())->assert($data['@value'] ?? null);
 
     $element = filter_keys(
         $data,
-        static fn (string $key): bool => !in_array($key, ['@attributes', '@namespaces', '@value'], true)
+        static fn (string $key): bool => !in_array($key, ['@attributes', '@namespaces', '@value', '@cdata'], true)
     );
 
     $currentNamespace = $namespaces[''] ?? null;
     $namedNamespaces = filter_keys($namespaces ?? []);
 
+    /** @var list<\Closure(\DOMElement): \DOMElement> $children */
     $children = filter_nulls([
         $attributes ? attributes($attributes) : null,
         $namedNamespaces ? xmlns_attributes($namedNamespaces) : null,
+        $cdata !== null ? childrenBuilder(cdata($cdata)) : null,
         $value !== null ? escaped_value($value) : null,
         ...values(map_with_key(
             $element,

diff --git a/src/bootstrap.php b/src/bootstrap.php
@@ -1,11 +1,13 @@
 <?php declare(strict_types=1);
 
 require_once __DIR__.'/Xml/Dom/Assert/assert_attribute.php';
+require_once __DIR__.'/Xml/Dom/Assert/assert_cdata.php';
 require_once __DIR__.'/Xml/Dom/Assert/assert_document.php';
 require_once __DIR__.'/Xml/Dom/Assert/assert_dom_node_list.php';
 require_once __DIR__.'/Xml/Dom/Assert/assert_element.php';
 require_once __DIR__.'/Xml/Dom/Builder/attribute.php';
 require_once __DIR__.'/Xml/Dom/Builder/attributes.php';
+require_once __DIR__.'/Xml/Dom/Builder/cdata.php';
 require_once __DIR__.'/Xml/Dom/Builder/children.php';
 require_once __DIR__.'/Xml/Dom/Builder/element.php';
 require_once __DIR__.'/Xml/Dom/Builder/escaped_value.php';
@@ -67,6 +69,7 @@
 require_once __DIR__.'/Xml/Dom/Mapper/xml_string.php';
 require_once __DIR__.'/Xml/Dom/Mapper/xslt_template.php';
 require_once __DIR__.'/Xml/Dom/Predicate/is_attribute.php';
+require_once __DIR__.'/Xml/Dom/Predicate/is_cdata.php';
 require_once __DIR__.'/Xml/Dom/Predicate/is_default_xmlns_attribute.php';
 require_once __DIR__.'/Xml/Dom/Predicate/is_document.php';
 require_once __DIR__.'/Xml/Dom/Predicate/is_document_element.php';

diff --git a/tests/Xml/Dom/Assert/AssertCDataTest.php b/tests/Xml/Dom/Assert/AssertCDataTest.php
@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace VeeWee\Tests\Xml\Dom\Assert;
+
+use DOMNode;
+use PHPUnit\Framework\TestCase;
+use Psl\Type\Exception\AssertException;
+use VeeWee\Xml\Dom\Document;
+use function VeeWee\Xml\Dom\Assert\assert_cdata;
+
+final class AssertCDataTest extends TestCase
+{
+    /**
+     *
+     * @dataProvider provideTestCases
+     */
+    public function test_it_knows_cdata(?DOMNode $node, bool $expected): void
+    {
+        if (!$expected) {
+            $this->expectException(AssertException::class);
+        }
+
+        $actual = assert_cdata($node);
+        static::assertSame($node, $actual);
+    }
+
+    public function provideTestCases()
+    {
+        $doc = Document::fromXmlString(
+            <<<EOXML
+            <doc><![CDATA[<html>HELLO</html]]></doc>
+            EOXML
+        )->toUnsafeDocument();
+
+        yield [$doc, false];
+        yield [$doc->documentElement, false];
+        yield [$doc->documentElement->firstChild, true];
+        yield [null, false];
+    }
+}
diff --git a/tests/Xml/Dom/Builder/CdataTest.php b/tests/Xml/Dom/Builder/CdataTest.php
@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace VeeWee\Tests\Xml\Dom\Builder;
+
+use DOMCdataSection;
+use DOMDocument;
+use PHPUnit\Framework\TestCase;
+use function Psl\Fun\identity;
+use function VeeWee\Xml\Dom\Builder\cdata;
+use function VeeWee\Xml\Dom\Mapper\xml_string;
+
+final class CdataTest extends TestCase
+{
+    public function test_it_can_build_cdata(): void
+    {
+        $doc = new DOMDocument();
+        $node = cdata($data = '<html>hello</html>')($doc);
+
+        static::assertInstanceOf(DOMCdataSection::class, $node);
+        static::assertSame($data, $node->textContent);
+        static::assertSame(xml_string()($node), '<![CDATA['.$data.']]>');
+    }
+
+    public function test_it_can_build_cdata_with_configurators(): void
+    {
+        $doc = new DOMDocument();
+        $node = cdata($data = '<html>hello</html>', identity())($doc);
+
+        static::assertInstanceOf(DOMCdataSection::class, $node);
+        static::assertSame($data, $node->textContent);
+    }
+}
diff --git a/tests/Xml/Dom/Builder/ChildrenTest.php b/tests/Xml/Dom/Builder/ChildrenTest.php
@@ -6,8 +6,10 @@
 
 use DOMDocument;
 use PHPUnit\Framework\TestCase;
+use function VeeWee\Xml\Dom\Builder\cdata;
 use function VeeWee\Xml\Dom\Builder\children;
 use function VeeWee\Xml\Dom\Builder\element;
+use function VeeWee\Xml\Dom\Mapper\xml_string;
 
 final class ChildrenTest extends TestCase
 {
@@ -27,7 +29,6 @@ public function test_it_can_build_document_children(): void
         static::assertSame('world2', $children->item(1)->nodeName);
     }
 
-
     public function test_it_can_build_an_element_with_children(): void
     {
         $doc = new DOMDocument();
@@ -48,4 +49,20 @@ public function test_it_can_build_an_element_with_children(): void
         static::assertSame('world1', $children->item(0)->nodeName);
         static::assertSame('world2', $children->item(1)->nodeName);
     }
+
+    public function test_it_can_add_cdata(): void
+    {
+        $doc = new DOMDocument();
+        $node = element(
+            'hello',
+            children(
+                cdata('<html>world</html>'),
+            )
+        )($doc);
+
+        static::assertXmlStringEqualsXmlString(
+            '<hello><![CDATA[<html>world</html>]]></hello>',
+            xml_string()($node)
+        );
+    }
 }
diff --git a/tests/Xml/Dom/Builder/NodesTest.php b/tests/Xml/Dom/Builder/NodesTest.php
@@ -20,7 +20,7 @@ public function test_it_can_build_nodes(): void
             static fn (DOMDocument $doc): array => [
                 element('many1')($doc),
                 element('many2')($doc),
-            ]
+            ],
         )($doc);
 
         static::assertCount(4, $nodes);

diff --git a/tests/Xml/Dom/Predicate/IsCDataTest.php b/tests/Xml/Dom/Predicate/IsCDataTest.php
@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace VeeWee\Tests\Xml\Dom\Predicate;
+
+use DOMNode;
+use PHPUnit\Framework\TestCase;
+use VeeWee\Xml\Dom\Document;
+use function VeeWee\Xml\Dom\Predicate\is_cdata;
+
+final class IsCDataTest extends TestCase
+{
+    /**
+     *
+     * @dataProvider provideTestCases
+     */
+    public function test_it_knows_cdata(?DOMNode $node, bool $expected): void
+    {
+        $actual = is_cdata($node);
+        static::assertSame($expected, $actual);
+    }
+
+    public function provideTestCases()
+    {
+        $doc = Document::fromXmlString(
+            <<<EOXML
+            <doc><![CDATA[<html>HELLO</html]]></doc>
+            EOXML
+        )->toUnsafeDocument();
+
+        yield [$doc, false];
+        yield [$doc->documentElement, false];
+        yield [$doc->documentElement->firstChild, true];
+    }
+}
diff --git a/tests/Xml/Encoding/EncodingTest.php b/tests/Xml/Encoding/EncodingTest.php
@@ -239,6 +239,16 @@ public function provideBidirectionalCases()
                 ]
             ]
         ];
+        yield 'cdata' => [
+            'xml' => '<hello><![CDATA[<html>world</html>]]></hello>',
+            'data' => ['hello' => [
+                '@cdata' => '<html>world</html>'
+            ]]
+        ];
+        yield 'mixed cdata' => [
+            'xml' => '<hello>hello <![CDATA[<html>world</html>]]></hello>',
+            'data' => ['hello' => 'hello <html>world</html>']
+        ];
     }
 
     public function provideRiskyBidirectionalCases()