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);
+ }
}