feat: added parameter-less constructors for element classes, allow cross-document appending, improve test coverage

Author: vardumper

README.md

@@ -32,14 +32,13 @@ composer require --dev vardumper/extended-htmldocument
 
 ## TL;DR
 
-This library adds the HTML5 specification to PHP and is fully compatible with `DOM\HTMLDocument`. You can create an `Anchor()` object and append it to any `DOM\Document`.
+This library adds the HTML5 specification to PHP and is fully compatible with `DOM\HTMLDocument`. You can now instantiate an `Anchor` without passing a document.
 
 ```php
-use Html\Delegator\HTMLDocumentDelegator as HTMLDocument;
 use Html\Element\Inline\Anchor;
+use Html\Enum\RelEnum;
 
-$dom = HTMLDocument::createEmpty()
-echo (string) Anchor::create($dom)
+echo (new Anchor())
     ->setClass('secondary')
     ->setRel(RelEnum::NOFOLLOW)
     ->setHref('https://google.com')

clover.xml

@@ -8,14 +8,13 @@ There are several different ways one can use this library in Symfony. One can:
 
 ## Using the HTML5 Element PHP classes and Enums
 
-This library adds the HTML5 specification to PHP and is fully compatible with `DOM\HTMLDocument`. You can create an `Anchor()` object and append it to any `DOM\Document`.
+This library adds the HTML5 specification to PHP and is fully compatible with `DOM\HTMLDocument`. You can now instantiate an `Anchor` without passing a document.
 
 ```php
-use Html\Delegator\HTMLDocumentDelegator as HTMLDocument;
 use Html\Element\Inline\Anchor;
+use Html\Enum\RelEnum;
 
-$dom = HTMLDocument::createEmpty()
-echo (string) Anchor::create($dom)
+echo (new Anchor())
     ->setClass('secondary')
     ->setRel(RelEnum::NOFOLLOW)
     ->setHref('https://google.com')

docs/frameworks/symfony.md

@@ -8,11 +8,10 @@ composer require vardumper/extended-htmldocument
 ## Use in PHP DOM\HTMLDocument
 
 ```php
-use Html\Delegator\HTMLDocumentDelegator as HTMLDocument;
 use Html\Element\Inline\Anchor;
+use Html\Enum\RelEnum;
 
-$dom = HTMLDocument::createEmpty()
-echo (string) Anchor::create($dom)
+echo (new Anchor())
     ->setClass('secondary')
     ->setRel(RelEnum::NOFOLLOW)
     ->setHref('https://google.com')

docs/frameworks/yii.md

@@ -11,8 +11,7 @@ composer require --dev vardumper/extended-htmldocument
 
 ```php [This library]
 // Extended HTMLDocument library
-$dom = \Html\Delegator\HTMLDocumentDelegator::createEmpty();
-echo (string) (\Html\Element\Inline\Anchor::create($dom))
+echo (new \Html\Element\Inline\Anchor())
   ->setHref('https://example.com')
   ->setTitle('Some info about the link')
   ->setRel('nofollow')

docs/getting-started.md

@@ -12,12 +12,10 @@ tbd add a gif
 This part is currently work in progress. The information below might be outdated, incomplete or incorrect.
 :::
 
-### Creation via `create()` method
+### Creation via constructor
 
 ```php{4}
-$dom = Html\Delegator\HTMLDocumentDelegator::createEmpty();
-
-$anchor = Html\Element\Inline\Anchor::create($dom);
+$anchor = new Html\Element\Inline\Anchor();
 $anchor->textContent = 'This is a test link.';
 $anchor->setAttributes([
     'href' => 'https://www.example.com',
@@ -28,7 +26,7 @@ echo $anchor;
 // or: $anchor->__toString();
 ```
 
-In the example above, we're passing an instance of the HTMLDocumentDelegator to the create method, which  we make use of three new methods HTMLElementDelegator `create()`, `setAttributes()` and `__toString()` as well as BackedEnums for static values.
+In the example above, we instantiate the element directly and make use of `setAttributes()` and `__toString()` as well as BackedEnums for static values.
 
 The output will be this:
 ```html{4}

docs/usage-examples.md

@@ -57,10 +57,24 @@ class HTMLElementDelegator implements HTMLElementDelegatorInterface
 
     public static array $parentOf = []; // Default value, change as needed
 
+    public HTMLElement|Element $delegated;
+
     public function __construct(
-        public readonly HTMLElement|Element $delegated,
+        HTMLElement|Element|null $delegated = null,
         public ?TemplateGeneratorInterface $renderer = null
     ) {
+        if ($delegated === null) {
+            if (! \defined(static::class . '::QUALIFIED_NAME')) {
+                throw new InvalidArgumentException(
+                    'Cannot instantiate ' . self::class . ' without a delegated node; instantiate a concrete Html\\Element\\* class instead.'
+                );
+            }
+            $document = HTMLDocumentDelegator::createEmpty();
+            static::$ownerDocument = $document;
+            $delegated = $document->delegated->createElement(static::getQualifiedName());
+        }
+
+        $this->delegated = $delegated;
         if ($renderer !== null && ! $renderer->canRenderElements()) {
             throw new InvalidArgumentException('The given renderer cannot render elements.');
         }
@@ -132,10 +146,19 @@ public function appendChild(HTMLElementDelegatorInterface|TextDelegator $child):
         // }
 
         if ($child->getOwnerDocument() !== $this->getOwnerDocument()) {
-            /** @todo the child could be imported here */
-            throw new InvalidArgumentException(
-                'The child element must belong to the same document as the parent element.'
-            );
+            $owner = $this->delegated->ownerDocument;
+            if (! $owner instanceof \DOM\HTMLDocument) {
+                throw new RuntimeException('No owner document available for this element.');
+            }
+
+            $imported = $owner->importNode($child->delegated, true);
+            $this->delegated->appendChild($imported);
+
+            if ($child instanceof self && ($imported instanceof \DOM\HTMLElement || $imported instanceof Element)) {
+                $child->delegated = $imported;
+            }
+
+            return $this;
         }
 
         $this->delegated->appendChild($child->delegated);
@@ -144,8 +167,21 @@ public function appendChild(HTMLElementDelegatorInterface|TextDelegator $child):
 
     public function removeChild(HTMLElementDelegatorInterface|TextDelegatorInterface|Text $child): static
     {
-        if (! \property_exists($child, 'ownerDocument')) {
-            throw new Exception('The child element must be an instance of HTMLElementDelegatorInterface or Text.');
+        if ($child instanceof Text) {
+            $owner = $child->ownerDocument;
+            if (! $owner instanceof \DOM\HTMLDocument) {
+                throw new RuntimeException('No owner document available for this text node.');
+            }
+
+            if (HTMLDocumentDelegator::getInstance($owner) !== $this->getOwnerDocument()) {
+                /** @todo the child could be imported here */
+                throw new InvalidArgumentException(
+                    'The child element must belong to the same document as the parent element.'
+                );
+            }
+
+            $this->delegated->removeChild($child);
+            return $this;
         }
 
         if ($child->getOwnerDocument() !== $this->getOwnerDocument()) {
@@ -154,15 +190,8 @@ public function removeChild(HTMLElementDelegatorInterface|TextDelegatorInterface
                 'The child element must belong to the same document as the parent element.'
             );
         }
-        if ($child instanceof HTMLElementDelegatorInterface) {
-            $this->delegated->removeChild($child->delegated);
-            return $this;
-        }
-        if ($child instanceof TextDelegatorInterface) {
-            $this->delegated->removeChild($child->delegated);
-            return $this;
-        }
-        $this->delegated->removeChild($child);
+
+        $this->delegated->removeChild($child->delegated);
         return $this;
     }
 

src/Delegator/HTMLElementDelegator.php

@@ -16,7 +16,7 @@
  */
 interface HTMLElementDelegatorInterface
 {
-    public function __construct(HTMLElement $delegated, ?TemplateGeneratorInterface $renderer = null);
+    public function __construct(HTMLElement|\Dom\Element|null $delegated = null, ?TemplateGeneratorInterface $renderer = null);
 
     public function __call($name, $arguments);
 

src/Interface/HTMLElementDelegatorInterface.php

@@ -12,14 +12,25 @@
 use Html\TemplateGenerator\HTMLGenerator;
 
 beforeEach(function () {
-    $this->document = HTMLDocumentDelegator::createEmpty();
-    $this->delegator = Anchor::create($this->document);
+    $this->delegator = new Anchor();
+    $this->document = $this->delegator->getOwnerDocument();
 });
 
 test('constructor', function () {
     expect($this->delegator)->toBeInstanceOf(HTMLElementDelegator::class);
 });
 
+test('can be instantiated without providing a document', function () {
+    $anchor = new Anchor();
+
+    expect($anchor)->toBeInstanceOf(Anchor::class);
+    expect(strtolower($anchor->delegated->tagName))->toBe('a');
+    expect($anchor->getOwnerDocument())->toBeInstanceOf(HTMLDocumentDelegator::class);
+
+    $anchor->setHref('https://example.com');
+    expect($anchor->getHref())->toBe('https://example.com');
+});
+
 test('call get global attribute', function () {
     $this->delegator->setAttribute('id', 'test');
     expect($this->delegator->getAttribute('id'))
@@ -376,6 +387,27 @@
         ->toBe(0);
 });
 
+test('removeChild can remove TextDelegator', function () {
+    $text = $this->document->createTextNode('hello');
+
+    $this->delegator->appendChild($text);
+    expect($this->delegator->delegated->textContent)->toBe('hello');
+
+    $this->delegator->removeChild($text);
+    expect($this->delegator->delegated->textContent)->toBe('');
+});
+
+test('removeChild can remove native DOM\\Text', function () {
+    $textDelegator = $this->document->createTextNode('raw');
+    $nativeText = $textDelegator->delegated;
+
+    $this->delegator->delegated->appendChild($nativeText);
+    expect($this->delegator->delegated->textContent)->toBe('raw');
+
+    $this->delegator->removeChild($nativeText);
+    expect($this->delegator->delegated->textContent)->toBe('');
+});
+
 test('replace child', function () {
     $child1 = Anchor::create($this->document);
     $child1->setTextContent('Original');
@@ -457,14 +489,19 @@ public function render($elementOrDocument): ?string
         ->toEqual(RelEnum::NOFOLLOW);
 });
 
-test('append child throws exception for different document', function () {
+test('append child imports node for different document', function () {
     $otherDocument = HTMLDocumentDelegator::createEmpty();
-    $child = Anchor::create($otherDocument);
-
-    $this->expectException(InvalidArgumentException::class);
-    $this->expectExceptionMessage('The child element must belong to the same document as the parent element.');
+    $child = $otherDocument->createElement('span');
+    $child->setTextContent('import-me');
 
     $this->delegator->appendChild($child);
+
+    expect($child->getOwnerDocument())
+        ->toBe($this->document);
+    expect($this->delegator->delegated->childNodes->length)
+        ->toBe(1);
+    expect($this->delegator->delegated->firstChild)
+        ->toBe($child->delegated);
 });
 
 test('remove child throws exception for different document', function () {

tests/Delegator/HTMLElementDelegatorTest.php

@@ -4,6 +4,8 @@
 use Html\Delegator\HTMLDocumentDelegator;
 use Html\Delegator\HTMLElementDelegator;
 use Html\Delegator\NodeDelegator;
+use Html\Element\Block\ListItem;
+use Html\Element\Block\UnorderedList;
 use Html\Element\Inline\Anchor;
 use Html\Element\Inline\Input;
 use Html\Element\InlineElement;
@@ -82,6 +84,36 @@
         ->toBeInstanceOf(HTMLElement::class);
 });
 
+test('appending an element created with its own document to a different document imports the node', function () {
+    $ul = UnorderedList::create($this->document);
+
+    $li = new ListItem();
+    $li->setTextContent('Item 1');
+
+    $ul->appendChild($li);
+
+    expect($li->getOwnerDocument())
+        ->toBe($this->document);
+    expect((string) $ul)
+        ->toBe('<ul><li>Item 1</li></ul>');
+});
+
+test('unordered list can accept list items from the same document', function () {
+    $ul = UnorderedList::create($this->document);
+
+    $li1 = ListItem::create($this->document);
+    $li1->setTextContent('One');
+    $li2 = ListItem::create($this->document);
+    $li2->setTextContent('Two');
+
+    $ul->appendChild($li1);
+    $ul->appendChild($li2);
+
+    expect($ul->delegated->childNodes->length)->toBe(2);
+    expect(strtolower($ul->delegated->firstChild->nodeName))->toBe('li');
+    expect((string) $ul)->toBe('<ul><li>One</li><li>Two</li></ul>');
+});
+
 test('setting properties via Setter', function () {
     $input = Input::create($this->document);
     $input->setType('text');