Helper class that provides missing DOM level 3 methods for the PHP DOM classes. More...

Static Public Member Functions
static	isStandardsMode ( $node=null)

static	isUsingDodo ( $node=null)

static	isUsing84Dom ( $node=null)

static	newDocument (bool $isHtml=true)
	Create a new empty HTML document using the preferred DOM implementation.

static	getTitle ( $document)
	Get document title.

static	setTitle ( $document, string $title)
	Set document title.

static	getElementById (DOMDocument\|DOMDocumentFragment\|Document\|DocumentFragment $node, string $id)
	Return the descendant with the specified ID.

static	setIdAttribute ( $element, string $id)
	Workaround bug in PHP's Document::getElementById() which doesn't actually index the 'id' attribute unless you use the non-standard `Element::setIdAttribute` method after the attribute is set; see https://www.php.net/manual/en/domdocument.getelementbyid.php for more details.

static	getElementsByTagName (DOMDocument\|DOMElement\|Document\|Element $node, string $tagName)
	Return all descendants with the specified tag name.

static	getFirstElementChild (DOMDocument\|DOMDocumentFragment\|DOMElement\|Document\|DocumentFragment\|Element $node)
	Return the first child of the node that is an Element, or null otherwise.

static	getLastElementChild (DOMDocument\|DOMDocumentFragment\|DOMElement\|Document\|DocumentFragment\|Element $node)
	Return the last child of the node that is an Element, or null otherwise.

static	querySelector ( $node, string $selector)

static	querySelectorAll (DOMDocument\|DOMDocumentFragment\|DOMElement\|Document\|DocumentFragment\|Element $node, string $selector)

static	getPreviousElementSibling (DOMElement\|DOMCharacterData\|Element\|CharacterData $node)
	Return the last preceding sibling of the node that is an element, or null otherwise.

static	getNextElementSibling (DOMElement\|DOMCharacterData\|Element\|CharacterData $node)
	Return the first following sibling of the node that is an element, or null otherwise.

static	append (DOMDocument\|DOMDocumentFragment\|DOMElement\|Document\|DocumentFragment\|Element $parentNode, DOMNode\|Node\|string ... $nodes)
	Append the node to the parent node.

static	appendChild (DOMDocument\|DOMDocumentFragment\|DOMElement\|Document\|DocumentFragment\|Element $parentNode, DOMNode\|Node $node)
	Append a child node to the parent node.

static	remove (DOMElement\|DOMCharacterData\|Element\|CharacterData $node)
	Removes the node from the document.

static	getInnerHTML ( $element)
	Get innerHTML.

static	setInnerHTML ( $element, string $html)
	Set innerHTML.

static	getOuterHTML ( $element)
	Get outerHTML.

static	getAttribute ( $element, string $attributeName)
	Return the value of an element attribute.

static	attributes (Element $element)
	Get an associative array of attributes, suitable for serialization.

static	getClassList ( $node)
	Return the class list of this element.

static	normalize ( $elt)

static	replaceChildren (DOMDocument\|DOMDocumentFragment\|DOMElement\|Document\|DocumentFragment\|Element $parentNode, DOMNode\|Node\|string ... $nodes)
	ParentNode.replaceChildren() https://developer.mozilla.org/en-US/docs/Web/API/ParentNode/replaceChildren.

static	getTemplateElementContent ( $node)
	Return HTMLTemplateElement::content.

Detailed Description

Helper class that provides missing DOM level 3 methods for the PHP DOM classes.

For a DOM method $node->foo( $bar) the equivalent helper is DOMCompat::foo( $node, $bar ). For a DOM property $node->foo there is a DOMCompat::getFoo( $node ) and DOMCompat::setFoo( $node, $value ).

Only implements the methods that are actually used by Parsoid.

Because this class may be used by code outside Parsoid, it tries to be relatively tolerant of object types: you can call it either with PHP's DOM* types or with a "proper" DOM implementation, and it will attempt to Do The Right Thing regardless. As a result, there are generally not parameter type hints for DOM object types, and the return types will be broad enough to accomodate the value a "real" DOM implementation would return, as well as the values our thunk will return. (For instance, we can't create a "real" NodeList in our compatibility thunk.)

Exception to the above: ::nodeName method is not so much a DOM compatibility method in the sense above, but a proxy to let us support multiple DOM libraries against the Parsoid codebase that expects lower-case names. In this specific instance the default behavior is tailored for performance vs. being HTML-standards-compliant.

Member Function Documentation

◆ append()

static Wikimedia\Parsoid\Core\DOMCompat::append	(	DOMDocument\|DOMDocumentFragment\|DOMElement\|Document\|DocumentFragment\|Element	$parentNode,
		DOMNode\|Node\|string ...	$nodes )

static

Append the node to the parent node.

Parameters

Document \| DocumentFragment \| Element	$parentNode
	Node\|string	...$nodes

Note: This method was added in PHP 8.0.0

◆ appendChild()

static Wikimedia\Parsoid\Core\DOMCompat::appendChild	(	DOMDocument\|DOMDocumentFragment\|DOMElement\|Document\|DocumentFragment\|Element	$parentNode,
		DOMNode\|Node	$node )

static

Append a child node to the parent node.

Parameters

Document \| DocumentFragment \| Element	$parentNode
Node	$node

Returns: Node

Note: From T411228 et al, appending an empty Document Fragment results in a PHP warning. No longer necessary when isUsing84Dom is true.

◆ attributes()

static Wikimedia\Parsoid\Core\DOMCompat::attributes ( Element $element )

static

Get an associative array of attributes, suitable for serialization.

Add the xmlns attribute if available, to workaround PHP's surprising behavior with the xmlns attribute: HTML is not an XML document, but various parts of PHP pretend that it is, sort of.

Parameters

Element $element

Returns: array<string,string>

See also: https://phabricator.wikimedia.org/T235295; https://developer.mozilla.org/en-US/docs/Web/API/Element/attributes

Note: Note that unlike the spec this method returns an associative array, not a NamedNodeMap, and as such is not an exact replacement for the DOM attributes property.

◆ getAttribute()

static Wikimedia\Parsoid\Core\DOMCompat::getAttribute	(		$element,
		string	$attributeName )

static

Return the value of an element attribute.

Unlike PHP's version, this is spec-compliant and returns null if the attribute is not present, allowing the caller to distinguish between "the attribute exists but has the empty string as its value" and "the attribute does not exist".

Parameters

Element	$element
string	$attributeName

Returns: ?string The attribute value, or null if the attribute does not exist on the element.

See also: https://dom.spec.whatwg.org/#dom-element-getattribute

◆ getClassList()

static Wikimedia\Parsoid\Core\DOMCompat::getClassList ( $node )

static

Return the class list of this element.

Parameters

Element $node

Returns: TokenList

See also: https://dom.spec.whatwg.org/#dom-element-classlist

◆ getElementById()

static Wikimedia\Parsoid\Core\DOMCompat::getElementById	(	DOMDocument\|DOMDocumentFragment\|Document\|DocumentFragment	$node,
		string	$id )

static

Return the descendant with the specified ID.

Workaround for https://bugs.php.net/bug.php?id=77686 and other issues related to inconsistent indexing behavior. XXX: 77686 is fixed in php 8.1.21

Parameters

Document \| DocumentFragment	$node
string	$id

Returns: Element|null

See also: https://dom.spec.whatwg.org/#dom-nonelementparentnode-getelementbyid

◆ getElementsByTagName()

static Wikimedia\Parsoid\Core\DOMCompat::getElementsByTagName	(	DOMDocument\|DOMElement\|Document\|Element	$node,
		string	$tagName )

static

Return all descendants with the specified tag name.

Workaround for PHP's getElementsByTagName being inexplicably slow in some situations and the lack of Element::getElementsByTagName().

Parameters

Document \| Element	$node
string	$tagName

Returns: (iterable<Element>&\Countable)|array<Element> Either an array or an HTMLCollection object

See also: https://dom.spec.whatwg.org/#dom-document-getelementsbytagname; https://dom.spec.whatwg.org/#dom-element-getelementsbytagname

Note: Note that unlike the spec this method is not guaranteed to return a NodeList (which cannot be freely constructed in PHP), just a traversable containing Elements.

◆ getFirstElementChild()

static

Return the first child of the node that is an Element, or null otherwise.

Parameters

Document | DocumentFragment | Element $node

Returns: Element|null

See also: https://dom.spec.whatwg.org/#dom-parentnode-firstelementchild

Note: This property was added to PHP in 8.0.0, and won't be needed once our minimum required version >= 8.0.0

◆ getInnerHTML()

static Wikimedia\Parsoid\Core\DOMCompat::getInnerHTML ( $element )

static

Get innerHTML.

See also: DOMUtils::getFragmentInnerHTML() for the fragment version

Parameters

Element $element

Returns: string

See also: https://w3c.github.io/DOM-Parsing/#dom-innerhtml-innerhtml

◆ getLastElementChild()

static

Return the last child of the node that is an Element, or null otherwise.

Parameters

Document | DocumentFragment | Element $node

Returns: Element|null

See also: https://dom.spec.whatwg.org/#dom-parentnode-lastelementchild

Note: This property was added to PHP in 8.0.0, and won't be needed once our minimum required version >= 8.0.0

◆ getNextElementSibling()

static Wikimedia\Parsoid\Core\DOMCompat::getNextElementSibling ( DOMElement|DOMCharacterData|Element|CharacterData $node )

static

Return the first following sibling of the node that is an element, or null otherwise.

Parameters

Element | CharacterData $node

Returns: Element|null

See also: https://dom.spec.whatwg.org/#dom-nondocumenttypechildnode-nextelementsibling

◆ getOuterHTML()

static Wikimedia\Parsoid\Core\DOMCompat::getOuterHTML ( $element )

static

Get outerHTML.

Parameters

Element $element

Returns: string

See also: https://w3c.github.io/DOM-Parsing/#dom-element-outerhtml

◆ getPreviousElementSibling()

static Wikimedia\Parsoid\Core\DOMCompat::getPreviousElementSibling ( DOMElement|DOMCharacterData|Element|CharacterData $node )

static

Return the last preceding sibling of the node that is an element, or null otherwise.

Parameters

Element | CharacterData $node

Returns: Element|null

See also: https://dom.spec.whatwg.org/#dom-nondocumenttypechildnode-previouselementsibling

◆ getTemplateElementContent()

static Wikimedia\Parsoid\Core\DOMCompat::getTemplateElementContent ( $node )

static

Return HTMLTemplateElement::content.

In the PHP DOM, <template> elements do not have a dedicated DocumentFragment and children are stored directly under the Element. In the HTML5 spec, the contents are stored in a DocumentFragment with a unique owner document.

Bridge this gap by returning the <template> element for PHP's DOM, or the DocumentFragment for an HTML5-compliant DOM.

Parameters

Element $node A <template> element

Returns: Element|DocumentFragment Either the element (for PHP compat) or the DocumentFragment which is the template's "content"

◆ getTitle()

static Wikimedia\Parsoid\Core\DOMCompat::getTitle ( $document )

static

Get document title.

Parameters

Document $document

Returns: string

See also: https://html.spec.whatwg.org/multipage/dom.html#document.title

◆ isStandardsMode()

static Wikimedia\Parsoid\Core\DOMCompat::isStandardsMode ( $node = null )

static

Parameters

Node | null $node If present, we'll use the type of the given node to determine whether to use standards mode.

Returns: bool When false, we'll use DOMDocument workarounds.

◆ isUsing84Dom()

static Wikimedia\Parsoid\Core\DOMCompat::isUsing84Dom ( $node = null )

static

Parameters

Node | null $node If present, we'll use the type of the given node to determine whether we're using the PHP 8.4 DOM implementation.

Returns: bool When true, we're using the PHP 8.4 DOM implementation.

◆ isUsingDodo()

static Wikimedia\Parsoid\Core\DOMCompat::isUsingDodo ( $node = null )

static

Parameters

Node | null $node If present, we'll use the type of the given node to determine whether we're using Dodo.

Returns: bool When true, we're using the Dodo DOM implementation.

◆ newDocument()

static Wikimedia\Parsoid\Core\DOMCompat::newDocument ( bool $isHtml = true )

static

Create a new empty HTML document using the preferred DOM implementation.

Parameters

bool $isHtml (optional) Should always be true.

Returns: Document

◆ normalize()

static Wikimedia\Parsoid\Core\DOMCompat::normalize ( $elt )

static

Parameters

Element | DocumentFragment $elt root of the DOM tree that needs to be normalized

◆ querySelector()

static Wikimedia\Parsoid\Core\DOMCompat::querySelector	(		$node,
		string	$selector )

static

Parameters

Document \| DocumentFragment \| Element	$node
string	$selector

Returns: Element|null

See also: https://dom.spec.whatwg.org/#dom-parentnode-queryselector

◆ querySelectorAll()

static Wikimedia\Parsoid\Core\DOMCompat::querySelectorAll	(	DOMDocument\|DOMDocumentFragment\|DOMElement\|Document\|DocumentFragment\|Element	$node,
		string	$selector )

static

Parameters

Document \| DocumentFragment \| Element	$node
string	$selector

Returns: (iterable<Element>&\Countable)|array<Element> Either a NodeList or an array

See also: https://dom.spec.whatwg.org/#dom-parentnode-queryselectorall

Note: Note that unlike the spec this method is not guaranteed to return a NodeList (which cannot be freely constructed in PHP), just a traversable containing Elements.

◆ remove()

static Wikimedia\Parsoid\Core\DOMCompat::remove ( DOMElement|DOMCharacterData|Element|CharacterData $node )

static

Removes the node from the document.

Parameters

Element | CharacterData $node

See also: https://dom.spec.whatwg.org/#dom-childnode-remove

◆ replaceChildren()

static Wikimedia\Parsoid\Core\DOMCompat::replaceChildren	(	DOMDocument\|DOMDocumentFragment\|DOMElement\|Document\|DocumentFragment\|Element	$parentNode,
		DOMNode\|Node\|string ...	$nodes )

static

ParentNode.replaceChildren() https://developer.mozilla.org/en-US/docs/Web/API/ParentNode/replaceChildren.

Parameters

Document \| DocumentFragment \| Element	$parentNode
	Node\|string	...$nodes

◆ setIdAttribute()

static Wikimedia\Parsoid\Core\DOMCompat::setIdAttribute	(		$element,
		string	$id )

static

Workaround bug in PHP's Document::getElementById() which doesn't actually index the 'id' attribute unless you use the non-standard Element::setIdAttribute method after the attribute is set; see https://www.php.net/manual/en/domdocument.getelementbyid.php for more details.

Parameters

Element	$element
string	$id	The desired value for the `id` attribute on $element.

See also: https://phabricator.wikimedia.org/T232390

◆ setInnerHTML()

static Wikimedia\Parsoid\Core\DOMCompat::setInnerHTML	(		$element,
		string	$html )

static

Set innerHTML.

See also: https://w3c.github.io/DOM-Parsing/#dom-innerhtml-innerhtml; DOMUtils::setFragmentInnerHTML() for the fragment version

Parameters

Element	$element
string	$html

◆ setTitle()

static Wikimedia\Parsoid\Core\DOMCompat::setTitle	(		$document,
		string	$title )

static

Set document title.

Parameters

Document	$document
string	$title

See also: https://html.spec.whatwg.org/multipage/dom.html#document.title

The documentation for this class was generated from the following file:

src/Core/DOMCompat.php

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ append()

◆ appendChild()

◆ attributes()

◆ getAttribute()

◆ getClassList()

◆ getElementById()

◆ getElementsByTagName()

◆ getFirstElementChild()

◆ getInnerHTML()

◆ getLastElementChild()

◆ getNextElementSibling()

◆ getOuterHTML()

◆ getPreviousElementSibling()

◆ getTemplateElementContent()

◆ getTitle()

◆ isStandardsMode()

◆ isUsing84Dom()

◆ isUsingDodo()

◆ newDocument()

◆ normalize()

◆ querySelector()

◆ querySelectorAll()

◆ remove()

◆ replaceChildren()

◆ setIdAttribute()

◆ setInnerHTML()

◆ setTitle()