Dodo
DOm DOcument implementation
Loading...
Searching...
No Matches
Wikimedia\Dodo\Node Class Reference
+ Inheritance diagram for Wikimedia\Dodo\Node:

Public Member Functions

 __construct (Document $nodeDocument)
 Create a Node whose node document is the given $nodeDocument.
 
int getNodeType ()
 Return the node type enumeration for this node.
 
string getNodeName ()
 Return the nodeName for this node.
 
string getNodeValue ()
 Return the value for this node.
 
 setNodeValue (?string $val)
 
string getTextContent ()
 Return the textContent for this node.
 
 setTextContent (?string $val)
 
Document getOwnerDocument ()
 The ownerDocument getter steps are to return null, if this is a document; otherwise this’s node document.
 
Node getParentNode ()
 Nodes might not have a parentNode.
 
Element getParentElement ()
 This value is the same as parentNode, except it puts an extra condition, that the parentNode must be an Element.
 
Wikimedia IDLeDOM Node getRootNode ($options=null)
 Return this' shadow-including root if options['composed'] is true; otherwise return this' root.
 
Node getPreviousSibling ()
 
Node getNextSibling ()
 
 getChildNodes ()
 This should be overridden in ContainerNode and Leaf.
 
 getFirstChild ()
 This should be overridden in ContainerNode and Leaf.
 
 getLastChild ()
 This should be overridden in ContainerNode and Leaf.
 
 _roothook ()
 <script> elements need to know when they're inserted into the document.
 
Node insertBefore ($node, $refNode=null)
 Insert $node as a child of $this, and insert it before $refChild in the document order.
 
 appendChild ( $node)
 
Node _unsafeAppendChild (Node $node)
 Does not check for insertion validity.
 
Node replaceChild ( $new, $old)
 
Node removeChild ( $node)
 
 normalize ()
 Puts $this and the entire subtree rooted at $this into "normalized" form.
 
int compareDocumentPosition ( $that)
 
bool contains ( $node)
 
bool isSameNode ( $node)
 
bool isEqualNode ( $node)
 Determine whether this node and $other are equal.
 
Node cloneNode (bool $deep=false)
 Clone this Node.
 
string lookupPrefix (?string $ns)
 Return DOMString containing prefix for given namespace URI.
 
string lookupNamespaceURI (?string $prefix)
 Return DOMString containing namespace URI for a given prefix.
 
bool isDefaultNamespace (?string $ns)
 Determine whether this is the default namespace.
 
string getNodePath ()
 Get an XPath for a node.
 
 _resetNodeDocument (Document $doc)
 Set the ownerDocument reference on a subtree rooted at $this.
 
bool getIsConnected ()
 Determine whether this Node is rooted (belongs to the tree rooted at the node document).
 
int _getSiblingIndex ()
 The index of this Node in its parent's childNodes list.
 
int _lastModTime ()
 Return the lastModTime value for this node.
 
 _modify ()
 Increment the owner document's modclock [and use the new value to update the lastModTime value for this node and all of its ancestors.
 
 _htmlSerialize (array &$result, array $options)
 Convert the children of a node to an HTML string.
 
 _xmlSerialize (?string $namespace, NamespacePrefixMap $prefixMap, int &$prefixIndex, array $options, array &$markup)
 XML serialize the given node.
 
int _length ()
 
bool _empty ()
 
mixed getExtensionData (string $key, $defaultValue=null)
 Get "extension data" associate with this node, using the given $key.
 
 setExtensionData (string $key, $value)
 Set "extension data" associate with this node, using the given $key.
 
- Public Member Functions inherited from Wikimedia::IDLeDOM::EventTarget
void addEventListener (string $type, $callback, $options=null)
 
void removeEventListener (string $type, $callback, $options=null)
 
bool dispatchEvent ( $event)
 
- Public Member Functions inherited from Wikimedia::IDLeDOM::Node
string getBaseURI ()
 
bool hasChildNodes ()
 

Public Attributes

Document $_nodeDocument
 The document this node is associated to.
 
Node null $_parentNode
 should be considered read-only
 
Node $_nextSibling
 The sibling list is stored as a circular linked list: the node "before" the first sibling is the last sibling, and the node "after" the last sibling is the first sibling.
 
Node $_previousSibling
 
int $_documentIndex = null
 DEVELOPERS NOTE: An index is assigned when a node is added to a Document (becomes rooted).
 
int $_cachedSiblingIndex = null
 DEVELOPERS NOTE: An index is assigned on INSERTION.
 

Protected Member Functions

bool _subclassIsEqualNode (Node $node)
 Delegated subclass method called by Node::isEqualNode()
 
Node _subclassCloneNodeShallow ()
 Delegated subclass method called by Node::cloneNode()
 
 _setMissingProp (string $name, $value)
 
 _getMissingProp (string $name)
 

Detailed Description

Node.php

Defines a "Node", the primary datatype of the W3C Document Object Model.

Conforms to W3C Document Object Model (DOM) Level 1 Recommendation (see: https://www.w3.org/TR/2000/WD-DOM-Level-1-20000929) -forbid-undeclared-magic-properties

Constructor & Destructor Documentation

◆ __construct()

Wikimedia\Dodo\Node::__construct ( Document  $nodeDocument)

Create a Node whose node document is the given $nodeDocument.

Parameters
Document$nodeDocument

Reimplemented in Wikimedia\Dodo\ContainerNode, and Wikimedia\Dodo\DocumentFragment.

Member Function Documentation

◆ _empty()

bool Wikimedia\Dodo\Node::_empty ( )
abstract

◆ _getMissingProp()

Wikimedia\Dodo\Node::_getMissingProp ( string  $name)
protected

◆ _getSiblingIndex()

int Wikimedia\Dodo\Node::_getSiblingIndex ( )

The index of this Node in its parent's childNodes list.

See also
https://dom.spec.whatwg.org/#concept-tree-index
Returns
int index
Exceptions

Throwable if we have no parent

NOTE Calling Node::_getSiblingIndex() will automatically trigger a switch to the NodeList representation (see Node::childNodes()).

◆ _htmlSerialize()

Wikimedia\Dodo\Node::_htmlSerialize ( array &  $result,
array  $options 
)

Convert the children of a node to an HTML string.

This is effectively 'innerHTML' for nodes in HTML documents. This is overridden in specific children, in particular HTMLTemplateElement.

See also
https://html.spec.whatwg.org/#html-fragment-serialisation-algorithm
Parameters
string[]&$resultThe result is accumulated here
array$optionsFormat options passed to WhatWG::htmlSerialize

Reimplemented in Wikimedia\Dodo\HTMLTemplateElement.

◆ _lastModTime()

int Wikimedia\Dodo\Node::_lastModTime ( )

Return the lastModTime value for this node.

(For use as a cache invalidation mechanism. If the node does not already have one, initialize it from the owner document's modclock property. (Note that modclock does not return the actual time; it is simply a counter incremented on each document modification.)

Returns
int

◆ _length()

int Wikimedia\Dodo\Node::_length ( )
abstract

◆ _modify()

Wikimedia\Dodo\Node::_modify ( )

Increment the owner document's modclock [and use the new value to update the lastModTime value for this node and all of its ancestors.

Nodes that have never had their lastModTime value queried do not need to have a lastModTime property set on them since there is no previously queried value to ever compare the new value against, so only update nodes that already have a _lastModTime property.]

◆ _resetNodeDocument()

Wikimedia\Dodo\Node::_resetNodeDocument ( Document  $doc)

Set the ownerDocument reference on a subtree rooted at $this.

Called by Document::adoptNode()

Parameters
Document$doc

◆ _roothook()

Wikimedia\Dodo\Node::_roothook ( )

<script> elements need to know when they're inserted into the document.

See Document::_root(Node). Override this method to invoke such a hook.

◆ _setMissingProp()

Wikimedia\Dodo\Node::_setMissingProp ( string  $name,
  $value 
)
protected

◆ _subclassCloneNodeShallow()

Node Wikimedia\Dodo\Node::_subclassCloneNodeShallow ( )
abstractprotected

◆ _subclassIsEqualNode()

bool Wikimedia\Dodo\Node::_subclassIsEqualNode ( Node  $node)
abstractprotected

Delegated subclass method called by Node::isEqualNode()

Parameters
Node$node
Returns
bool

Reimplemented in Wikimedia\Dodo\DocumentFragment, Wikimedia\Dodo\Element, and Wikimedia\Dodo\Document.

◆ _unsafeAppendChild()

Node Wikimedia\Dodo\Node::_unsafeAppendChild ( Node  $node)

Does not check for insertion validity.

This out-performs PHP DOMDocument by over 2x.

Parameters
Node$node
Returns
Node

Reimplemented in Wikimedia\Dodo\Document.

◆ _xmlSerialize()

Wikimedia\Dodo\Node::_xmlSerialize ( ?string  $namespace,
NamespacePrefixMap  $prefixMap,
int &  $prefixIndex,
array  $options,
array &  $markup 
)

XML serialize the given node.

This is overridden in subclasses. Note that this is effectively "outerHTML", due to a spec inconsistency: https://github.com/w3c/DOM-Parsing/issues/28 .

See also
https://w3c.github.io/DOM-Parsing/#dfn-xml-serialization
Parameters
?string$namespace
NamespacePrefixMap$prefixMap
int&$prefixIndex
array$options
string[]&$markupaccumulator for the result

Reimplemented in Wikimedia\Dodo\Attr, Wikimedia\Dodo\CDATASection, Wikimedia\Dodo\Comment, Wikimedia\Dodo\Document, Wikimedia\Dodo\DocumentFragment, Wikimedia\Dodo\DocumentType, Wikimedia\Dodo\Element, Wikimedia\Dodo\ProcessingInstruction, and Wikimedia\Dodo\Text.

◆ appendChild()

Wikimedia\Dodo\Node::appendChild (   $node)

◆ cloneNode()

Node Wikimedia\Dodo\Node::cloneNode ( bool  $deep = false)

Clone this Node.

spec DOM-LS

NOTE:

  1. If $deep is false, then no child nodes are cloned, including any text the node contains (since these are Text nodes).
  2. The duplicate returned by this method is not part of any document until it is added using ::appendChild() or similar.
  3. Initially (DOM4) , $deep was optional with default of 'true'. Currently (DOM4-LS), $deep is optional with default of 'false'.
  4. Shallow cloning is delegated to _subclassCloneNodeShallow(), which needs to be implemented by the subclass. For a similar pattern, see Node::isEqualNode().
  5. All "deep clones" are a shallow clone followed by recursion on the tree structure, so this suffices to capture subclass-specific behavior.
Parameters
bool$deepif true, clone entire subtree
Returns
Node (clone of $this)

Implements Wikimedia::IDLeDOM::Node.

Reimplemented in Wikimedia\Dodo\Document.

◆ compareDocumentPosition()

int Wikimedia\Dodo\Node::compareDocumentPosition (   $that)
final

◆ contains()

bool Wikimedia\Dodo\Node::contains (   $node)
final

◆ getChildNodes()

Wikimedia\Dodo\Node::getChildNodes ( )
abstract

This should be overridden in ContainerNode and Leaf.

Implements Wikimedia::IDLeDOM::Node.

Reimplemented in Wikimedia\Dodo\ContainerNode, and Wikimedia\Dodo\Leaf.

◆ getExtensionData()

mixed Wikimedia\Dodo\Node::getExtensionData ( string  $key,
  $defaultValue = null 
)

Get "extension data" associate with this node, using the given $key.

Parameters
string$keyDistinguishes between various types of extension data.
mixed$defaultValueThe value to return if the extension data is not present on this node; defaults to null.
Returns
mixed The extension data associated with $key on this node.

◆ getFirstChild()

Wikimedia\Dodo\Node::getFirstChild ( )
abstract

This should be overridden in ContainerNode and Leaf.

Implements Wikimedia::IDLeDOM::Node.

Reimplemented in Wikimedia\Dodo\ContainerNode, and Wikimedia\Dodo\Leaf.

◆ getIsConnected()

bool Wikimedia\Dodo\Node::getIsConnected ( )

Determine whether this Node is rooted (belongs to the tree rooted at the node document).

Returns
bool

NOTE Document nodes maintain a list of all the nodes inside their tree, assigning each an index, Node::_documentIndex.

Therefore if we are currently rooted, we can tell by checking that we have one of these.

Implements Wikimedia::IDLeDOM::Node.

◆ getLastChild()

Wikimedia\Dodo\Node::getLastChild ( )
abstract

This should be overridden in ContainerNode and Leaf.

Implements Wikimedia::IDLeDOM::Node.

Reimplemented in Wikimedia\Dodo\ContainerNode, and Wikimedia\Dodo\Leaf.

◆ getNextSibling()

Node Wikimedia\Dodo\Node::getNextSibling ( )
final

◆ getNodeName()

◆ getNodePath()

string Wikimedia\Dodo\Node::getNodePath ( )

Get an XPath for a node.

This is a PHP-compatibility extension to the DOM spec.

Returns
?string

◆ getNodeType()

◆ getNodeValue()

string Wikimedia\Dodo\Node::getNodeValue ( )

Return the value for this node.

See also
https://dom.spec.whatwg.org/#dom-node-nodevalue
Returns
?string

Implements Wikimedia::IDLeDOM::Node.

Reimplemented in Wikimedia\Dodo\Attr, and Wikimedia\Dodo\CharacterData.

◆ getOwnerDocument()

Document Wikimedia\Dodo\Node::getOwnerDocument ( )

The ownerDocument getter steps are to return null, if this is a document; otherwise this’s node document.

We will override this implementation to return null in the Document class.

Implements Wikimedia::IDLeDOM::Node.

Reimplemented in Wikimedia\Dodo\Document.

◆ getParentElement()

Element Wikimedia\Dodo\Node::getParentElement ( )
final

This value is the same as parentNode, except it puts an extra condition, that the parentNode must be an Element.

Accordingly, it requires no additional backing property, and can exist only as an accessor.

Implements Wikimedia::IDLeDOM::Node.

◆ getParentNode()

Node Wikimedia\Dodo\Node::getParentNode ( )
final

Nodes might not have a parentNode.

Perhaps they have not been inserted into a DOM, or are a Document node, which is the root of a DOM tree and thus has no parent. In those cases, the value of parentNode is null.

Returns
?Node

Implements Wikimedia::IDLeDOM::Node.

◆ getPreviousSibling()

Node Wikimedia\Dodo\Node::getPreviousSibling ( )
final

◆ getRootNode()

Wikimedia IDLeDOM Node Wikimedia\Dodo\Node::getRootNode (   $options = null)

Return this' shadow-including root if options['composed'] is true; otherwise return this' root.

NOTE that the root of a node is not (necessarily) the ownerDocument or node document of the node!

See also
https://dom.spec.whatwg.org/#dom-node-getrootnode
https://dom.spec.whatwg.org/#concept-tree-root
Parameters
GetRootNodeOptions | associative-array | null$options
Returns
\Wikimedia\IDLeDOM\Node

Implements Wikimedia::IDLeDOM::Node.

◆ getTextContent()

string Wikimedia\Dodo\Node::getTextContent ( )

◆ insertBefore()

Node Wikimedia\Dodo\Node::insertBefore (   $node,
  $refNode = null 
)

Insert $node as a child of $this, and insert it before $refChild in the document order.

spec DOM-LS

THINGS TO KNOW FROM THE SPEC:

  1. If $node already exists in this Document, this function moves it from its current position to its new position ('move' means 'remove' followed by 're-insert').
  2. If $refNode is NULL, then $node is added to the end of the list of children of $this. In other words, insertBefore($node, NULL) is equivalent to appendChild($node).
  3. If $node is a DocumentFragment, the children of the DocumentFragment are moved into the child list of $this, and the empty DocumentFragment is returned.

THINGS TO KNOW IN LIFE:

Despite its weird syntax (blame the spec), this is a real workhorse, used to implement all of the non-replacing insertion mutations.

Parameters
INode$nodeTo be inserted
?INode$refNode Child of this node before which to insert $node
Returns
Node Newly inserted Node or empty DocumentFragment
Exceptions
DOMException"HierarchyRequestError" or "NotFoundError"

Implements Wikimedia::IDLeDOM::Node.

Reimplemented in Wikimedia\Dodo\Document, and Wikimedia\Dodo\Leaf.

◆ isDefaultNamespace()

bool Wikimedia\Dodo\Node::isDefaultNamespace ( ?string  $ns)

Determine whether this is the default namespace.

Implements Wikimedia::IDLeDOM::Node.

◆ isEqualNode()

bool Wikimedia\Dodo\Node::isEqualNode (   $node)

Determine whether this node and $other are equal.

spec: DOM-LS

NOTE: Each subclass of Node has its own criteria for equality. Rather than extend Node::isEqualNode(), subclasses must implement _subclassIsEqualNode(), which is called from Node::isEqualNode() and handles all of the equality testing specific to the subclass.

This allows the recursion and other fast checks to be handled here and written just once.

Yes, we realize it's a bit weird.

Implements Wikimedia::IDLeDOM::Node.

◆ isSameNode()

bool Wikimedia\Dodo\Node::isSameNode (   $node)
final

◆ lookupNamespaceURI()

string Wikimedia\Dodo\Node::lookupNamespaceURI ( ?string  $prefix)

Return DOMString containing namespace URI for a given prefix.

NOTE Inverse of Node::lookupPrefix

Implements Wikimedia::IDLeDOM::Node.

◆ lookupPrefix()

string Wikimedia\Dodo\Node::lookupPrefix ( ?string  $ns)

Return DOMString containing prefix for given namespace URI.

spec DOM-LS

NOTE Think this function looks weird? It's actually spec: https://dom.spec.whatwg.org/#locate-a-namespace

Implements Wikimedia::IDLeDOM::Node.

◆ normalize()

Wikimedia\Dodo\Node::normalize ( )
final

Puts $this and the entire subtree rooted at $this into "normalized" form.

In a normalized sub-tree, no text nodes in the sub-tree are empty, and there are no adjacent text nodes.

See also
https://dom.spec.whatwg.org/#dom-node-normalize

Implements Wikimedia::IDLeDOM::Node.

◆ removeChild()

Node Wikimedia\Dodo\Node::removeChild (   $node)

◆ replaceChild()

Node Wikimedia\Dodo\Node::replaceChild (   $new,
  $old 
)

◆ setExtensionData()

Wikimedia\Dodo\Node::setExtensionData ( string  $key,
  $value 
)

Set "extension data" associate with this node, using the given $key.

Parameters
string$keyDistinguishes between various types of extension data.
mixed$valueThe value to store under this $key on this node.

◆ setNodeValue()

Wikimedia\Dodo\Node::setNodeValue ( ?string  $val)

◆ setTextContent()

Wikimedia\Dodo\Node::setTextContent ( ?string  $val)

Member Data Documentation

◆ $_cachedSiblingIndex

int Wikimedia\Dodo\Node::$_cachedSiblingIndex = null

DEVELOPERS NOTE: An index is assigned on INSERTION.

It uniquely identifies the Node among its siblings.

It is used to help compute document position and to mark where insertion should occur.

Its existence is, frankly, mostly for convenience due to the fact that the most common representation of child nodes is a linked list that doesn't have numeric indices otherwise.

FIXME It is public because it gets used by the whatwg algorithms page.

◆ $_documentIndex

int Wikimedia\Dodo\Node::$_documentIndex = null

DEVELOPERS NOTE: An index is assigned when a node is added to a Document (becomes rooted).

It uniquely identifies the Node within its owner Document.

This index makes it simple to represent a Node as an integer.

This is also used to determine if a Node is currently rooted.

It allows this optimization: If two Elements have the same id, they will be stored in an array under their $document_index. This means we don't have to search the array for a matching Node when another node with the same ID is added or removed from the document; we can do a look up in O(1). If your document contains lots of elements with identical IDs, this prevents a quadratic slowdown.

◆ $_nextSibling

Node Wikimedia\Dodo\Node::$_nextSibling

The sibling list is stored as a circular linked list: the node "before" the first sibling is the last sibling, and the node "after" the last sibling is the first sibling.

This makes finding the last sibling as quick as finding the first.

As a consequence, if a Node has no siblings, i.e. it is the 'only child' of $_parentNode, then the properties $_nextSibling and $_previousSibling are set equal to $this (ie, a single-element circular list).

Obviously, the DOM LS accessors return 'null' at the beginning and ends of the list (as well as for both siblings when the node is an only child); we tweak the getters to make this work.

But be very careful when you access _nextSibling directly! If you want a null-terminated list, use getNextSibling() instead!

◆ $_nodeDocument

Document Wikimedia\Dodo\Node::$_nodeDocument

The document this node is associated to.

spec DOM-LS

NOTE This is different from ownerDocument: According to DOM-LS, Document::ownerDocument() must equal NULL, even though it's often more convenient if a document is its own owner.

What we're looking for is the "node document" concept, as laid out in the DOM-LS spec:

 -"Each node has an associated node document, set upon creation,
  that is a document."

 -"A node's node document can be changed by the 'adopt'
  algorithm."

 -"The node document of a document is that document itself."

 -"All nodes have a node document at all times."

NOTE The DOM-LS method Node::getRootNode (and the "root" of a node) is not the same thing: the root of a node which hasn't been added to the document is the highest ancestor; while the node document is always the owning document even if this node hasn't yet been added to it.

◆ $_previousSibling

Node Wikimedia\Dodo\Node::$_previousSibling
See also
$_nextSibling

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