Update docs

Author: veewee

docs/dom.md

@@ -10,7 +10,7 @@ use VeeWee\Xml\Xsd\Schema\Manipulator;
 use function VeeWee\Xml\Dom\Locator\Xsd\locate_all_xsd_schemas;
 
 $doc = Document::fromXmlFile('some.xml');
-$schemas = locate_all_xsd_schemas($doc->toUnsafeDocument())
+$schemas = $doc->map(locate_all_xsd_schemas(...))
     ->manipulate(Manipulator\base_path('/var/www'))
     ->manipulate(Manipulator\overwrite_with_local_files([
         'http://www.w3.org/2001/XMLSchema' => '/local/XMLSchema.xsd'

docs/xsd.md

@@ -9,10 +9,10 @@
 use function Psl\Type\instance_of;
 
 /**
- * @psalm-assert \Dom\CDATASection $node
+ * @psalm-assert \Dom\CdataSection $node
  * @throws AssertException
  */
-function assert_cdata(mixed $node): \Dom\CDATASection
+function assert_cdata(mixed $node): \Dom\CdataSection
 {
-    return instance_of(\Dom\CDATASection::class)->assert($node);
+    return instance_of(\Dom\CdataSection::class)->assert($node);
 }

src/Xml/Dom/Assert/assert_cdata.php

@@ -5,24 +5,24 @@
 namespace VeeWee\Xml\Dom\Builder;
 
 use Closure;
-use \Dom\CDATASection;
+use \Dom\CdataSection;
 use \Dom\Node;
 use function VeeWee\Xml\Dom\Assert\assert_cdata;
 use function VeeWee\Xml\Dom\Locator\Node\detect_document;
 use function VeeWee\Xml\Internal\configure;
 
 /**
- * @param list<callable(\Dom\CDATASection): \Dom\CDATASection> $configurators
+ * @param list<callable(\Dom\CdataSection): \Dom\CdataSection> $configurators
  *
- * @return Closure(\Dom\Node): \Dom\CDATASection
+ * @return Closure(\Dom\Node): \Dom\CdataSection
  */
 function cdata(string $data, ...$configurators): Closure
 {
-    return static function (\Dom\Node $node) use ($data, $configurators): \Dom\CDATASection {
+    return static function (\Dom\Node $node) use ($data, $configurators): \Dom\CdataSection {
         $document = detect_document($node);
 
         return assert_cdata(
-            configure(...$configurators)($document->createCDATASection($data))
+            configure(...$configurators)($document->createCdataSection($data))
         );
     };
 }

src/Xml/Dom/Builder/cdata.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace VeeWee\Xml\Dom\Configurator;
+
+use Closure;
+use VeeWee\Xml\Dom\Document;
+
+/**
+ * @param callable(\DOM\XMLDocument ): void $loader
+ *
+ * @return Closure(\DOM\XMLDocument ): \DOM\XMLDocument
+ */
+function loader(callable $loader): Closure
+{
+    return static function (\DOM\XMLDocument $document) use ($loader): \DOM\XMLDocument {
+        return Document::fromLoader($loader)->toUnsafeDocument();
+    };
+}

src/Xml/Dom/Configurator/loader.php

@@ -13,11 +13,11 @@
  * @param int $options - bitmask of LIBXML_* constants https://www.php.net/manual/en/libxml.constants.php
  * @return Closure(): XMLDocument
  */
-function xml_file_loader(string $file, int $options = 0): Closure
+function xml_file_loader(string $file, int $options = 0, ?string $override_encoding = null): Closure
 {
-    return static fn () => disallow_issues(static function () use ($file, $options): XMLDocument {
+    return static fn () => disallow_issues(static function () use ($file, $options, $override_encoding): XMLDocument {
         Assert::fileExists($file);
 
-        return XMLDocument::createFromFile($file, $options);
+        return XMLDocument::createFromFile($file, $options, $override_encoding);
     });
 }

src/Xml/Dom/Loader/xml_file_loader.php

@@ -13,9 +13,9 @@
  * @param int $options - bitmask of LIBXML_* constants https://www.php.net/manual/en/libxml.constants.php
  * @return Closure(): XMLDocument
  */
-function xml_string_loader(string $xml, int $options = 0): Closure
+function xml_string_loader(string $xml, int $options = 0, ?string $override_encoding = null): Closure
 {
-    return static fn () => disallow_issues(static function () use ($xml, $options): XMLDocument {
-        return XMLDocument::createFromString($xml, $options);
+    return static fn () => disallow_issues(static function () use ($xml, $options, $override_encoding): XMLDocument {
+        return XMLDocument::createFromString($xml, $options, $override_encoding);
     });
 }

src/Xml/Dom/Loader/xml_string_loader.php

@@ -4,13 +4,13 @@
 
 namespace VeeWee\Xml\Dom\Predicate;
 
-use \Dom\CDATASection;
+use \Dom\CdataSection;
 use \Dom\Node;
 
 /**
- * @psalm-assert-if-true \Dom\CDATASection $node
+ * @psalm-assert-if-true \Dom\CdataSection $node
  */
 function is_cdata(\Dom\Node $node): bool
 {
-    return $node instanceof \Dom\CDATASection;
+    return $node instanceof \Dom\CdataSection;
 }

src/Xml/Dom/Predicate/is_cdata.php

@@ -24,6 +24,7 @@
         'Xml\Dom\Configurator\canonicalize' => __DIR__.'/Xml/Dom/Configurator/canonicalize.php',
         'Xml\Dom\Configurator\comparable' => __DIR__.'/Xml/Dom/Configurator/comparable.php',
         'Xml\Dom\Configurator\document_uri' => __DIR__.'/Xml/Dom/Configurator/document_uri.php',
+        'Xml\Dom\Configurator\loader' => __DIR__.'/Xml/Dom/Configurator/loader.php',
         'Xml\Dom\Configurator\normalize' => __DIR__.'/Xml/Dom/Configurator/normalize.php',
         'Xml\Dom\Configurator\optimize_namespaces' => __DIR__.'/Xml/Dom/Configurator/optimize_namespaces.php',
         'Xml\Dom\Configurator\pretty_print' => __DIR__.'/Xml/Dom/Configurator/pretty_print.php',

src/bootstrap.php

@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+namespace VeeWee\Tests\Xml\Dom\Configurator;
+
+use Exception;
+use PHPUnit\Framework\TestCase;
+use function VeeWee\Xml\Dom\Configurator\loader;
+
+final class LoaderTest extends TestCase
+{
+    public function test_it_can_load_xml(): void
+    {
+        $doc = new \Dom\XMLDocument();
+        $xml = '<hello />';
+
+        $loader = loader(static function (\Dom\XMLDocument $doc) use ($xml): void {
+            $doc->loadXML($xml);
+        });
+
+        $result = $loader($doc);
+        static::assertNotSame($doc, $result);
+        static::assertXmlStringEqualsXmlString($xml, $result->saveXML());
+    }
+
+
+    public function test_it_can_mark_xml_loading_as_failed(): void
+    {
+        $doc = new \Dom\XMLDocument();
+        $exception = new Exception('Could not load the XML document');
+        $loader = loader(static function (\Dom\XMLDocument $doc) use ($exception): void {
+            throw $exception;
+        });
+
+        $this->expectExceptionObject($exception);
+        $loader($doc);
+    }
+}

tests/Xml/Dom/Configurator/LoaderTest.php

@@ -60,4 +60,17 @@ public function test_it_throws_exception_on_invalid_file(): void
 
         $loader();
     }
+
+    public function test_it_can_override_charset(): void
+    {
+        $xml = '<hello>héllo</hello>';
+        [$file, $handle] = $this->fillFile($xml);
+        $loader = xml_file_loader($file, override_encoding: 'ASCII');
+
+        $doc = $loader();
+        fclose($handle);
+
+        static::assertSame('<hello>héllo</hello>', $doc->saveXML($doc->documentElement));
+        static::assertSame('ASCII', $doc->encoding);
+    }
 }

tests/Xml/Dom/Loader/XmlFileLoaderTest.php

@@ -39,4 +39,14 @@ public function test_it_can_load_with_options(): void
 
         static::assertSame('<hello>HELLO</hello>', $doc->saveXML($doc->documentElement));
     }
+
+    public function test_it_can_override_charset(): void
+    {
+        $xml = '<hello>héllo</hello>';
+        $loader = xml_string_loader($xml, override_encoding: 'ASCII');
+        $doc = $loader();
+
+        static::assertSame('<hello>héllo</hello>', $doc->saveXML($doc->documentElement));
+        static::assertSame('ASCII', $doc->encoding);
+    }
 }