Documentation

XML
in package

XML helper methods.

Table of Contents

Methods

allowedEntities()  : callable
Create an entity loader that only loads from within a white list.
attr()  : string|null
Fetches an attribute from an element and trims it.
boolean()  : bool
XML booleans are... unclear. This is an attempt.
enum()  : mixed
Convert an integer into something more useful, with a map.
expectFirst()  : DOMElement
Requires that at least one element with the given tag exist and returns the first found.
expectFirstText()  : string
Requires that at least one element with the given tag exist, and returns the text content of the first found.
expectOneOf()  : DOMElement
Expect one of these nodes in the children.
first()  : DOMElement|null
Fetches the first element of a given tag name or null if none are found.
firstText()  : string|null
Fetches the text of the first element of a given tag name, or null if the element wasn't found.
format()  : DOMDocument
Interpolate and escape XML strings.
gatherChildren()  : array<string|int, DOMElement>
Iterates over the children (1 level deep) of a parent and fetches the first of all wanted elements by tag name.
getChildrenText()  : array<string|int, string>
Get a list of strings from the target child element.
parse()  : DOMDocument
Parse an XML document from a string.
parseFile()  : DOMDocument
Parse an XML document from a file.
prefixEntities()  : callable
Create an entity loader that only loads from a set of prefixes.
print()  : void
Print a node to the standard output.
processConditionals()  : void
Process if/end PI tags.
text()  : string
Fetches the text content of a node and trims it.
toString()  : string
Get the string of a node.
validate()  : void
Validate the document against a schema.
xpath()  : string|bool|int|float|DOMElement|array<string|int, DOMNode>|Generator<string|int, DOMNode>|null
Perform an XPath query on the node.
cleanLibXml()  : void
Tidy up after ourselves.
collectLibXmlErrors()  : void
Convert libxml errors into an exception.
createDocument()  : DOMDocument
Create a configured document ready for parsing.
getElementIterator()  : Generator<string|int, DOMElement>
Get an iterator for elements in a DOMNodeList.
getNodeIterator()  : Generator<string|int, DOMNode>
Get an iterator for a DOMNodeList.

Methods

allowedEntities()

Create an entity loader that only loads from within a white list.

public static allowedEntities(array<string|int, mixed> $entities) : callable

E.g.

XML::parse($blob, [
  'entities' => XML::allowedEntities([
    'http://www.w3.org/2001/xml.xsd',
    'http://www.w3.org/2003/05/soap-envelope/',
  ]),
]);
Parameters
$entities : array<string|int, mixed>
Return values
callable —

(public_id, system_id, context) => resource|null

attr()

Fetches an attribute from an element and trims it.

public static attr(DOMDocument|DOMElement $element, string $name) : string|null
Parameters
$element : DOMDocument|DOMElement
$name : string
Return values
string|null

boolean()

XML booleans are... unclear. This is an attempt.

public static boolean(DOMNode $thing) : bool
Parameters
$thing : DOMNode
Return values
bool —

true/false and nothing else

enum()

Convert an integer into something more useful, with a map.

public static enum(DOMNode $xml, string $path, array<string|int, mixed> $params) : mixed

The first element of the map will be the fallback if the value isn't found or the map can't find an element.

Example:

  XML::enum($dom, '//path/to/number', [
     0 => 'null',
     1 => 'yes',
     2 => 'no',
  ]);
  // => outputs one of null/yes/no
  // => unknown/no-value is 'null'
Parameters
$xml : DOMNode
$path : string
$params : array<string|int, mixed>

expectFirst()

Requires that at least one element with the given tag exist and returns the first found.

public static expectFirst(DOMNode $parent, string $tag_name) : DOMElement
Parameters
$parent : DOMNode
$tag_name : string
Tags
throws
XMLAssertException

If there were no nodes with that tag

Return values
DOMElement

expectFirstText()

Requires that at least one element with the given tag exist, and returns the text content of the first found.

public static expectFirstText(DOMNode $parent, string $tag_name) : string
Parameters
$parent : DOMNode
$tag_name : string
Tags
throws
XMLAssertException

If there were no nodes with that tag name

Return values
string

expectOneOf()

Expect one of these nodes in the children.

public static expectOneOf(DOMNode $parent, array<string|int, string> $wanted) : DOMElement
Parameters
$parent : DOMNode
$wanted : array<string|int, string>
Tags
throws
XMLAssertException

If no tag found

Return values
DOMElement

first()

Fetches the first element of a given tag name or null if none are found.

public static first(DOMNode $parent, string $tag_name) : DOMElement|null
Parameters
$parent : DOMNode
$tag_name : string
Return values
DOMElement|null

firstText()

Fetches the text of the first element of a given tag name, or null if the element wasn't found.

public static firstText(DOMNode $parent, string $tag_name) : string|null
Parameters
$parent : DOMNode
$tag_name : string
Return values
string|null

format()

Interpolate and escape XML strings.

public static format(string $template, array<string|int, mixed> $args) : DOMDocument

This creates an XML object.

Specify {{etc}} or {{0}} in the template and provide the same in the $args array. Values will be appropriately escaped.

Perform conditional with the <?if ?> PI tag.

<!-- Conditional blocks -->
<?if conditional ?>
   <item>
      <block attr="value"/>
   </item>
<?endif ?>

<!-- Conditional element -->
<?if element attr="value" ?>
Parameters
$template : string
$args : array<string|int, mixed>
Return values
DOMDocument

gatherChildren()

Iterates over the children (1 level deep) of a parent and fetches the first of all wanted elements by tag name.

public static gatherChildren(DOMNode $parent, array<string|int, string> $wanted) : array<string|int, DOMElement>

Note, if there are two of the same tag name, it will only get the first.

Output is indexed by the relevant tag name.

Parameters
$parent : DOMNode
$wanted : array<string|int, string>
Tags
throws
XMLAssertException

If not all wanted tags are found

Return values
array<string|int, DOMElement> —

[name => element]

getChildrenText()

Get a list of strings from the target child element.

public static getChildrenText(DOMElement $node, string $tag) : array<string|int, string>
Parameters
$node : DOMElement
$tag : string
Return values
array<string|int, string>

parse()

Parse an XML document from a string.

public static parse(string $source[, array<string|int, mixed> $config = [] ]) : DOMDocument

Example:

XML::parse($xml_source, [
   'options' => LIBXML_NOCDATA | LIBXML_NOBLANKS,
   'filename' => __DIR__ '/etc.xml',
   'schema' => $xsd_source,
]);

Config:

  • 'filename' include for prettier errors.
  • 'options' are an bitwise OR of libxml options.
  • 'schema' an XSD file for additional validation.
  • 'encoding' (default: UTF-8).
  • 'recover' try to parse non-well formed documents.
  • 'entities' an entity loading callback.
Parameters
$source : string
$config : array<string|int, mixed> = []

[filename, options, schema, encoding, recover, entities]

Tags
link
https://www.php.net/manual/en/libxml.constants.php
https://www.php.net/manual/en/function.libxml-set-external-entity-loader.php
throws
XMLException
Return values
DOMDocument

parseFile()

Parse an XML document from a file.

public static parseFile(string $filename[, array<string|int, mixed> $config = [] ]) : DOMDocument

Example:

XML::parseFile($filename, [
   'options' => LIBXML_NOCDATA | LIBXML_NOBLANKS,
   'schema_filename' => $xsd_source,
]);

Config:

  • 'options' are an bitwise OR of libxml options.
  • 'schema' an XSD file for additional validation.
  • 'encoding' (default: UTF-8).
  • 'recover' try to parse non-well formed documents.
  • 'entities' an entity loading callback.
Parameters
$filename : string
$config : array<string|int, mixed> = []

[options, schema, encoding, recover, entities]

Tags
link
https://www.php.net/manual/en/libxml.constants.php
https://www.php.net/manual/en/function.libxml-set-external-entity-loader.php
throws
XMLException
Return values
DOMDocument

prefixEntities()

Create an entity loader that only loads from a set of prefixes.

public static prefixEntities(array<string|int, mixed> $prefixes) : callable

E.g.

XML::parse($blob, [
  'entities' => XML::prefixEntities([
    'http://www.w3.org',
    'http://www.w3.org',
  ]),
]);
Parameters
$prefixes : array<string|int, mixed>
Return values
callable —

(public_id, system_id, context) => resource|null

print()

Print a node to the standard output.

public static print(DOMNode $node) : void
Parameters
$node : DOMNode
Return values
void —

echos

processConditionals()

Process if/end PI tags.

public static processConditionals(DOMNode $node, array<string|int, mixed> $conditions) : void

Given the matching condition, pass or remove the conditional PI tags.

This will modify the $node parameter.

Parameters
$node : DOMNode
$conditions : array<string|int, mixed>
Tags
example 
<!-- Conditional blocks -->
<?if conditional ?>
   <item>
      <block attr="value"/>
   </item>
<?endif ?>

<!-- Conditional element -->
<?if element attr="value" ?>
throws
XMLException

text()

Fetches the text content of a node and trims it.

public static text(DOMNode $node) : string
Parameters
$node : DOMNode
Return values
string

toString()

Get the string of a node.

public static toString(DOMNode $node) : string
Parameters
$node : DOMNode
Return values
string

validate()

Validate the document against a schema.

public static validate(DOMDocument $doc, string $source) : void
Parameters
$doc : DOMDocument
$source : string
Tags
throws
XMLException

xpath()

Perform an XPath query on the node.

public static xpath(DOMNode $node, string $query[, string $type = 'nodes' ]) : string|bool|int|float|DOMElement|array<string|int, DOMNode>|Generator<string|int, DOMNode>|null

By default, this will return an iterator of DOMNode. You can ask this method to convert it to something more useful.

Types:

  • string - via ::text()
  • bool - via ::boolean()
  • int
  • float
  • element - a DOMElement or null
  • list - DOMElement[]
  • nodes - Generator<DOMNode>
Parameters
$node : DOMNode
$query : string
$type : string = 'nodes'

string|bool|int|float|element|list|nodes

Return values
string|bool|int|float|DOMElement|array<string|int, DOMNode>|Generator<string|int, DOMNode>|null

cleanLibXml()

Tidy up after ourselves.

private static cleanLibXml() : void

collectLibXmlErrors()

Convert libxml errors into an exception.

private static collectLibXmlErrors(string $class, string|null $filename) : void
Parameters
$class : string

must be a XMLParseException type

$filename : string|null
Tags
throws
XMLException

createDocument()

Create a configured document ready for parsing.

private static createDocument(array<string|int, mixed> &$config) : DOMDocument
Parameters
$config : array<string|int, mixed>
Return values
DOMDocument

getElementIterator()

Get an iterator for elements in a DOMNodeList.

private static getElementIterator(DOMNodeList $list) : Generator<string|int, DOMElement>

The builtin getIterator() was only introduced with php8.

Parameters
$list : DOMNodeList
Return values
Generator<string|int, DOMElement>

getNodeIterator()

Get an iterator for a DOMNodeList.

private static getNodeIterator(DOMNodeList $list) : Generator<string|int, DOMNode>

The builtin getIterator() was only introduced with php8.

Parameters
$list : DOMNodeList
Return values
Generator<string|int, DOMNode>
On this page

Search results