Merge pull request #67 from veewee/shortcut-functions

Add stringify and document element shortcuts to XML Document
veewee · Jan 14, 2024 · 143c565 · 143c565
2 parents 3172e96 + eaba15b
commit 143c565
Show file tree

Hide file tree

Showing 3 changed files with 63 additions and 0 deletions.
diff --git a/docs/dom.md b/docs/dom.md
@@ -763,6 +763,9 @@ use function VeeWee\Xml\Dom\Locator\document_element;
 
 $doc = Document::fromXmlFile('some.xml');
 $rootElement = $doc->locate(document_element());
+
+// Since this is a common action, there is also a shortcut:
+$doc->locateDocumentElement();
 ```
 
 #### elements_with_namespaced_tagname
@@ -1116,7 +1119,12 @@ Converts the DOM document to something else.
 use VeeWee\Xml\Dom\Document;
 
 $doc = Document::fromXmlFile('some.xml');
+
+// Get full XML including the XML declaration tag:
 $xml = $doc->toXmlString();
+
+// OR, get only the XML part without declaration:
+$xml = $doc->stringifyDocumentElement();
 ```
 
 Instead of mapping a full document, you can also map a specific node only to XML.
@@ -1126,6 +1134,9 @@ use function VeeWee\Xml\Dom\Mapper\xml_string;
 
 $mapper = xml_string();
 $xml = $mapper($someNode);
+
+// Or use the shortcut on Document level:
+$xml = $doc->stringifyNode($someNode);
 ```
 
 #### xslt_template

diff --git a/src/Xml/Dom/Document.php b/src/Xml/Dom/Document.php
@@ -6,6 +6,7 @@
 
 use Closure;
 use DOMDocument;
+use DOMElement;
 use DOMNode;
 use DOMXPath;
 use VeeWee\Xml\Dom\Traverser\Traverser;
@@ -113,6 +114,11 @@ public function locate(callable $locator)
         return $locator($this->document);
     }
 
+    public function locateDocumentElement(): DOMElement
+    {
+        return $this->locate(Locator\document_element());
+    }
+
     /**
      * @param callable(DOMDocument): mixed $manipulator
      *
@@ -191,4 +197,20 @@ public function toXmlString(): string
     {
         return $this->map(xml_string());
     }
+
+    /**
+     * @return non-empty-string
+     */
+    public function stringifyDocumentElement(): string
+    {
+        return xml_string()($this->locateDocumentElement());
+    }
+
+    /**
+     * @return non-empty-string
+     */
+    public function stringifyNode(DOMNode $node): string
+    {
+        return xml_string()($node);
+    }
 }
diff --git a/tests/Xml/Dom/DocumentTest.php b/tests/Xml/Dom/DocumentTest.php
@@ -144,4 +144,34 @@ public function test_it_can_reconfigure_document(): void
         static::assertSame($doc1->toUnsafeDocument(), $doc2->toUnsafeDocument());
         static::assertXmlStringEqualsXmlString($xml1, $xml2);
     }
+
+    public function test_it_can_locate(): void
+    {
+        $doc = Document::fromXmlString('<hello />');
+        $actual1 = $doc->locate(document_element());
+        $actual2 = $doc->locateDocumentElement();
+
+        static::assertSame($doc->toUnsafeDocument()->documentElement, $actual1);
+        static::assertSame($actual1, $actual2);
+    }
+
+    public function test_it_can_stringify_parts(): void
+    {
+        $doc = Document::fromXmlString('<hello value="world"/>');
+        $full = $doc->toXmlString();
+        $documentElement = $doc->stringifyDocumentElement();
+        $node = $doc->stringifyNode($doc->locateDocumentElement());
+        $attr = $doc->stringifyNode($doc->locateDocumentElement()->getAttributeNode('value'));
+
+
+        $expected = '<hello value="world"/>';
+
+        static::assertSame(
+            '<?xml version="1.0"?>'.PHP_EOL.$expected.PHP_EOL,
+            $full
+        );
+        static::assertSame($expected, $documentElement);
+        static::assertSame($expected, $node);
+        static::assertSame(' value="world"', $attr);
+    }
 }