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

@@ -3,7 +3,7 @@
     errorLevel="1"
     resolveFromConfigFile="true"
     strictBinaryOperands="true"
-    phpVersion="8.1"
+    phpVersion="8.3"
     allowStringToStandInForClass="true"
     rememberPropertyAssignmentsAfterCall="false"
     skipChecksOnUnresolvableIncludes="false"

psalm.xml

@@ -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 $loader
+ *
+ * @return Closure(\Dom\XMLDocument): \Dom\XMLDocument
+ */
+function loader(callable $loader): Closure
+{
+    return static function () 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

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

tests/Xml/Dom/Configurator/LoaderTest.php

@@ -9,6 +9,7 @@
 use VeeWee\Tests\Xml\Helper\FillFileTrait;
 use VeeWee\Xml\Exception\RuntimeException;
 use function VeeWee\Xml\Dom\Loader\xml_file_loader;
+use function VeeWee\Xml\Dom\Loader\xml_string_loader;
 
 final class XmlFileLoaderTest extends TestCase
 {
@@ -60,4 +61,17 @@ public function test_it_throws_exception_on_invalid_file(): void
 
         $loader();
     }
+
+    public function test_it_can_override_charset(): void
+    {
+        $xml = '<?xml version="1.0" encoding="UTF-8"?><hello>héllo</hello>';
+        [$file, $handle] = $this->fillFile($xml);
+        $loader = xml_file_loader($file, override_encoding: 'Windows-1252');
+
+        $doc = $loader();
+        fclose($handle);
+
+        static::assertSame('héllo', $doc->documentElement->textContent);
+        static::assertSame('Windows-1252', $doc->xmlEncoding);
+    }
 }

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 = '<?xml version="1.0" encoding="UTF-8"?><hello>héllo</hello>';
+        $loader = xml_string_loader($xml, override_encoding: 'Windows-1252');
+        $doc = $loader();
+
+        static::assertSame('héllo', $doc->documentElement->textContent);
+        static::assertSame('Windows-1252', $doc->xmlEncoding);
+    }
 }