---

Element

• Full name: \Hazaar\XML\Element
• This class implements: \ArrayAccess, \Iterator

Constants

Constant	Visibility	Type	Value
VERSION	public		'1.0'
ENCODING	public		'utf-8'

Properties

__parent

The direct parent object of the current node element.

public ?\Hazaar\XML\Element $__parent

---

open_tag

public string $open_tag

---

close_tag

public string $close_tag

---

__name

The name of the current node element.

protected ?string $__name

---

__namespace

The namespace prefix for the current node element.

protected ?string $__namespace

---

__default_namespace

The default namespace prefix to use when accessing child members.

protected ?string $__default_namespace

---

__namespaces

An array of namespaces defined on this node.

protected string[] $__namespaces

---

__attributes

An array of attributed defined on this node.

protected array<string,string> $__attributes

---

__children

An array to contain all the child nodes of this node element.

protected \Hazaar\XML\Element[] $__children

---

__children_index

protected (\Hazaar\XML\Element[]|\Hazaar\XML\Element)[] $__children_index

---

__value

If there are no child nodes, the value that will used for this node element.

private mixed $__value

---

__reset

Toggle to indicate if the Element is being accessed as an array and is reset.

private bool $__reset

---

Methods

__construct

Creates a new \Hazaar\XML\Element object.

public __construct(string $name = null, mixed $value = null, string[] $namespaces = null, string $open_tag = '<', string $close_tag = '>'): mixed

Parameters:

Parameter	Type	Description
$name	string	The name of the element to create, optionally including a namespace
$value	mixed	The value of the element. This can be pretty much anything, including another \Hazaar\Xml\Element object.
$namespaces	string[]	Array of namespaces to declare where the key is the prefix and the value is the namespace URI
$open_tag	string	Configurable open tag for elements. XML defines this as '<'. This can be changed for use with alternative file formats.
$close_tag	string	Configurable close tag for elements. XML defines this as '>'. This can be changed for use with alternative file formats.

---

__clone

public __clone(): void

---

__toString

Magic method to return the current node element as a string.

public __toString(): string

---

__get

Magic method to access a child element by it's name.

public __get(string $name): \Hazaar\XML\Element

This will automatically create a new child element when accessing a node that does not yet exist.

Parameters:

Parameter	Type	Description
$name	string	the name of the child element to return

Return Value:

the child element being requested

---

__set

Magic method to automatically create a new child element on access.

public __set(string $name, mixed $value): void

Parameters:

Parameter	Type	Description
$name	string	the name key of child node to modify
$value	mixed	he value to set

---

setTagChars

Set the open and close tag characters for parsing and generating XML.

public setTagChars(string $open_tag, string $close_tag): void

By changing the open and close tags we are able to use the \Hazaar\XML\Element class to work with text formats other than XML but that have a similar format.

Parameters:

Parameter	Type	Description
$open_tag	string	the open tag to set
$close_tag	string	the close tag to set

---

setDefaultNamespace

Sets the default namespace to use when accessing child nodes as members.

public setDefaultNamespace(string $ns): bool

The namespace MUST be a valid namespace already defined in the objects. If the namespace is not defined then FALSE will be returned. The namespace can be referenced with by it's alias or it's URL. In the latter case the alias will be looked up. Also, if the URL is not found the shortcut URL will be tried which is the URL with a colon appended (eg: DAV:).

Parameters:

Parameter	Type	Description
$ns	string	the name/url of the namespace to use/prefix as default

---

getDefaultNamespace

Returns the default namespace for the current node object.

public getDefaultNamespace(): ?string

The default namespace does not need to be set on the current object and can be set on a parent object. This method will look at it's own default namespace and if one is not set it will then request one from the parent.

---

addNamespace

Declare a namespace on the current node element.

public addNamespace(string $prefix, string $value): void

Parameters:

Parameter	Type	Description
$prefix	string	a namespace prefix
$value	string	the value of the namespace

---

namespaceExists

Test if a namespace is available for the current node element.

public namespaceExists(string $prefix): bool

This is a recursive test, meaning if the namespace isn't defined on the current element then it's parent will be checked. This is because namespaces, once declared, are available to all child elements of the node the namespace is declared on.

Parameters:

Parameter	Type	Description
$prefix	string	the namespace prefix to check

---

attr

Set an attribute on the current Hazaar\XML\Element object.

public attr(string $name, string $value): void

Parameters:

Parameter	Type	Description
$name	string	the name of the attribute
$value	string	the value of the attribute

---

getAttr

Return an attribute value.

public getAttr(string $name): string

Parameters:

Parameter	Type	Description
$name	string	The name of the attribute to return

---

attributes

Returns a list of attributes current declared on the node element.

public attributes(): array<string,string>

---

add

Adds a new element to the current node element.

public add(string $name, mixed $value = null, string[] $namespaces = null): \Hazaar\XML\Element

Parameters:

Parameter	Type	Description
$name	string	The name of the element to create, optionally including a namespace
$value	mixed	The value of the element. This can be pretty much anything, including another \Hazaar\Xml\Element object.
$namespaces	string[]	Array of namespaces to declare where the key is the prefix and the value is the namespace URI

Return Value:

the new child object

---

addFromArray

Creates and adds child elements to the current XML element from an array.

public addFromArray(string $name, array $array, string $tag = 'child'): \Hazaar\XML\Element

Parameters:

Parameter	Type	Description
$name	string	the name of the current XML element
$array	array	the array containing the data for creating child elements
$tag	string	the tag name for the child elements (default: 'child')

Return Value:

the current XML element with added child elements

---

child

Returns a child by it's node name.

public child(string $name, mixed $value = null, string[] $namespaces = null): array|\Hazaar\XML\Element

If the node doesn't exist, then it is automatically added.

Parameters:

Parameter	Type	Description
$name	string	The name of the element to create, optionally including a namespace
$value	mixed	The value of the element. This can be pretty much anything, including another Hazaar\Xml\Element object.
$namespaces	string[]	Array of namespaces to declare where the key is the prefix and the value is the namespace URI

---

children

Returns a list of all child elements on the current node element.

public children(): \Hazaar\XML\Element[]

---

count

Returns the number of children on the current node element.

public count(): int

---

hasChildren

Returns the TRUE or FALSE to indicate that the node has child elements.

public hasChildren(): bool

---

getName

Get the full valid name of the current node element.

public getName(bool $include_invalid_namespace = false): string

This will return the full name which includes the namespace that was originally defined ONLY if the namespace is valid. Namespaces are valid if they have also been defined with a call to Hazar\Xml\Element::addNamespace() on this element or a parent element.

If the namespace is NOT valid, then it is simply ignored. If the namespace should be returned regardless of it's validity, use the $include_invalid_namespace parameter.

Parameters:

Parameter	Type	Description
$include_invalid_namespace	bool	include namespaces that have no been defined in the current or parent nodes

---

getLocalName

Get the local name of the XML element.

public getLocalName(): string

Return Value:

the local name of the XML element

---

getNamespace

Get the namespace of the XML element.

public getNamespace(): string

Return Value:

the namespace of the XML element

---

value

Get or set the current value of the node element.

public value(string $value = null): mixed

If the node element does not have any child nodes then it's value can be set directly. If there are child nodes defined then this value is ignored when generating XML output using the Hazaar\Xml\Element::toXML() method.

If the $value parameter is not defined then current value is returned without modification

Parameters:

Parameter	Type	Description
$value	string	The value to set. If this is null then the value will not be modified. To empty the value set it to an empty string.

Return Value:

the current value of the element

---

getNamespaces

Returns an array of namespaces currently defined on the current node element.

public getNamespaces(bool $recursive = false): string[]

Optionally return any namespaces defined anywhere in the data object model.

Parameters:

Parameter	Type	Description
$recursive	bool	recurse through all child node elements and append their namespace declarations to the list

Return Value:

an array of defined namespaces with keys as the prefix and URIs as the value

---

toXML

Output the current XML structure as a string or save to file.

public toXML(string $filename = null): bool|string

This method generates the current XML structure as a returns it as a string resolving all names, namespaces and child elements.

Parameters:

Parameter	Type	Description
$filename	string	optional filename to save XML directly into

Return Value:

If saving to file, returns true/false indicating the file write result. Otherwise returns the XML as a string.

---

loadXML

Load an XML definition from a string.

public loadXML(string $xml): bool

The [[Hazaar\Xml\Element]] class can not only be used to generate XML, but also parse it to allow programmatic access to the data structure. This method takes a single string argument and attempts to parse it as valid XML.

Parameters:

Parameter	Type	Description
$xml	string	The XML source string

Return Value:

Indicates success or failure

---

hasChild

Tests if a child element exists on the current node.

public hasChild(string $name): bool

Parameters:

Parameter	Type	Description
$name	string	The name of the child element with optional namespace

Return Value:

true if the child element exists, false otherwise

---

hasAttr

Tests if an attribute exists on the current node.

public hasAttr(string $name): bool

Parameters:

Parameter	Type	Description
$name	string	The name of the child element with optional namespace

Return Value:

true if the child element exists, false otherwise

---

find

Searches children to find an element that matches search criteria.

public find(string[] $criteria, string $name = null): \Hazaar\XML\Element

Parameters:

Parameter	Type	Description
$criteria	string[]	An array of attribute criteria to search on. Example: ['name' => 'test'] will find elements who have a name attribute with a value of 'test'.
$name	string	optional node name to filter on

Return Value:

The child element if found. NULL Otherwise.

---

offsetSet

Set element attribute.

public offsetSet(mixed $name, mixed $value): void

Parameters:

Parameter	Type	Description
$name	mixed	the name key of child node to modify
$value	mixed	the value to set

---

offsetExists

Test if element attribute exists.

public offsetExists(string $name): bool

Parameters:

Parameter	Type	Description
$name	string	the name key of child node to check

Return Value:

TRUE if the child node exists, FALSE otherwise

---

offsetGet

Return an attribute value.

public offsetGet(mixed $name): mixed

Parameters:

Parameter	Type	Description
$name	mixed	The name of the attribute to return

Return Value:

the value of the attribute

---

offsetUnset

Unset an elements attribute.

public offsetUnset(mixed $name): void

Parameters:

Parameter	Type	Description
$name	mixed	the key name of the child to unset

---

current

Return the current child element.

public current(): mixed

---

next

Move to the next child element.

public next(): void

---

key

Return the key of the current child element.

public key(): mixed

---

valid

Test if the current child element is valid.

public valid(): bool

---

rewind

Reset the internal pointer to the first child element.

public rewind(): void

---

removeIndex

Returns the child element at the specified index.

public removeIndex(int $index): void

Parameters:

Parameter	Type	Description
$index	int	The index of the child element to return

---

getIndex

Returns the child element at the specified index.

public getIndex(int $index): mixed

Parameters:

Parameter	Type	Description
$index	int	The index of the child element to return

---

setName

Sets the name of the current \Hazaar\XML\Element object.

protected setName(string $name): void

Namespaces can be specifed using the colon separator. eg: 'namespace:name'.

$node->setName('C:mynode');

Parameters:

Parameter	Type	Description
$name	string	the name to set for the current object, optionally including a namespace

---

setParent

Sets the parent object for the current Hazaar\Xml\Element object.

private setParent(\Hazaar\XML\Element $parent): void

This is an internal method and is not accessible outside of the Hazaar\Xml\Element class.

Parameters:

Parameter	Type	Description
$parent	\Hazaar\XML\Element	the Hazaar\Xml\Element object to use as the parent

---

resolveXML

private resolveXML(\Hazaar\XML\Element[] $element): string

Parameters:

Parameter	Type	Description
$element	\Hazaar\XML\Element[]

---

---

Automatically generated on 2024-11-14