Manual

Package to "beautify" XML documents. This package will add line breaks, indentation and other layout elements to an XML document, so it can be easier read by humans.

Introduction

Introduction – Introduction to XML_Beautifier

Introduction to XML_Beautifier

XML_Beautifier is a package, that helps you making XML documents easier to read for human beings.

It is able to add line-breaks, indentation, sorts attributes, convert tag cases and wraps long comments. It recognizes tags, character data, comments, XML declarations, processing instructions and external entities and is able to format these tokens nicely.

The document is split into these tokens using the XML_Beautifier_Tokenizer class and the expat parser. Then a renderer is used to create the string representation of the document and formats it using the specified options.

Currently only one renderer is available, but as XML_Beautifier uses a driver-based architecture, other renderers (like syntax-highlighting) will follow soon.

Example

Example – Example for the usage of XML_Beautifier

Basic example

Let's assume, you've got an XML document that is really badly formatted:

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE page [
    <!ENTITY foo SYSTEM "foo.xml">
    <!ENTITY bar SYSTEM "bar.xml">
]>
<document title="Current News">
<meta project="none" foo="bar">
    <keywords/><description/>
<author>Stephan Schmidt</author>
<getMetaNav/>
</meta>
<page label="PHP Application Tools" sublabel="Current News">
<?php
    for($i = 0; $i < count($_GET); $i++) {
        echo    $_GET[$i]."<br>";
    }
?>
&foo;&bar;
<intro>
   <!-- This Comment
has more
    than one line.
                    -->
        <introtitle>Welcome to PHP
Application Tools &amp; PEAR!</introtitle>
<para>
        If you're new to pat, and would like
        <!-- This is a comment in a single line that contains an &amp; -->
         to know
         
         what we do
         
         here, take a look at
         
         <link url=
         "/about/project.xml">
         "About Pat"</link> 
or
check out the
<link url="/about/projectsOverview.xml">"projects overview"</link>. Otherwise, you probably know your way 
around
the site already <smiley type="smile"/>
</para>
                                            </intro>
</page>
</document>

All you have to do is to use XML_Beautifier, pass the filename of the original file and the filename for the new file:

<?php
require_once "XML/Beautifier.php";
$fmt = new XML_Beautifier();
$result = $fmt->formatFile('originalFile.xml', 'beautifiedFile.xml');

if (PEAR::isError($result)) {
    echo $result->getMessage();
    exit();
}
echo "File beautified, awaiting orders!<br />";
?>

And voila, your document looks nice:

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE page [
    <!ENTITY foo SYSTEM "foo.xml">
    <!ENTITY bar SYSTEM "bar.xml">
]>
<document title="Current News">
    <meta foo="bar" project="none">
        <keywords />
        <description />
        <author>Stephan Schmidt</author>
        <getMetaNav />
    </meta>
    <page label="PHP Application Tools" sublabel="Current News">
        <?php
        for($i = 0; $i < count($_GET); $i++) {
                echo    $_GET[$i]."<br>";
            }
        ?>
        &foo;
        &bar;
        <intro>
            <!--
                This Comment
                has more
                than one line.
            -->
            <introtitle>Welcome to PHP Application Tools &amp; PEAR!</introtitle>
            <para>
                If you&apos;re new to pat, and would like
                <!-- This is a comment in a single line that contains an &amp; -->
                to know what we do here, take a look at
                <link url="/about/project.xml">&quot;About Pat&quot;</link>
                or check out the
                <link url="/about/projectsOverview.xml">&quot;projects overview&quot;</link>
                . Otherwise, you probably know your way around the site already
                <smiley type="smile" />
            </para>
        </intro>
    </page>
</document>

Options

Options – List of all XML_Beautifier options

Introduction to options

Options let you influence the beautifiying process. They are passed to the renderer and thus, you have to check, whether the renderer you are using supports the options you want to use.

As there currently is only one renderer (Plain) available, you should not worry about this too much.

Options can be passed as an associative array to the constructor of XML_Beautifier. You may also use setOption(), or setOptions() to set one or more options after the instance of XML_Beautifier has been created.

All available options

Here is a list of all options supported by XML_Beautifier.

XML_Beautifier options
Option	Possible values	Default	Description
removeLineBreaks	TRUE or FALSE	TRUE	Sets, whether linebreaks should be stripped from cdata sections
indent	any string	" " (4 spaces)	The string passed to this option will be used to indent the tags in one level.
linebreak	any string	"\n"	The string passed to this option will be used for linebreaks You should use "\n" or "\r\n".
caseFolding	TRUE or FALSE	FALSE	Disable or enable case folding for tags and attributes
caseFoldingTo	"uppercase" or "lowercase"	"uppercase"	Can be used, if `caseFolding` is set to TRUE to define whether tags and attributes should be converted to upper- or lowercase
normalizeComments	FALSE or TRUE	FALSE	If set to true, all adjacent whitespaces in an XML comment will be converted to one space. This will convert comments with more than one line to a comment with one line.
maxCommentLine	integer	-1	Maximum length of comment line. If a comment exceeds this limit, it will be wrapped automatically. If set to -1 the line length is unlimited.
multilineTags	TRUE or FALSE	FALSE	If set to true, a linebreak will be added inside the tags after each attribute and attributes will be indeted.

Options example

The following example shows how to set options for XML_Beautifier.

Using setOptions() and setOption()

<?php
require_once "XML/Beautifier.php";
$options = array(
                    "caseFolding"       => true,
                    "caseFoldingTo"     => "uppercase",
                    "normalizeComments" => true
                );

$fmt = new XML_Beautifier($options);
$result = $fmt->formatFile('originalFile.xml', 'outputFile.xml');
?>

Options example setting options at a later point

The following example shows how to set options for XML_Beautifier, if the instance already has been created.

XML_Beautifier options

<?php
require_once "XML/Beautifier.php";
$fmt = new XML_Beautifier();
$options = array(
                    "caseFolding"       => true,
                    "caseFoldingTo"     => "uppercase",
                    "normalizeComments" => true
                );

$fmt->setOptions($options);
$fmt->setOption("indent", "\t");
$result = $fmt->formatFile('originalFile.xml', 'outputFile.xml');
?>

XML_Beautifier::XML_Beautifier

XML_Beautifier::XML_Beautifier() – create new instance

Synopsis

require_once 'XML/Beautifier.php';

object XML_Beautifier::XML_Beautifier ( array $options = array() )

Description

Creates a new instance of XML_Beautifier.

Parameter

array $options - options are used to influence to beautifying process. You may set the indent string, specify whether case folding should be enabled, etc... See XML_Beautifier options for more information.

Return value

object XML_Beautifier object

Note

This function can not be called statically.

XML_Beautifier::setOption

XML_Beautifier::setOption() – set an option

Synopsis

require_once 'XML/Beautifier.php';

void XML_Beautifier::setOption ( string $option , mixed $value )

Description

Set an option for the beautifying process.

See XML_Beautifier options for more information.

Parameter

string $option - name of the option
mixed $value - value of the option

Return value

void

Note

This function can not be called statically.

XML_Beautifier::setOptions

XML_Beautifier::setOptions() – set several options

Synopsis

require_once 'XML/Beautifier.php';

void XML_Beautifier::setOptions ( array $options )

Description

Set several options for the beautifying process.

See XML_Beautifier options for more information.

Parameter

array $options - associative array containing options and their values, like you would pass it to the constructor.

Return value

void

Note

This function can not be called statically.

XML_Beautifier::resetOptions

XML_Beautifier::resetOptions() – reset options to default

Synopsis

require_once 'XML/Beautifier.php';

void XML_Beautifier::resetOptions ( )

Description

Reset all options to their default values.

See XML_Beautifier options for more information.

Parameter

This method does not accept any parameters.

Return value

void

Note

This function can not be called statically.

XML_Beautifier::apiVersion

XML_Beautifier::apiVersion() – return API version

Synopsis

require_once 'XML/Beautifier.php';

string XML_Beautifier::apiVersion ( )

Description

Returns API version of XML_Beautifier.

Return value

string API version

Note

This function can be called statically.

XML_Beautifier::formatFile

XML_Beautifier::formatFile() – beautify a file

Synopsis

require_once 'XML/Beautifier.php';

object XML_Beautifier::formatFile ( string $file , string $newFile = null , string $renderer = "Plain" )

Description

Beautifies a file.

Parameter

string $file - filename of the original file
string $newFile - filename for the beautified file. If no file is given, the method will return the resulting XML document. To overwrite the original file, pass XML_BEAUTIFIER_OVERWRITE.
string $renderer - renderer to use, currently only a "Plain" XML renderer can be used.

Return value

mixed Either true, if file has been written or the XML document string.

Note

This function can not be called statically.

XML_Beautifier::formatString

XML_Beautifier::formatString() – beautify a string

Synopsis

require_once 'XML/Beautifier.php';

object XML_Beautifier::formatString ( string $string , string $renderer = "Plain" )

Description

Beautifies an XML string. Use this method to beautify an XML document that has been generated on-the-fly.

Parameter

string $string - string containing an XML document.
string $renderer - renderer to use, currently only a "Plain" XML renderer can be used.

Return value

string beautified XML document

Note

This function can not be called statically.