Home » XML » XML_Util » Manual

Introduction

Introduction – Introduction to XML_Util

Introduction to XML_Util

XML_Util is a utility class that helps you working with (and especially creating) XML documents.

All methods of XML_Util can be called statically, that means you do not have to instantiate an XML_Util object to use the provided methods.

The funcionality of XML_Util ranges from validating an XML tag name (as there are strict rules for tag and attribute names) to the creation of namespaced XML tags.

Example

Example – Example for the usage of XML_Util

Usage example

The following examples shows how some of the methods of XML_Util have to be used.

Some basic examples

<?php
require_once "XML/Util.php";

// creating an XML tag
$tag = XML_Util::createTag("xsl:stylesheet", array("version" => "1.0"), "Place your content here", "http://www.w3.org/1999/XSL/Transform");

// verify tag name
$result = XML_Util::isValidName("my Tag");
if (PEAR::isError($result)) {
    print "Invalid XML name: " . $result->getMessage();
} else {
    print "Tagname is valid.";
}
?>

XML_Util::apiVersion

XML_Util::apiVersion() – return API version

Synopsis

string XML_Util::apiVersion ( )

Description

Returns API version of XML_Util.

Return value

string API version

Note

This function should be called statically.

XML_Util::attributesToString

XML_Util::attributesToString() – create XML attribute string

Synopsis

string XML_Util::attributesToString ( array $attributes , boolean $sort = true , boolean $multiline = false , string $indent = ' ' , string $linebreak = "\n" , integer $entities = XML_UTIL_ENTITIES_XML )

Description

create string representation of an attribute list

Parameter

• array $attributes - assoc array containg attributes
• boolean $sort - whether to sort the attributes alphabetically
• boolean $multiline - whether to display the attributes on more than one line (makes it easier to read)
• string $indent - indentation characters, only used when multiline is set to TRUE
• string $linebreak - linebreak character, only used when multiline is set to TRUE
• integer $entities - define, which entities should be replaced in the attribute values. One of XML_UTIL_ENTITIES_NONE, XML_UTIL_ENTITIES_XML, XML_UTIL_ENTITIES_XML_REQUIRED or XML_UTIL_ENTITIES_HTML

Return value

string string representation of the attributes

Note

This function should be called statically.

XML_Util::collapseEmptyTags

XML_Util::collapseEmptyTags() – collapse empty XML tags in a string

Synopsis

string XML_Util::collapseEmptyTags ( string $string , integer $mode = XML_UTIL_COLLAPSE_ALL )

Description

This method collapses empty tags like <foo></foo> with the short version <foo/> by applying a regular expression. This is especially helpful when dealing with XHTML-documents, as there is an important difference in rendering these tags in the browser.

This method has been added in XML_Util 1.1.0.

Parameter

• string $string - string, in which empty tags should be collapsed
• integer $mode - collapse all empty tags (XML_UTIL_COLLAPSE_ALL) or only XHTML tags (XML_UTIL_COLLAPSE_XHTML_ONLY).

Return value

string string with collapsed empty tags

Note

This function should be called statically.

XML_Util::createTag

XML_Util::createTag() – create a tag

Synopsis

string XML_Util::createTag ( string $qname , array $attributes = array() , string $content = null , string $namespaceUri = null , integer $replaceEntities = XML_UTIL_REPLACE_ENTITIES )

Description

create a tag with attributes, namespace and adds 'xmlns' if needed.

Parameter

• string $qname - qualified tag name
• array $attributes - assoc array with attributes
• string $content - string content of the tag
• string $namespaceUri - URI of the namespace if xmlns attribute should be added
• integer $replaceEntities - whether to replace XML entities in content, embedd it in a CData section or leave it untouched. Possible values are FALSE, XML_UTIL_REPLACE_ENTITIES or XML_UTIL_CDATA_SECTION.

Return value

string xml tag

Note

This function should be called statically.

XML_Util::createTagFromArray

XML_Util::createTagFromArray() – create a tag from an array

Synopsis

string XML_Util::createTagFromArray ( array $tag , integer $replaceEntities = XML_UTIL_REPLACE_ENTITIES )

Description

create a tag from an array. This is similar to XML_Util::createTag(), but more flexible.

Parameter

• array $tag - array containing information about the tag
• integer $replaceEntities - whether to replace XML entities in content, embedd it in a CData section or leave it untouched. Possible values are FALSE, XML_UTIL_REPLACE_ENTITIES or XML_UTIL_CDATA_SECTION.

Return value

string xml tag

Note

This function should be called statically.

Usage example

Creating a tag with XML_Util::createTagFromArray()

<?php
require_once "XML/Util.php";

$tag = array(
             "namespace"    => "xslt",
             "localPart"    => "variable",
             "namespaceUri" => "http://www.w3.org/1999/XSL/Transform",
             "attributes"   => array( "name" => "myVar" ),
             "content"      => "myValue"
           );
$string = XML_Util::createTagFromArray($tag);
?>

XML_Util::createStartElement

XML_Util::createStartElement() – create a start element

Synopsis

string XML_Util::createStartElement ( string $qname , array $attributes = array() , string $namespaceUri = null )

Description

create a start element with attributes, namespace and adds 'xmlns' if needed. (<pear foo="bar">)

Parameter

• string $qname - qualified tag name
• array $attributes - assoc array with attributes
• string $namespaceUri - URI of the namespace if xmlns attribute should be added

Return value

string opening xml tag

Note

This function should be called statically.

XML_Util::createEndElement

XML_Util::createEndElement() – create an end element

Synopsis

string XML_Util::createEndElement ( string $qname )

Description

create an end element (</foo>)

Parameter

• string $qname - qualified tag name

Return value

string closing xml tag

Note

This function should be called statically.

XML_Util::createCDataSection

XML_Util::createCDataSection() – create a CData section

Synopsis

string XML_Util::createCDataSection ( string $data )

Description

Creates a CData section, by embedding the data in <!CDATA[ and ]]>. If you use a CData section inside an XML document, entities do not have to be replaced in this sections.

Parameter

• string $data - data for the CData section.

Return value

string CData section

Note

This function should be called statically.

XML_Util::createComment

XML_Util::createComment() – create an XML comment

Synopsis

string XML_Util::createComment ( string $data )

Description

Creates an XML comment, by embedding the supplied data in <!-- and -->.

Parameter

• string $data - data for the comment.

Return value

string comment

Note

This function should be called statically.

XML_Util::getDocTypeDeclaration

XML_Util::getDocTypeDeclaration() – build a document type declaration

Synopsis

string XML_Util::getDocTypeDeclaration ( string $root , mixed $uri = null , mixed $internalDtd = null )

Description

Returns a document type declaration based on parameters.

Parameter

• string $root - root tag
• mixed $uri - URI of the document type definition or array containing the public id and the URI of the DTD
• mixed $internalDtd - internal definitions

Return value

string document type declaration

Note

This function should be called statically.

XML_Util::getXMLDeclaration

XML_Util::getXMLDeclaration() – build an xml declaration

Synopsis

string XML_Util::getXMLDeclaration ( string $version = "1.0" , string $encoding = null , boolean $standalone = null )

Description

Returns an XML declaration based on parameters.

Parameter

• string $version - XML version
• string $encoding - XML encoding
• boolean $standalone - whether document is standalone

Return value

string XML declaration

Note

This function should be called statically.

XML_Util::isValidName

XML_Util::isValidName() – verify an XML name

Synopsis

boolean XML_Util::isValidName ( string $string )

Description

Checks, whether a string is a valid XML name. In XML the names of tags and attributes must follow strict rules. This method can be used to validate the names you are using.

Parameter

• string $string - string to be checked

Return value

Returns TRUE on success, PEAR_Error on failure.

Note

This function should be called statically.

XML_Util::replaceEntities

XML_Util::replaceEntities() – replace XML entities

Synopsis

string XML_Util::replaceEntities ( string $string )

Description

In XML documents you are not allowed to use & and <. The have to be replaced with their respective entities. This method does this for you and furthermore replaces all other predefined XML entities.

Parameter

• string $string - string, in which entities have to be replaced

Return value

string string with entities replaced

Note

This function should be called statically.

XML_Util::reverseEntities

XML_Util::reverseEntities() – replace XML entities

Synopsis

string XML_Util::reverseEntities ( string $string )

Description

This is the reverse function to XML_Util::replaceEntities()(). It replaces all XML (or HTML) entities in a string by their corresponding characters. This can be useful when working with XML documents without using an XML parser.

This method has been added in XML_Util 1.0.0.

Parameter

• string $string - string, in which entities have to be removed

Return value

string string with entities removed

Note

This function should be called statically.

XML_Util::splitQualifiedName

XML_Util::splitQualifiedName() – split qualified name

Synopsis

array XML_Util::splitQualifiedName ( string $qname , string $defaultNs = null )

Description

Splits a qualified name and returns array with namespace and local part.

Parameter

• string $qname - qualified tag name (e.g. xsl:stylsheet)
• string $defaultNs - default namespace, will be used in return value, if qualified name contains only a local part

Return value

array assoc array containing namespace and local part of the tag

Note

This function should be called statically.