Migrate DOM-classes to PHP 8.4's new DOM-API

README.md

@@ -60,7 +60,7 @@ objects will look like the following:
 ```php
 namespace MyNamespace;
 
-use DOMElement;
+use Dom;
 use SimpleSAML\XMLSecurity\XML\SignableElementInterface;
 use SimpleSAML\XMLSecurity\XML\SignableElementTrait;
 use SimpleSAML\XMLSecurity\XML\SignedElementInterface;
@@ -79,7 +79,7 @@ class MyObject implements SignableElementInterface, SignedElementInterface
     }
 
 
-    protected function getOriginalXML(): DOMElement
+    protected function getOriginalXML(): Dom\Element
     {
         // return the original XML, if any, or the XML generated by your object
     }
@@ -109,7 +109,7 @@ Then your object can extend from that:
 ```php
 namespace MyNamespace;
 
-use DOMElement;
+use Dom;
 use SimpleSAML\XMLSecurity\XML\SignableElementInterface;
 use SimpleSAML\XMLSecurity\XML\SignableElementTrait;
 use SimpleSAML\XMLSecurity\XML\SignedElementInterface;
@@ -129,20 +129,20 @@ class MyObject extends AbstractMyNSElement
     }
 
 
-    protected function getOriginalXML(): DOMElement
+    protected function getOriginalXML(): Dom\Element
     {
         // return the original XML, if any, or the XML generated by your object
     }
 
 
-    public static function fromXML(DOMElement $xml): object
+    public static function fromXML(Dom\Element $xml): object
     {
         // build an instance of your object based on an XML document
         // representing it
     }
 
 
-    public function toXML(DOMElement $parent = null): DOMElement
+    public function toXML(Dom\Element $parent = null): Dom\Element
     {
         // build an XML representation of your object
     }
@@ -180,7 +180,7 @@ implement support for signing your objects like this:
 [xml-common]: https://github.com/simplesamlphp/xml-common
 
 ```php
-    public function toXML(DOMElement $parent = null): DOMElement
+    public function toXML(Dom\Element $parent = null): Dom\Element
     {
         if ($this->signer !== null) {
             $signedXML = $this->doSign($this->getMyXML());
@@ -193,7 +193,7 @@ implement support for signing your objects like this:
 ```
 
 Note that you will need to implement a mechanism to obtain the actual
-`DOMElement` to sign. It could be a method itself, as depicted in this example,
+`Dom\Element` to sign. It could be a method itself, as depicted in this example,
 or it could be stored in a class property.
 
 At this point, your object is ready to be signed. You just need to create
@@ -424,7 +424,7 @@ implementation of `decrypt()` will be suitable for most use cases:
 So what did just happen here? `MyObject` is supposed to implement
 `ElementInterface`, right? That means it must implement a `fromXML()` static
 method that creates a new instance of the class based on what's passed to it as
-a `DOMElement` object. The `DOMElement` itself was created with help from the
+a `Dom\Element` object. The `Dom\Element` itself was created with help from the
 `DOMDocumentFactory` class, which in turn took the `string` result of calling
 the `decryptData()` method provided by the trait. And that's it, that might be
 all you need to decrypt your encrypted objects!

composer.json

@@ -44,7 +44,7 @@
         "ext-spl": "*",
 
         "simplesamlphp/assert": "~2.0",
-        "simplesamlphp/xml-common": "~2.8"
+        "simplesamlphp/xml-common": "dev-feature/dom-migration-php84"
     },
     "require-dev": {
         "simplesamlphp/simplesamlphp-test-framework": "~1.11"
@@ -62,5 +62,19 @@
             "simplesamlphp/composer-module-installer": true,
             "simplesamlphp/composer-xmlprovider-installer": true
         }
+    },
+    "scripts": {
+        "pre-commit": [
+            "vendor/bin/phpcs -p",
+            "vendor/bin/phpstan analyze -c phpstan.neon",
+            "vendor/bin/phpstan analyze -c phpstan-dev.neon",
+            "vendor/bin/phpunit --no-coverage --testdox"
+        ],
+        "tests": [
+            "vendor/bin/phpunit --no-coverage"
+        ],
+        "propose-fix": [
+            "vendor/bin/phpcs --report=diff"
+        ]
     }
 }

src/Exception/ReferenceValidationFailedException.php

@@ -7,7 +7,7 @@
 /**
  * Class ReferenceValidationFailedException
  *
- * This exception is thrown when we can't validate the signature against the referenced DOMDocument or DOMElement.
+ * This exception is thrown when we can't validate the signature against the referenced Dom\XMLDocument or Dom\Element.
  *
  * @package simplesamlphp/xml-security
  */

src/Exception/SignatureVerificationFailedException.php

@@ -7,7 +7,7 @@
 /**
  * Class SignatureVerificationFailedException
  *
- * This exception is thrown when we can't verify the signature for a given DOMDocument or DOMElement.
+ * This exception is thrown when we can't verify the signature for a given Dom\XMLDocument or Dom\Element.
  *
  * @package simplesamlphp/xml-security
  */

src/TestUtils/SignedElementTestTrait.php

@@ -4,7 +4,7 @@
 
 namespace SimpleSAML\XMLSecurity\TestUtils;
 
-use DOMDocument;
+use Dom;
 use SimpleSAML\XMLSchema\Type\Base64BinaryValue;
 use SimpleSAML\XMLSecurity\Alg\Signature\SignatureAlgorithmFactory;
 use SimpleSAML\XMLSecurity\Constants as C;
@@ -37,7 +37,7 @@ trait SignedElementTestTrait
     /**
      * A base document that we can reuse in our tests.
      */
-    protected static DOMDocument $xmlRepresentation;
+    protected static Dom\XMLDocument $xmlRepresentation;
 
     /**
      * The name of the class we are testing.
@@ -60,7 +60,7 @@ public function testSignatures(): void
         } elseif (empty(self::$xmlRepresentation)) {
             $this->markTestSkipped(
                 'Unable to run ' . self::class . '::testSignatures(). Please set ' . self::class
-                . ':$xmlRepresentation to a DOMDocument representing the XML-class being tested',
+                . ':$xmlRepresentation to a Dom\XMLDocument representing the XML-class being tested',
             );
         } else {
             $algorithms = array_keys(C::$RSA_DIGESTS);

src/Utils/XPath.php

@@ -4,8 +4,7 @@
 
 namespace SimpleSAML\XMLSecurity\Utils;
 
-use DOMNode;
-use DOMXPath;
+use Dom;
 use SimpleSAML\XMLSecurity\Constants as C;
 use SimpleSAML\XPath\XPath as XPathUtils;
 
@@ -17,15 +16,15 @@
 class XPath extends XPathUtils
 {
     /**
-     * Get a DOMXPath object that can be used to search for XMLDSIG elements.
+     * Get a Dom\XPath object that can be used to search for XMLDSIG elements.
      *
-     * @param \DOMNode $node The document to associate to the DOMXPath object.
+     * @param \Dom\Node $node The document to associate to the Dom\XPath object.
      * @param bool $autoregister Whether to auto-register all namespaces used in the document
      *
-     * @return \DOMXPath A DOMXPath object ready to use in the given document, with the XMLDSIG namespace already
+     * @return \Dom\XPath A \Dom\XPath object ready to use in the given document, with the XMLDSIG namespace already
      * registered.
      */
-    public static function getXPath(DOMNode $node, bool $autoregister = false): DOMXPath
+    public static function getXPath(Dom\Node $node, bool $autoregister = false): Dom\XPath
     {
         $xp = parent::getXPath($node, $autoregister);
 

src/XML/CanonicalizableElementTrait.php

@@ -4,7 +4,7 @@
 
 namespace SimpleSAML\XMLSecurity\XML;
 
-use DOMElement;
+use Dom;
 use SimpleSAML\XMLSecurity\Assert\Assert;
 use SimpleSAML\XMLSecurity\Constants as C;
 use SimpleSAML\XMLSecurity\Exception\CanonicalizationFailedException;
@@ -21,20 +21,20 @@
 trait CanonicalizableElementTrait
 {
     /**
-     * This trait uses the php DOM extension. As such, it requires you to keep track (or produce) the DOMElement
+     * This trait uses the php DOM extension. As such, it requires you to keep track (or produce) the Dom\Element
      * necessary to perform the canonicalisation.
      *
-     * Implement this method to return the DOMElement with the proper representation of this object. Whatever is
+     * Implement this method to return the Dom\Element with the proper representation of this object. Whatever is
      * returned here will be used both to perform canonicalisation and to serialize the object, so that it can be
      * recovered later in its exact original state.
      */
-    abstract protected function getOriginalXML(): DOMElement;
+    abstract protected function getOriginalXML(): Dom\Element;
 
 
     /**
      * Canonicalize any given node.
      *
-     * @param \DOMElement $element The DOM element that needs canonicalization.
+     * @param \Dom\Element $element The DOM element that needs canonicalization.
      * @param string $c14nMethod The identifier of the canonicalization algorithm to use.
      *   See \SimpleSAML\XMLSecurity\Constants.
      * @param array<mixed>|null $xpaths An array of xpaths to filter the nodes by. Defaults to null (no filters).
@@ -44,7 +44,7 @@ abstract protected function getOriginalXML(): DOMElement;
      * @return string The canonical representation of the given DOM node, according to the algorithm requested.
      */
     public function canonicalizeData(
-        DOMElement $element,
+        Dom\Element $element,
         string $c14nMethod,
         ?array $xpaths = null,
         ?array $prefixes = null,
@@ -111,15 +111,15 @@ public function canonicalize(string $method, ?array $xpaths = null, ?array $pref
      * Process all transforms specified by a given Reference element.
      *
      * @param \SimpleSAML\XMLSecurity\XML\ds\Transforms $transforms The transforms to apply.
-     * @param \DOMElement $data The data referenced.
+     * @param \Dom\Element $data The data referenced.
      *
      * @return string The canonicalized data after applying all transforms specified by $ref.
      *
      * @see http://www.w3.org/TR/xmldsig-core/#sec-ReferenceProcessingModel
      */
     public function processTransforms(
         Transforms $transforms,
-        DOMElement $data,
+        Dom\Element $data,
     ): string {
         Assert::maxCount(
             $transforms->getTransform(),
@@ -162,8 +162,10 @@ public function processTransforms(
                         );
 
                         foreach ($nslist as $nsnode) {
-                            if ($nsnode->localName != "xml") {
-                                $arXPath['namespaces'][$nsnode->localName] = $nsnode->nodeValue;
+                            if ($nsnode instanceof Dom\Element) {
+                                if ($nsnode->localName !== "xml") {
+                                    $arXPath['namespaces'][$nsnode->localName] = $nsnode->nodeValue;
+                                }
                             }
                         }
                     }
@@ -183,6 +185,8 @@ public function processTransforms(
     public function __serialize(): array
     {
         $xml = $this->getOriginalXML();
-        return [$xml->ownerDocument->saveXML($xml)];
+        /** @var \Dom\XMLDocument $ownerDocument */
+        $ownerDocument = $xml->ownerDocument;
+        return [$ownerDocument->saveXML($xml)];
     }
 }

src/XML/EncryptedElementTrait.php

@@ -4,7 +4,7 @@
 
 namespace SimpleSAML\XMLSecurity\XML;
 
-use DOMElement;
+use Dom;
 use SimpleSAML\Assert\Assert;
 use SimpleSAML\XML\AbstractElement;
 use SimpleSAML\XMLSchema\Exception\InvalidDOMElementException;
@@ -171,7 +171,7 @@ protected function decryptData(EncryptionAlgorithmInterface $decryptor): string
      * @throws \SimpleSAML\XML\Exception\InvalidDOMElementException
      *   If the qualified name of the supplied element is wrong
      */
-    public static function fromXML(DOMElement $xml): static
+    public static function fromXML(Dom\Element $xml): static
     {
         Assert::same(
             $xml->localName,
@@ -198,7 +198,7 @@ public static function fromXML(DOMElement $xml): static
     /**
      * @inheritDoc
      */
-    public function toXML(?DOMElement $parent = null): DOMElement
+    public function toXML(?Dom\Element $parent = null): Dom\Element
     {
         $e = $this->instantiateParentElement($parent);
         $this->encryptedData->toXML($e);
@@ -212,9 +212,9 @@ public function toXML(?DOMElement $parent = null): DOMElement
      * The AbstractElement class implements this method. If your object inherits from that class, you will already
      * have this method out of the box.
      *
-     * @param \DOMElement|null $parent The element we should append to.
+     * @param \Dom\Element|null $parent The element we should append to.
      */
-    abstract public function instantiateParentElement(?DOMElement $parent = null): DOMElement;
+    abstract public function instantiateParentElement(?Dom\Element $parent = null): Dom\Element;
 
 
     /**

src/XML/SignableElementTrait.php

@@ -4,7 +4,7 @@
 
 namespace SimpleSAML\XMLSecurity\XML;
 
-use DOMElement;
+use Dom;
 use SimpleSAML\Assert\Assert;
 use SimpleSAML\XML\DOMDocumentFactory;
 use SimpleSAML\XMLSchema\Type\AnyURIValue;
@@ -103,7 +103,7 @@ public function sign(
     private function getReference(
         string $digestAlg,
         Transforms $transforms,
-        DOMElement $xml,
+        Dom\Element $xml,
         string $canonicalDocument,
     ): Reference {
         $id = $this->getId();
@@ -150,21 +150,21 @@ private function getReference(
     /**
      * Do the actual signing of the document.
      *
-     * Note that this method does not insert the signature in the returned \DOMElement. The signature will be available
+     * Note that this method does not insert the signature in the returned \Dom\Element. The signature will be available
      * in $this->signature as a \SimpleSAML\XMLSecurity\XML\ds\Signature object, which can then be converted to XML
-     * calling toXML() on it, passing the \DOMElement value returned here as a parameter. The resulting \DOMElement
+     * calling toXML() on it, passing the \Dom\Element value returned here as a parameter. The resulting \Dom\Element
      * can then be inserted in the position desired.
      *
      * E.g.:
      *     $xml = // our XML to sign
      *     $signedXML = $this->doSign($xml);
      *     $signedXML->appendChild($this->signature->toXML($signedXML));
      *
-     * @param \DOMElement $xml The element to sign.
-     * @return \DOMElement The signed element, without the signature attached to it just yet.
+     * @param \Dom\Element $xml The element to sign.
+     * @return \Dom\Element The signed element, without the signature attached to it just yet.
      */
     #[\NoDiscard]
-    protected function doSign(DOMElement $xml): DOMElement
+    protected function doSign(Dom\Element $xml): Dom\Element
     {
         Assert::notNull(
             $this->signer,
@@ -208,6 +208,7 @@ protected function doSign(DOMElement $xml): DOMElement
                 $this->keyInfo,
             ),
         );
+
         return DOMDocumentFactory::fromString($canonicalDocument)->documentElement;
     }
 

src/XML/SignedElementTrait.php

@@ -4,7 +4,7 @@
 
 namespace SimpleSAML\XMLSecurity\XML;
 
-use DOMElement;
+use Dom;
 use SimpleSAML\Assert\Assert;
 use SimpleSAML\XML\DOMDocumentFactory;
 use SimpleSAML\XMLSchema\Exception\TooManyElementsException;
@@ -87,7 +87,7 @@ protected function setSignature(Signature $signature): void
     /**
      * Make sure the given Reference points to the original XML given.
      */
-    private function validateReferenceUri(Reference $reference, DOMElement $xml): void
+    private function validateReferenceUri(Reference $reference, Dom\Element $xml): void
     {
         if (
             in_array(
@@ -142,7 +142,7 @@ private function validateReference(SignedInfo $signedInfo): SignedElementInterfa
             $this->validateReferenceUri($reference, $xml);
         }
 
-        // Clone the document so we don't mess up the original DOMDocument
+        // Clone the document so we don't mess up the original Dom\XMLDocument
         $doc = DOMDocumentFactory::create();
         $node = $doc->importNode($xml->ownerDocument->documentElement, true);
         $doc->appendChild($node);