XmlNodes

MMO\core\helpers · 1 symbol · generated 5 Oct 2026

class

XmlNodes

A lightweight, mutable DOM-like tree: a list of "child nodes" that are each either a plain string (text) or another XmlNodes/XmlNode instance. XmlNodes itself is an unnamed container (a document fragment / root document); XmlNode adds a tag name and attributes on top, for an actual element. Children can be indexed numerically ($nodes[0]) or by an optional string alias ($nodes['greeting']) assigned via

class MMO\core\helpers\XmlNodes implements MMO\core\interfaces\iArray, MMO\core\interfaces\iRenderable use MMO\core\classes\tPropertyGetter

Namespace: MMO\core\helpers
Implements: iArray, iRenderable
Uses traits: tPropertyGetter
See: add/push.

$root = new XmlNode('div', ['class' => 'box']); $root->add('Hello '); $root->add(new XmlNode('b', [], ['World']), 'bold'); (string)$root; // '<div class="box">Hello <b>World</b></div>' $root['bold']; // the <b> node, via its alias

Index

	alias
	childNodes
	ClosingTags static	HTML void elements: self-closing, never get a separate closing tag when rendered.
	parentNode
	add($value, $alias, $first)	Add value as a node Convert any array into a HTMLNodes
	addXml($xml)	Parse xml and add nodes
	children()
	clear()	Remove every child (and alias), detaching each from this tree.
	contains($node)
	count()	\Countable::count
	create($tag, $attrs, $nodes)	Convenience factory: build a new node (not yet attached to this tree).
	debugName()
	From($xml, $simplify) static	Parse XML/HTML text (or a stream) into a tree.
	FromFile($filename, $simplify) static	Same as `From`, reading the XML/HTML from a file.
	getAlias($node)
	getContent()
	getElementByTagName($tag, $ns)	Get first element with the given tag
	getElementsById($id)
	getElementsByTagName($tag, $ns)
	getIterator()	\IteratorAggregate::getIterator
	getParentNode()
	getRootNode()
	hasChildNodes()
	hasElement($tag)
	innerNodes($opts)
	innerText()
	isClosingTag($tag)
	jsonSerialize()
	listElementsByTagName($tags, $nodes)	Like `getElementsByTagName` but for several tag names at once.
	loopElementsByTagName($tag, $ns)	Look for all children recursively who have a given tag
	nearest($tags)	Walk up the ancestor chain (starting at the parent, all the way up to and including the document root) looking for the first one whose tag matches.
	offsetExists($key)	\ArrayAccess::offsetExists
	offsetGet($key)	\ArrayAccess::offsetGet -- a numeric key indexes `$childNodes` directly; anything else looks up `$alias`.
	offsetSet($key, $value)	\ArrayAccess::offsetSet -- setting an existing numeric index replaces that child (or, for an XmlNodes target, sets its content); an unknown key (numeric or alias) adds a new child instead.
	offsetUnset($key)	\ArrayAccess::offsetUnset
	push($key, $value)	Push a value into an EXISTING child (by numeric index or alias) -- delegates to that child's own `add` (or, for two adjacent text nodes, string concatenation) -- or, if $key doesn't resolve to a…
	remove()	Detach this node from its parent (a no-op if it has none).
	removeChild($node)	Detach $node from this tree's direct children (and any alias pointing at it).
	render($opts)
	replaceChild($newNode, $oldNode)	Replace $oldNode (a direct child) with $newNode in place, carrying over any alias that pointed to $oldNode (checked up the WHOLE ancestor chain, not just this node).
	setAlias($alias, $node)	Name (or rename) a child so it can be looked up via `$nodes['alias']` -- does NOT add $node as a child itself, see `add` for that.
	setContent($content)	Replace every child with $content (via `clear` then `add`).
	setParentNode($parent)	Attach this node to $parent, detaching it from its previous parent first if it had a different one.
	stripTags($includes, $excludes)
	toArray()
	__construct($nodes)
	__get($key)	__get -- allow read access to a protected/private property from outside the class.
	__isset($key)	__isset
	__toString()

Properties4

alias

protected array $alias = []

Type: array

childNodes

protected array $childNodes = []

Type: array

ClosingTags

static

HTML void elements: self-closing, never get a separate closing tag when rendered.

static $ClosingTags = […17 items]

parentNode

protected ?MMO\core\helpers\XMLNodes $parentNode = null

Type: null | XMLNodes

Methods45

add($value, $alias, $first)

XmlNodes.php:173

Add value as a node Convert any array into a HTMLNodes

function add(mixed $value, ?string $alias = null, bool $first = false)

$value	mixed	anything that can be rendered by the printer -- an array (recursively added, its own keys becoming aliases), a string (merged into an adjacent text node instead of creating a new one, when possible), or any XmlNodes/XmlNode instance
$alias = null	null \| string	if given, the new node can also be looked up via `$this[$alias]` afterward
$first = false	bool	if true, prepend instead of append
returns

$root->add('Hello '); // a new text-node child (or merged into the last one, if it was text too)

$root->add(new XmlNode('b', [], ['World']), 'bold');

addXml($xml)

XmlNodes.php:267

Parse xml and add nodes

function addXml($xml): void

$xml
returns	void

children()

XmlNodes.php:476

function children(): array

returns

array

count($node->children()); // number of ELEMENT children, ignoring text nodes -- unlike count($node), which counts every child node including text

clear()

XmlNodes.php:204

Remove every child (and alias), detaching each from this tree.

function clear(): void

returns

void

contains($node)

XmlNodes.php:440

function contains(self $node): bool

$node	self
returns	bool	true if $node is a DIRECT child of this node (not recursive)

count()

XmlNodes.php:545

\Countable::count

function count(): int

returns

int

create($tag, $attrs, $nodes)

XmlNodes.php:110

Convenience factory: build a new node (not yet attached to this tree).

function create(?string $tag = null, array $attrs = [], array $nodes = []): self

$tag = null	null \| string	null builds a plain XmlNodes fragment; a string builds an `XmlNode` with that tag
$attrs = []	array
$nodes = []	array	initial children
returns	self

debugName()

XmlNodes.php:46

function debugName(): string

returns

string

e.g. 'xmlNodes(3)'

From($xml, $simplify)

staticXmlNodes.php:63

Parse XML/HTML text (or a stream) into a tree.

static function From($xml, bool $simplify = true): self

$xml
$simplify = true	bool	if true, and the parsed result has exactly one child, return that child directly instead of the wrapping XmlNodes container
returns	self

XmlNodes::From('<root><a>1</a><b>2</b></root>'); // an XmlNode (simplified: single root element)

FromFile($filename, $simplify)

staticXmlNodes.php:75

Same as From, reading the XML/HTML from a file.

static function FromFile(string $filename, bool $simplify = true): self

$filename	string
$simplify = true	bool
returns	self

getAlias($node)

XmlNodes.php:140

function getAlias(mixed $node): ?string

$node	mixed
returns	null \| string	the alias $node is registered under, if any

getContent()

XmlNodes.php:147

function getContent(): array

returns array same as toArray

getElementByTagName($tag, $ns)

XmlNodes.php:342

Get first element with the given tag

function getElementByTagName(string $tag, ?string $ns = null): ?MMO\core\helpers\XmlNode

$tag	string
$ns = null	null \| string
returns	null \| XmlNode

getElementsById($id)

XmlNodes.php:382

function getElementsById($id): ?self

$id
returns	null \| self	the first descendant whose 'id' attribute equals $id

getElementsByTagName($tag, $ns)

XmlNodes.php:332

function getElementsByTagName(string $tag, ?string $ns = null): array

$tag	string
$ns = null	null \| string
returns	array	all matching descendants, see `loopElementsByTagName`

getIterator()

XmlNodes.php:559

\IteratorAggregate::getIterator

function getIterator(): Traversable

returns

Traversable

getParentNode()

XmlNodes.php:258

function getParentNode(): ?self

returns

null | self

getRootNode()

XmlNodes.php:445

function getRootNode(): self

returns

self

the outermost ancestor -- $this itself if it has no parent

hasChildNodes()

XmlNodes.php:393

function hasChildNodes(): bool

returns

bool

true if this node has at least one child

hasElement($tag)

XmlNodes.php:353

function hasElement(array|string $tag): bool

$tag	array \| string	one or more tag names
returns	bool	true if any descendant has this tag (recursive)

innerNodes($opts)

XmlNodes.php:115

function innerNodes(array $opts = []): string

$opts = []	array
returns	string	same as `render` -- kept distinct so an `XmlNode` subclass can render just its children

innerText()

XmlNodes.php:120

function innerText(): string

returns

string

every text node, recursively, concatenated (tags stripped, text kept)

isClosingTag($tag)

XmlNodes.php:80

function isClosingTag(string $tag): bool

$tag	string
returns	bool	true if $tag is a self-closing/void HTML element (`$ClosingTags`)

jsonSerialize()

XmlNodes.php:85

function jsonSerialize(): array

returns array same as toArray, for json_encode()

listElementsByTagName($tags, $nodes)

XmlNodes.php:368

Like getElementsByTagName but for several tag names at once.

function listElementsByTagName(array $tags, array &$nodes = []): array

$tags	array
$nodes = []	array
returns	array

loopElementsByTagName($tag, $ns)

XmlNodes.php:316

Look for all children recursively who have a given tag

function loopElementsByTagName(string $tag, ?string $ns = null): Generator

$tag	string
$ns = null	null \| string	if '*', ignore the tag namespace.
returns	Generator

nearest($tags)

XmlNodes.php:458

Walk up the ancestor chain (starting at the parent, all the way up to and including the document root) looking for the first one whose tag matches. See also XmlNode::closest (same intent, walked from an element rather than a fragment).

function nearest(array|string $tags): ?MMO\core\helpers\XmlNode

$tags	array \| string	one or more tag names
returns	null \| XmlNode

$span->nearest('div'); // the nearest ancestor <div>, or null if none

offsetExists($key)

XmlNodes.php:552

\ArrayAccess::offsetExists

function offsetExists(mixed $key): bool

$key	mixed
returns	bool

offsetGet($key)

XmlNodes.php:494

\ArrayAccess::offsetGet -- a numeric key indexes $childNodes directly; anything else looks up $alias.

function offsetGet(mixed $key): mixed

Returned by reference (so e.g. `$node[0][] = $child;` can mutate a child in place) -- for a key that doesn't exist, this returns a reference to a fresh, unshared `null` instead of indexing $childNodes/$alias directly: doing the latter would have PHP silently auto-vivify that key (creating a real, permanent `null` entry as a side effect of merely reading it) -- corrupting the node with a phantom child/alias.

$key	mixed
returns	mixed

$node[0]; // the first child node

$node['greeting']; // the child registered under that alias (@see add / @see setAlias)

offsetSet($key, $value)

XmlNodes.php:507

\ArrayAccess::offsetSet -- setting an existing numeric index replaces that child (or, for an XmlNodes target, sets its content); an unknown key (numeric or alias) adds a new child instead.

function offsetSet(mixed $key, mixed $value): void

$key	mixed
$value	mixed
returns	void

offsetUnset($key)

XmlNodes.php:531

\ArrayAccess::offsetUnset

function offsetUnset(mixed $key): void

$key	mixed
returns	void

push($key, $value)

XmlNodes.php:223

Push a value into an EXISTING child (by numeric index or alias) -- delegates to that child's own add (or, for two adjacent text nodes, string concatenation) -- or, if $key doesn't resolve to an existing child, falls back to add-ing $value as a brand new child.

function push(string|int $key, mixed $value): void

$key	string \| int	a numeric index, or an alias name
$value	mixed	the value to push
returns	void

$node->push(0, new XmlNode('li', [], ['pushed in'])); // added as a child of childNodes[0]

$node->push('greeting', ' again'); // appended into the node aliased 'greeting'

remove()

XmlNodes.php:275

Detach this node from its parent (a no-op if it has none).

function remove(): self

returns

self

$this, for chaining

removeChild($node)

XmlNodes.php:402

Detach $node from this tree's direct children (and any alias pointing at it).

function removeChild(self $node): self

$node	self
returns	self	$node, for chaining

render($opts)

XmlNodes.php:97

function render(array $opts = []): string

$opts = []	array
returns	string	every child node concatenated/rendered, in order

replaceChild($newNode, $oldNode)

XmlNodes.php:420

Replace $oldNode (a direct child) with $newNode in place, carrying over any alias that pointed to $oldNode (checked up the WHOLE ancestor chain, not just this node).

function replaceChild($newNode, $oldNode)

$newNode
$oldNode
returns		$oldNode (now detached)
throws		if $oldNode is not a direct child of this node

setAlias($alias, $node)

XmlNodes.php:135

Name (or rename) a child so it can be looked up via $nodes['alias'] -- does NOT add $node as a child itself, see add for that.

function setAlias(string $alias, mixed $node): void

$alias	string
$node	mixed
returns	void

setContent($content)

XmlNodes.php:156

Replace every child with $content (via clear then add).

function setContent(array $content): void

$content	array
returns	void

setParentNode($parent)

XmlNodes.php:247

Attach this node to $parent, detaching it from its previous parent first if it had a different one.

function setParentNode(?self $parent): void

$parent	null \| self
returns	void

stripTags($includes, $excludes)

XmlNodes.php:293

function stripTags(array $includes = [], array $excludes = ['script', 'style']): string

$includes = []	array
$excludes = ['script', 'style']	array
returns	string

$node->stripTags(); // e.g. 'Hello World !' -- text nodes joined with a space, tags removed

$node->stripTags(['b']); // keeps <b>...</b> tags in the output, strips every other tag

toArray()

XmlNodes.php:51

function toArray(): array

returns

array

the raw child nodes (strings and/or XmlNodes/XmlNode instances), in order

__construct($nodes)

XmlNodes.php:41

function __construct(array $nodes = [])

$nodes = [] array initial children, merged in via merge (so e.g. an alias => node associative structure works too, same as passing it to add)

__get($key)

tPropertyGetter.php:25

__get -- allow read access to a protected/private property from outside the class.

function __get($key)

$key
returns
throws		if no such property exists at all (a declared-but-uninitialized typed property is returned as-is here, and would raise PHP's own "must not be accessed before initialization" error, not this exception)

$thing->name; // 'Marc'

$thing->doesNotExist; // throws eNotFound

__isset($key)

tPropertyGetter.php:36

__isset

function __isset($key)

$key
returns

isset($thing->name); // true

__toString()

XmlNodes.php:92

function __toString(): string

returns string same as render() with default options