ExpressionEngine

2.11.9 User Guide

Retired Documentation

You are using the documentation for version 2.11.9. Go here for the latest version or check here for your available upgrades to the latest version.

XML Parser Class

Calling the XML Parser Class

class XMLparser

ExpressionEngine has an abstracted XML parser that enables developers to work with XML information more easily than with PHP’s built-in XML functions.

To use the XML parser in your modules, you need to first instantiate the XML Parser Class:

ee()->load->library('xmlparser');

Parsing XML

XMLparser::parse_xml($xml)

This method returns an abstracted object containing all of the tags, attributes, and values from the XML. The string parameter must be valid and well-formed XML. Below is an example of the structures generated by this method.

Parameters:
  • $xml (string) – XML to be parsed
Returns:

Parsed XML as an object (see below)
Return type:

XML_Cache object

 
xml_cache Object
(
    [tag] => emails
    [attributes] =>
    [value] =>
    [children] => Array
    (
        [0] => xml_cache Object
        (
            [tag] => email
            [attributes] =>
            [value] =>
            [children] => Array
            (
                [0] => xml_cache Object
                (
                    [tag] => from
                    [attributes] =>
                    [value] => Samantha
                    [children] =>
                )
                [1] => xml_cache Object
                (
                    [tag] => to
                    [attributes] =>
                    [value] => Gertrude
                    [children] =>
                )
                [2] => xml_cache Object
                (
                    [tag] => subject
                    [attributes] =>
                    [value] => You coming to the party?
                    [children] =>
                )
                [3] => xml_cache Object
                (
                    [tag] => message
                    [attributes] => Array
                    (
                        [type] => urgent
                    )
                    [value] => It starts at 9pm.  Don't forget to bring the gruyère!
                    [children] =>
                )
            )
        )
    )
)

With this structure, each tag as an array of objects for each child. In addition to the children array, there are three other variables for each tag object.

Converting Delimited Text to XML

XMLparser::delimited_to_xml($params[, $reduce_null = FALSE])

Takes delimited data and returns XML. Returns FALSE if unable to create XML, and uses the XML class $errors array to log errors encountered. You should always check the $errors array before using the returned XML.

Parameters:
  • $params (array) –

    Associative array of parameters

    • data (string) delimited text data (comma-delimited, tab-delimited, quote-enclosed, etc.)
    • structure (array) structure of the delimited data.
    • root (string) The root XML document tag name. Default is 'root'
    • element (string) The name of the primary element that will be used to enclose each record / row of data. Default is 'element'
    • delimiter (string) The character delimiting the text. The default is \\t (tab).
    • enclosure (string) Character used to enclose the data, such as " in the case of $data = '"item1", "item2", "item3"'; Default is none (empty string)
  • $reduce_null (boolean) – If set to TRUE doesn’t create null elements
Returns:

Generated XML
Return type:

String

Example:

$data = "Samantha|Gertrude|You coming to the party?|It starts at 9pm.  Don't forget to bring the gruyère!
Inigo|Westley|I know something you don't know.|I am not left-handed!";

$params = array(
    'data'      => $data,
    'structure' => array("from", "to", "subject", "message"),
    'delimiter' => "|",
    'root'      => "emails",
    'element'   => "email"
);

$xml = ee()->xmlparser->delimited_to_xml($params);

Result:

<emails>
    <email>
        <from>Samantha</from>
        <to>Gertrude</to>
        <subject>You coming to the party?</subject>
        <message>It starts at 9pm.  Don't forget to bring the gruyère!</message>
    </email>
    <email>
        <from>Inigo</from>
        <to>Westley</to>
        <subject>I know something you don't know.</subject>
        <message>I am not left-handed!</message>
    </email>
</emails>

Checking for Errors

property XMLparser::$errors

You should always check for the presence of errors before using the returned XML. This will allow you to tell which records were skipped and unable to be used in the XML. XMLparser::delimited_to_xml will only return FALSE on fatal errors, as in some cases it may be acceptable to ignore the errors.

if ( ! empty(ee()->xmlparser->errors))
{
    echo "Could not convert to XML:<br /><br />";

    foreach (ee()->xmlparser->errors as $error)
    {
        echo "{$error}<br />";
        exit;
    }
}

You can also take advantage of ExpressionEngine’s error display methods to generate a more UI consistent error page.

if ( ! empty(ee()->xmlparser->errors))
{
  // frontend
  ee()->output->show_user_error('general', ee()->xmlparser->errors);

  // control panel
  show_error(ee()->xmlparser->errors);
}