PB-369: Integrate third party library to work with DOMDocument

 - update wrapper classes

Author: cspruiell

app/code/Magento/PageBuilder/Model/Dom/Adapter/AttrInterface.php

@@ -12,5 +12,10 @@
  */
 interface AttrInterface
 {
-    public function remove():self;
+    /**
+     * Removes attribute
+     *
+     * @return $this
+     */
+    public function remove(): self;
 }

app/code/Magento/PageBuilder/Model/Dom/Adapter/DocumentFragmentInterface.php

@@ -7,13 +7,16 @@
 
 namespace Magento\PageBuilder\Model\Dom\Adapter;
 
-use DOMNode;
-use RuntimeException;
-
 /**
  * Interface for DocumentFragment wrappers
  */
 interface DocumentFragmentInterface
 {
-    public function appendHTML(string $data):bool;
+    /**
+     * Appends the specified content to the document fragment
+     *
+     * @param string $data
+     * @return bool
+     */
+    public function appendHTML(string $data): bool;
 }

app/code/Magento/PageBuilder/Model/Dom/Adapter/DocumentInterface.php

@@ -15,16 +15,27 @@
  */
 interface DocumentInterface
 {
-    public function __toString():string;
+    /**
+     * Returns string representation of document
+     *
+     * @return string
+     */
+    public function __toString(): string;
 
-    public function saveHTML(DOMNode $node = null):string;
+    /**
+     * Dumps the internal document into a string using HTML formatting
+     *
+     * @param DOMNode|null $node
+     * @return string
+     */
+    public function saveHTML(DOMNode $node = null): string;
 
     /**
      * Closes the stream and any underlying resources.
      *
      * @return void
      */
-    public function close():void;
+    public function close(): void;
 
     /**
      * Separates any underlying resources from the stream.
@@ -40,29 +51,29 @@ public function detach();
      *
      * @return int|null Returns the size in bytes if known, or null if unknown.
      */
-    public function getSize():?int;
+    public function getSize(): ?int;
 
     /**
      * Returns the current position of the file read/write pointer
      *
      * @return int Position of the file pointer
      * @throws RuntimeException on error.
      */
-    public function tell():int;
+    public function tell(): int;
 
     /**
      * Returns true if the stream is at the end of the stream.
      *
      * @return bool
      */
-    public function eof():bool;
+    public function eof(): bool;
 
     /**
      * Returns whether or not the stream is seekable.
      *
      * @return bool
      */
-    public function isSeekable():bool;
+    public function isSeekable(): bool;
 
     /**
      * Seek to a position in the stream.
@@ -76,7 +87,7 @@ public function isSeekable():bool;
      *     SEEK_END: Set position to end-of-stream plus offset.
      * @throws RuntimeException on failure.
      */
-    public function seek($offset, $whence = SEEK_SET):void;
+    public function seek($offset, $whence = SEEK_SET): void;
 
     /**
      * Seek to the beginning of the stream.
@@ -88,14 +99,14 @@ public function seek($offset, $whence = SEEK_SET):void;
      * @link http://www.php.net/manual/en/function.fseek.php
      * @see seek()
      */
-    public function rewind():void;
+    public function rewind(): void;
 
     /**
      * Returns whether or not the stream is writable.
      *
      * @return bool
      */
-    public function isWritable():bool;
+    public function isWritable(): bool;
 
     /**
      * Write data to the stream.
@@ -104,14 +115,14 @@ public function isWritable():bool;
      * @return int Returns the number of bytes written to the stream.
      * @throws RuntimeException on failure.
      */
-    public function write($string):int;
+    public function write($string): int;
 
     /**
      * Returns whether or not the stream is readable.
      *
      * @return bool
      */
-    public function isReadable():bool;
+    public function isReadable(): bool;
 
     /**
      * Read data from the stream.
@@ -123,7 +134,7 @@ public function isReadable():bool;
      *     if no bytes are available.
      * @throws RuntimeException if an error occurs.
      */
-    public function read($length):string;
+    public function read($length): string;
 
     /**
      * Returns the remaining contents in a string
@@ -132,7 +143,7 @@ public function read($length):string;
      * @throws RuntimeException if unable to read or an error occurs while
      *     reading.
      */
-    public function getContents():string;
+    public function getContents(): string;
 
     /**
      * Get stream metadata as an associative array or retrieve a specific key.

app/code/Magento/PageBuilder/Model/Dom/Adapter/ElementInterface.php

@@ -7,43 +7,66 @@
 
 namespace Magento\PageBuilder\Model\Dom\Adapter;
 
-use Gt\Dom\Element;
-
 /**
  * Interface for Element wrappers
  */
 interface ElementInterface
 {
     /**
-     * returns true if the element would be selected by the specified selector
-     * string; otherwise, returns false.
+     * Returns true if the element would be selected by the specified selector string; otherwise, returns false.
+     *
      * @param string $selectors The CSS selector(s) to check against
      * @return bool True if this element is selectable by provided selector
      */
-    public function matches(string $selectors):bool;
+    public function matches(string $selectors): bool;
 
     /**
-     * Returns a live HTMLCollection containing all child elements which have all
-     * of the given class names. When called on the document object, the complete
-     * document is searched, including the root node.
+     * Returns a live HTMLCollection containing all child elements which have all of the given class names.
+     *
      * @param string $names a string representing the list of class names to
      *  match; class names are separated by whitespace
      * @return HtmlCollectionInterface
      */
-    public function getElementsByClassName(string $names):HtmlCollectionInterface;
+    public function getElementsByClassName(string $names): HtmlCollectionInterface;
 
     /**
-     * Returns the closest ancestor of the current element (or itself)
-     * which matches the selectors.
+     * Returns the closest ancestor of the current element (or itself) which matches the selectors.
+     *
      * @param string $selectors CSS selector(s)
      * @return ElementInterface|null
      */
     public function closest(string $selectors): ?ElementInterface;
 
     /**
      * Returns the value of the specified attribute
-     * @param $name
+     *
+     * @param string $name
      * @return string|null
      */
-    public function getAttribute($name):?string;
+    public function getAttribute($name): ?string;
+
+    /**
+     * Sets the value of the specified attribute
+     *
+     * @param string $name
+     * @param string $value
+     * @return AttrInterface|null
+     */
+    public function setAttribute($name, $value): ?AttrInterface;
+
+    /**
+     * Returns the first element matching the specified selector.
+     *
+     * @param string $selector
+     * @return HtmlCollectionInterface
+     */
+    public function querySelector(string $selector): ElementInterface;
+
+    /**
+     * Returns all elements matching the specified selector.
+     *
+     * @param string $selector
+     * @return HtmlCollectionInterface
+     */
+    public function querySelectorAll(string $selector): HtmlCollectionInterface;
 }

app/code/Magento/PageBuilder/Model/Dom/Adapter/HtmlCollectionInterface.php

@@ -12,35 +12,92 @@
  */
 interface HtmlCollectionInterface
 {
-	/**
-     * Returns the specific Node whose ID or, as a fallback,
-     * name matches the string specified by $name. Matching by name is only done
-     * as a last resort, and only if the referenced element supports the name
-     * attribute.
+    /**
+     * Returns the specific Node whose ID or, as a fallback, name matches the string specified by $name.
+     *
      * @param string $name
      * @return ElementInterface
      */
     public function namedItem(string $name): ?ElementInterface;
 
+    /**
+     * Gets the nth Element object in the internal DOMNodeList.
+     *
+     * @param int $index
+     * @return ElementInterface|null
+     */
     public function item(int $index): ?ElementInterface;
 
+    /**
+     * Resets the internal pointer to the beginning of the collection
+     *
+     * @return void
+     */
     public function rewind(): void;
 
+    /**
+     * Returns the current index key value
+     *
+     * @return int
+     */
     public function key(): int;
 
+    /**
+     * Returns true if the current index key is valid
+     *
+     * @return bool
+     */
     public function valid(): bool;
 
+    /**
+     * Advances the iterator one position forward
+     *
+     * @return void
+     */
     public function next(): void;
 
+    /**
+     * Returns the element currently being pointed to by the iterator
+     *
+     * @return ElementInterface|null
+     */
     public function current(): ?ElementInterface;
 
+    /**
+     * Returns true if the specified offset points to a value in the collection, false otherwise.
+     *
+     * @param int $offset
+     * @return bool
+     */
     public function offsetExists($offset): bool;
 
+    /**
+     * Returns the item in the $offset position in the collection
+     *
+     * @param int $offset
+     * @return ElementInterface|null
+     */
     public function offsetGet($offset): ?ElementInterface;
 
+    /**
+     * Attempts to set the specified value in the $offset position of the collection
+     *
+     * @param int $offset
+     * @param string $value
+     */
     public function offsetSet($offset, $value): void;
 
+    /**
+     * Attempts to unset the item in the specified offset of the collection
+     *
+     * @param int $offset
+     */
     public function offsetUnset($offset): void;
 
+    /**
+     * Returns the number of items in the collection
+     *
+     * @return int
+     */
     public function count(): int;
 }

app/code/Magento/PageBuilder/Model/Dom/Adapter/HtmlDocumentInterface.php

@@ -14,8 +14,32 @@ interface HtmlDocumentInterface
 {
     /**
      * Returns collection of elements matching the specified class names
+     *
      * @param string $names
      * @return HtmlCollectionInterface
      */
-    public function getElementsByClassName(string $names):HtmlCollectionInterface;
+    public function getElementsByClassName(string $names): HtmlCollectionInterface;
+
+    /**
+     * Returns the first element matching the specified selector.
+     *
+     * @param string $selector
+     * @return HtmlCollectionInterface
+     */
+    public function querySelector(string $selector): ElementInterface;
+
+    /**
+     * Returns all elements matching the specified selector.
+     *
+     * @param string $selector
+     * @return HtmlCollectionInterface
+     */
+    public function querySelectorAll(string $selector): HtmlCollectionInterface;
+
+    /**
+     * Dumps the internal document into a string using HTML formatting
+     *
+     * @return string
+     */
+    public function saveHTML(): string;
 }