Home » XML » XML_Serializer » Manual

Introduction

Introduction – Introduction to XML_Serializer

Introduction to XML_Serializer

XML_Serializer serializes complex data structures like arrays or object as XML documents. This class helps you generating any XML document you require without the need for DOM.

Currently there are two ways in which XML_Serializer can be used in your applications:

• use XML_Serializer's functionality to create XML documents in a specific XML application (e.g. RDF) that is being processed by an existing script)
• use XML_Serializer's functionality to serialize data structures that have to be unserialized at a later point. This is possible by adding type information to all XML elements.

The package not only contains a serializer class but also a matching XML_Unserializer, which is able to virtually read any XML document and return an array or object structure that represents the data stored in the document.

Tutorials on XML_Serializer

There are several tutorials on XML_Serializer available, that help you get started.

• Create a RSS newsfeed with XML_Serializer (local) by cnb
• Instant XML with PHP and PEAR::XML_Serializer by Harry Fuecks
• Serializing XML With PHP by Vikram Vaswani

Package XML_Serializer Constants

Package XML_Serializer Constants – Constants defined in and used by XML_Serializer

All Constants

Constants defined in Serializer.php

Constants defined in Unserializer.php

Class Summary XML_Serializer

Class Summary XML_Serializer – XML_Serializer - class that serializes various structures into an XML document

XML_Serializer - class that serializes various structures into an XML document

This class can be used in two modes:

1. Create an XML document from an array or object that is processed by other applications.
2. This classes can be used to serialize any data structure in a way that it can later be unserialized again. XML_Serializer will store the type of the value and additional meta information in attributes of the surrounding tag. This meta information can later be used to restore the original data structure in PHP.

constructor XML_Serializer::XML_Serializer

constructor XML_Serializer::XML_Serializer() – constructor

Synopsis

void constructor XML_Serializer::XML_Serializer ( mixed $options = null )

Description

This package is not documented yet.

Parameter

mixed $options

array containing options for the serialization

Throws

throws no exceptions thrown

Note

This function can not be called statically.

XML_Serializer::apiVersion

XML_Serializer::apiVersion() – return API version

Synopsis

string XML_Serializer::apiVersion ( )

Description

This package is not documented yet.

Return value

returns API version

Throws

throws no exceptions thrown

static

static

Note

This function can not be called statically.

XML_Serializer::serialize

XML_Serializer::serialize() – serialize data

Synopsis

boolean XML_Serializer::serialize ( mixed $data , mixed $options = null )

Description

This package is not documented yet.

Parameter

mixed $data

data to serialize

mixed $options

Return value

returns true on success, pear error on failure

Throws

throws no exceptions thrown

Note

This function can not be called statically.

XML_Serializer::getSerializedData

XML_Serializer::getSerializedData() – get the result of the serialization

Synopsis

string XML_Serializer::getSerializedData ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

XML_Serializer::resetOptions

XML_Serializer::resetOptions() – reset all options to default options

Synopsis

void XML_Serializer::resetOptions ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

See

see XML_Serializer::setOption(), XML_Unserializer()

Note

This function can not be called statically.

XML_Serializer::setOption

XML_Serializer::setOption() – set an option

Synopsis

void XML_Serializer::setOption ( mixed $name , mixed $value )

Description

You can use this method if you do not want to set all options in the constructor

Parameter

mixed $name

mixed $value

Throws

throws no exceptions thrown

See

see resetOption(), XML_Serializer::XML_Serializer()

Note

This function can not be called statically.

Example

Example – Example for the usage of XML_Serializer

Build a simple XML document

Example that uses the returnResult option to directly return the serialized XML document in the serialize() method.

In this example look at theses 3 lines.

<?php
$serializer = &new XML_Serializer($options);
$foo = PEAR::raiseError('Just a test', 1234);
$result = $serializer->serialize($foo);
?>

<?php
error_reporting(E_ALL);
require_once 'XML/Serializer.php';
$options = array(
  XML_SERIALIZER_OPTION_INDENT        => '    ',
  XML_SERIALIZER_OPTION_RETURN_RESULT => true
  );

$serializer = &new XML_Serializer($options);

$foo = PEAR::raiseError('Just a test', 1234);

$result = $serializer->serialize($foo);

echo '<pre>';
echo htmlspecialchars($result);
echo '</pre>';
?>

And this is the result

<pear_error>
    <error_message_prefix />
    <mode>1</mode>
    <level>1024</level>
    <code>1234</code>
    <message>Just a test</message>
    <userinfo />
    <backtrace>
        <XML_Serializer_Tag>
            <file>pathToMypear\PEAR.php</file>
            <line>566</line>
            <function>pear_error</function>
            <class>pear_error</class>
            <type>-&gt;</type>
            <args>
                <XML_Serializer_Tag>Just a test</XML_Serializer_Tag>
                <XML_Serializer_Tag>1234</XML_Serializer_Tag>
                <XML_Serializer_Tag>1</XML_Serializer_Tag>
                <XML_Serializer_Tag>1024</XML_Serializer_Tag>
                <XML_Serializer_Tag />
            </args>
        </XML_Serializer_Tag>
        <XML_Serializer_Tag>
            <file>pathToMyDocRoot\cvs.php.net\pear\xml_serializer\examples\serializeandreturn.php</file>
            <line>19</line>
            <function>raiseerror</function>
            <class>pear</class>
            <type>::</type>
            <args>
                <XML_Serializer_Tag>Just a test</XML_Serializer_Tag>
                <XML_Serializer_Tag>1234</XML_Serializer_Tag>
            </args>
        </XML_Serializer_Tag>
    </backtrace>
    <callback />
</pear_error>

You can find the last version of this source code in the package : serializeAndReturn.php

Build a RDF document

This example shows how to create an RDF document with a few lines of code. This can also be done with mode => simplexml.

In this example look at theses 3 lines.

<?php
$serializer = new XML_Serializer($options);
    $result = $serializer->serialize($rdf);
    echo    htmlentities($serializer->getSerializedData());
?>

<?php
/**
   * @see    serializeIndexedArray.php
   */
    error_reporting(E_ALL);

    require_once 'XML/Serializer.php';

    $options = array(
      "indent"          => "    ",
      "linebreak"       => "\n",
      "typeHints"       => false,
      "addDecl"         => true,
      "encoding"        => "UTF-8",
      "rootName"        => "rdf:RDF",
      "rootAttributes"  => array("version" => "0.91"),
      "defaultTagName"  => "item",
      "attributesArray" => "_attributes"
      );
    
    $serializer = new XML_Serializer($options);

    $rdf = array(
      "channel" => array(
        "title" => "Example RDF channel",
        "link"  => "http://www.php-tools.de",
        "image" => array(
          "title" => "Example image",
          "url"   => "http://www.php-tools.de/image.gif",
          "link"  => "http://www.php-tools.de"
          ),
        "_attributes" => array( "rdf:about" => "http://example.com/foobar.html" ),
        array(
          "title"       => "Example item",
          "link"    => "http://example.com",
          "_attributes" => array( "rdf:about" => "http://example.com/foobar.html" )
          ),
        array(
          "title"    => "Another item",
          "link"    => "http://example.com",
          "_attributes" => array( "rdf:about" => "http://example.com/foobar.html" )
          ),
        array(
          "title"    => "I think you get it...",
          "link"    => "http://example.com",
          "_attributes" => array( "rdf:about" => "http://example.com/foobar.html" )
          )
        )
      );
    
    $result = $serializer->serialize($rdf);
    
    if( $result === true ) {
        echo    "<pre>";
        echo    htmlentities($serializer->getSerializedData());
        echo    "</pre>";
    }
?>

And this is the result

<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF version="0.91">
    <channel rdf:about="http://example.com/foobar.html">
        <title>Example RDF channel</title>
        <link>http://www.php-tools.de</link>
        <image>
            <title>Example image</title>
            <url>http://www.php-tools.de/image.gif</url>
            <link>http://www.php-tools.de</link>
        </image>
        <item rdf:about="http://example.com/foobar.html">
            <title>Example item</title>
            <link>http://example.com</link>
        </item>
        <item rdf:about="http://example.com/foobar.html">
            <title>Another item</title>
            <link>http://example.com</link>
        </item>
        <item rdf:about="http://example.com/foobar.html">
            <title>I think you get it...</title>
            <link>http://example.com</link>
        </item>
    </channel>
</rdf:RDF>

You can find the last version of this source code in the package : serializeRDF.php

Note : if you search how to parse (read) an RDF/RSS document, look at XML_RSS package.

Build a XML document with a DTD

This example shows how to add a DocType Declaration to the XML document

In this example look at theses 3 lines.

<?php
$serializer = new XML_Serializer($options);
    $result = $serializer->serialize($rdf);
    echo    htmlentities($serializer->getSerializedData());
?>

<?php
error_reporting(E_ALL);

    require_once 'XML/Serializer.php';

    $options = array(
      "indent"     => "    ",
      "linebreak"  => "\n",
      "addDecl"    => true,
      "addDoctype" => true,
      "doctype"    => array(
        'uri' => 'http://pear.php.net/dtd/package-1.0',
        'id'  => '-//PHP//PEAR/DTD PACKAGE 0.1'
        )
      );
    
    $serializer = new XML_Serializer($options);

    $foo    =   PEAR::raiseError("Just a test", 1234);    
    
    $result = $serializer->serialize($foo);
    
    if( $result === true ) {
        echo '<pre>';
        echo htmlentities($serializer->getSerializedData());
        echo '</pre>';
    }
?>

And this is the result

<?xml version="1.0"?>
<!DOCTYPE pear_error PUBLIC "-//PHP//PEAR/DTD PACKAGE 0.1" "http://pear.php.net/dtd/package-1.0">
<pear_error>
    <error_message_prefix />
    <mode>1</mode>
    <level>1024</level>
    <code>1234</code>
    <message>Just a test</message>
    <userinfo />
    <backtrace>
        <XML_Serializer_Tag>
            <file>pathToMyPear\PEAR.php</file>
            <line>566</line>
            <function>pear_error</function>
            <class>pear_error</class>
            <type>-&gt;</type>
            <args>
                <XML_Serializer_Tag>Just a test</XML_Serializer_Tag>
                <XML_Serializer_Tag>1234</XML_Serializer_Tag>
                <XML_Serializer_Tag>1</XML_Serializer_Tag>
                <XML_Serializer_Tag>1024</XML_Serializer_Tag>
                <XML_Serializer_Tag />
            </args>
        </XML_Serializer_Tag>
        <XML_Serializer_Tag>
            <file>pathToMyDocumentRoot\cvs.php.net\pear\xml_serializer\examples\serializewithdtd.php</file>
            <line>24</line>
            <function>raiseerror</function>
            <class>pear</class>
            <type>::</type>
            <args>
                <XML_Serializer_Tag>Just a test</XML_Serializer_Tag>
                <XML_Serializer_Tag>1234</XML_Serializer_Tag>
            </args>
        </XML_Serializer_Tag>
    </backtrace>
    <callback />
</pear_error>

You can find the last version of this source code in the package : serializeWithDTD.php

Tutorial: Create an RSS Feed

Tutorial: Create an RSS Feed – How to use XML_Serializer to build an RSS Newsfeed

Mission

This tutorial has been written by cnb and been published on http://freedomink.org/node/62. The site is offline since 2005 and has been rescued using the Internet Archive's Wayback Machine.

Here's how you can create an XML news feed in just five minutes using PHP, PEAR and the PEAR XML_Serializer package by Stephan Schmidt.

What a news feed consists of in it's barest form is your "site name", "site url" and a "listing of stories" from your site. To create a news feed what we need to do is create a publically accessible (web) document which can show this information in a format other sites can understand. This is possible by creating this document in the standard RDF Site Summary (RSS) format. A format used by many sites.

What we are aiming at is creating a document which looks like the following:

This isn't "well formed" XML but a stripped version making it as simple as possible for illustrative purposes. Once we understand the basics we can move on to create well formed XML.

<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF>
    <channel>
        <title>Freedom Ink</title>
        <link>http://freedomink.org/</link>
        <item>
            <item>
                <title>First Article</title>
                <link>http://freedomink.org/node/view/55</link>
                <description>Short blurb about article........</description>
            </item>
            <item>
                <title>Second Article</title>
                <link>http://freedomink.org/node/view/11</link>
                <description>This article shows you how ......</description>
            </item>
        </item>
    </channel>
</rdf:RDF>

Do it in PHP

Here's an easy way to do it in PHP.

Prerequisite: Install PEAR and the XML_Serializer package.

Include the following default options at the top of your php page.

<?php
require_once 'XML/Serializer.php';

$options = array(
    "indent"    => "    ",
    "linebreak" => "\n",
    "typeHints" => false,
    "addDecl"   => true,
    "encoding"  => "UTF-8",
    "rootName"   => "rdf:RDF",
    "defaultTagName" => "item"
);
?>

Let us first create an array containing a listing of the stories on your site.

We create array $stories and add one story.

<?php
$stories[] = array(
    'title'       => 'First Article',
    'link'        => 'http://freedomink.org/node/view/55',
    'description' => 'Short blurb about article........'
);
?>

You can add more stories to the array in the same manner. Ideally this should be done in a "for" or "foreach" loop.

<?php
$stories[] = array(
    'title'       => 'Second Article',
    'link'        => 'http://freedomink.org/node/view/11',
    'description' => 'This article shows you how ......'
);
?>

Finally we specify the channel details and add the stories to it.

<?php
$data['channel'] = array(
    "title" => "Freedom Ink",
    "link"  => "http://freedomink.org/",
    $stories
);
?>

Now we generate the XML using the PEAR XML_Serializer package.

<?php
$serializer = new XML_Serializer($options);

if ($serializer->serialize($data)) {
    header('Content-type: text/xml');
    echo $serializer->getSerializedData();
}
?>

And that's it! When a person visits the page containing this code an XML file like the one we saw above will be generated and served.

To learn how to parse XML/RSS files you can read this related article which has by far the easiest method of parsing XML/RSS documents.

Class Summary XML_Unserializer

Class Summary XML_Unserializer – XML_Unserializer - class to unserialize (read) XML documents

XML_Unserializer - class to unserialize (read) XML documents

Class to unserialize XML documents that have been created with XML_Serializer. To unserialize an XML document you have to add type hints to the XML_Serializer options.

If no type hints are available, XML_Unserializer will guess how the tags should be treated, that means complex structures will be arrays and tags with only CData in them will be strings.

XML_Unserializer Options

XML_Unserializer Options – List of all XML_Unserializer options

Introduction to options

Options let you influence how XML_Unserializer treats the parsed XML. It allows you to define whether attributes should be parsed, whether to use associative arrays or objects for complex data types, and more.

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

All available options

Here is a list of all options supported by XML_Unserializer.

Options via XML_UNSERIALIZER_OPTION Constants example

The following examples shows how to set options for XML_Unserializer, using the available XML_UNSERIALIZER_OPTION constants.

Using the constructor

<?php
require_once "XML/Unserializer.php";
$options = array(
    XML_UNSERIALIZER_OPTION_COMPLEXTYPE => 'array'
);

$us = new XML_Unserializer($options);
$result = $us->unserialize('example.xml', true);
?>

The following example shows how to set options for XML_Unserializer, using the available XML_UNSERIALIZER_OPTION constants, if the instance already has been created.

Using setOption() and setOptions()

<?php
require_once "XML/Unserializer.php";
$us = new XML_Unserializer();
$options = array(
    XML_UNSERIALIZER_OPTION_TAG_MAP         => array( 'util' => 'XML_Util' ),
    XML_UNSERIALIZER_OPTION_ATTRIBUTE_CLASS => '_classname'
);

$us->setOptions($options);
$us->setOption(XML_UNSERIALIZER_OPTION_COMPLEXTYPE, 'object');
$result = $us->unserialize('example.xml', true);
?>

Options via $options examples

The following example shows how to set options for XML_Unserializer, using an $options array.

Using the constructor

<?php
require_once "XML/Unserializer.php";
$options = array(
    'complexType' => 'array'
);

$us = new XML_Unserializer($options);
$result = $us->unserialize('example.xml', true);
?>

The following example shows how to set options for XML_Unserializer, using an $options array, if the instance already has been created.

Using setOption() and setOptions()

<?php
require_once "XML/Unserializer.php";
$us = new XML_Unserializer();
$options = array(
    'tagMap'         => array( 'util' => 'XML_Util' ),
    'classAttribute' => '_classname'
);

$us->setOptions($options);
$us->setOption('complexType', 'object');
$result = $us->unserialize('example.xml', true);
?>

XML_Unserializer::XML_Unserializer

XML_Unserializer::XML_Unserializer() – Constructor for XML_Unserializer

Synopsis

XML_Unserializer::XML_Unserializer ( array $options = null )

Description

Creates a new instance of XML_Unserializer.

Parameter

• array $options - Options for the instance. Can also be set using XML_Unserializer::setOption()

Note

This function can not be called statically.

XML_Unserializer::apiVersion

XML_Unserializer::apiVersion() – return API version

Synopsis

string XML_Unserializer::apiVersion ( )

Description

Returns API version of XML_Unserializer. This may be useful to check if the needed functionality exists.

Return value

string API version

Note

This function can be called statically.

XML_Unserializer::unserialize

XML_Unserializer::unserialize() – unserialize data

Synopsis

boolean XML_Unserializer::unserialize ( string $data , boolean $isFile = false , array $options = null )

Description

Unserialize an XML document from a string or a file.

The way the document is unserialized is influenced by the options you set in the constructor or with setOptions().

Parameter

• string $data - either the file name of an XML document or a string containing the XML document.
• boolean $isFile - indicates whether the first parameter should is a filename (TRUE) or an XML string (FALSE).
• array $options - Options to override the options that have been set previously. The options will only be used for this unserialization and then reset the options you set before.

Return value

Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

XML_Unserializer::getUnserializedData

XML_Unserializer::getUnserializedData() – get the result of the unserialization

Synopsis

string XML_Unserializer::getUnserializedData ( )

Description

This method returns the result of the last unserialization. You have to call XML_Unserializer::unserialize() first.

Return value

mixed result of the unserialization. May either be an array or an object.

Throws

throws PEAR_Error object, if not document has been parsed.

Note

This function can not be called statically.

XML_Unserializer::getRootName

XML_Unserializer::getRootName() – get the name of the root tag of the parsed document.

Synopsis

string XML_Unserializer::getRootName ( )

Description

This method will return the name of the root tag, after a document has been unserialized. This can be extremely useful when returning an array. You have to call XML_Unserializer::unserialize() first.

Return value

string name of the root tag

Throws

throws PEAR_Error object, if not document has been parsed.

Note

This function can not be called statically.

XML_Unserializer::setOption

XML_Unserializer::setOption() – set an option

Synopsis

void XML_Unserializer::setOption ( string $name , mixed $value )

Description

Options influence the behaviour of XML_Unserializer and are the most important part of XML_Unserializer.

You can use this method if you do not want to set all options in the constructor.

Parameter

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

See

see XML_Unserializer::resetOptions()

Note

This function can not be called statically.

XML_Unserializer::setoptions

XML_Unserializer::setoptions() – set several options

Synopsis

void XML_Unserializer::setOptions ( array $options )

Description

Options influence the behaviour of XML_Unserializer and are the most important part of XML_Unserializer.

You can use this method if you do not want to set all options in the constructor.

Parameter

• array $options - assoc array containing all options

See

see XML_Unserializer::resetOptions(), XML_Unserializer::setOption()

Note

This function can not be called statically.

XML_Unserializer::resetOptions

XML_Unserializer::resetOptions() – reset all options to default options

Synopsis

void XML_Unserializer::resetOptions ( )

Description

Resets all XML_Unserializer options to the default options.

See

see XML_Unserializer::setOption() and XML_Unserializer::XML_Unserializer() on how to set options.

Note

This function can not be called statically.