diff --git a/docs/dom.md b/docs/dom.md index e0021e7c..56bcc628 100644 --- 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 index 0fa1e210..448d39fc 100644 --- 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 index 51bbb8a1..04f9c9d1 100644 --- 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(''); + $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(''); + $full = $doc->toXmlString(); + $documentElement = $doc->stringifyDocumentElement(); + $node = $doc->stringifyNode($doc->locateDocumentElement()); + $attr = $doc->stringifyNode($doc->locateDocumentElement()->getAttributeNode('value')); + + + $expected = ''; + + static::assertSame( + ''.PHP_EOL.$expected.PHP_EOL, + $full + ); + static::assertSame($expected, $documentElement); + static::assertSame($expected, $node); + static::assertSame(' value="world"', $attr); + } }