PHP Classes

\Xmtk\Parser: Restructure the XML parsing results conveniently

Recommend this page to a friend!
     
  Info   View files Files   Install with Composer Install with Composer   Download Download   Reputation   Support forum   Blog    
Ratings Unique User Downloads Download Rankings
Not enough user ratingsTotal: 104 All time: 9,744 This week: 660Up
Version License PHP version Categories
xmtk-parser 1.0MIT/X Consortium ...7.0XML, PHP 5
Description 

Author

This class can restructure the XML parsing results conveniently.

It can transform results of the xml_parse_into_struct() function into form, more convenient to understand and to work with.

Innovation Award
PHP Programming Innovation award nominee
September 2017
Number 12
This class can restructure the XML parsing results conviniently.

It can transform results of the xml_parse_into_struct() function into form, more convenient to understand and to work with.

Manuel Lemos
Picture of Vasily Blinkov
Name: Vasily Blinkov <contact>
Classes: 1 package by
Country: Russian Federation Russian Federation
Age: 34
All time rank: 4401125 in Russian Federation Russian Federation
Week rank: 178 Up10 in Russian Federation Russian Federation Up
Innovation award
Innovation award
Nominee: 1x

Details

CHANGELOG

2017-12-24. Overridable errors handling.

2017-12-02. Add the \Xmtk\CData class.

2017-11-26. The unit testing using GitLab CI and PHPUnit was implemented.

2017-09-17. Breaking change: the xml_parse_into_array() method of the Parser class has been renamed to xmlParseIntoArray() according to PHP-FIG's PSR.

2017-09-30. Introduced the Xmtk\Writer class to write XML from arrays.

ABOUT

What Xmtk is?

xml parser

Xmtk is a wrapper around the xml_parse_into_struct() function. It parses XML strings into the structs using the above function, but then transforms its result into easy-to-handle array hierarchies. Please, see example 1 to get the difference.

xml writer

The \Xmtk\Writer class writes hierarchical arrays to XML files. In other words Writer aimed to do the reverse work of Parser. See example 2.

cdata

There is the \Xmtk\CData class in the package. It offers the encode() method to convert strings to CData forms. See the 3rd example to learn why this class useful.

example 1

This example shows the difference between the result. Look at the listing 1. It is the input XML. Listing 2 shows what result the xml_parse_into_struct() will return. And, finally, listing 3 is the result of \Xmtk\Parser work.

example 2

\Xmtk\Writer will convert the arrays looking like in the listing 3 below into XML string like shown in the listing 1.

example 3

Let's suppose you need to put HTML markup into the some tag of XML. The next code will not work correctly.

$writer = new \Xmtk\Writer;
$xml = $writer->xmlWriteFromArray(
	['markup'=>'<strong>text</strong>']);

The value of the $xml variable in this example will be: <markup><strong>text</strong></markup>. This is wrong. To fix this situation you may use the \Xmtk\CData class next way.

$cdata = new \Xmtk\CData;
$xml = $writer->xmlWriteFromArray(
	['markup'=>$cdata->encode('<strong>text</strong>')]);

The output XML will look like the next one.

<markup><![CDATA[<strong>text</strong>]]></markup>

listing 1 (input xml)

<bike>
	<wheel>front</wheel>
	<wheel>rear</wheel>
	<chain>
		<length>1</length>
	</chain>
</bike>

listing 2 (php function)

Array
(
    [0] => Array
        (
            [tag] => bike
            [type] => open
            [level] => 1
            [value] =>

        )

    [1] => Array
        (
            [tag] => wheel
            [type] => complete
            [level] => 2
            [value] => front
        )

    [2] => Array
        (
            [tag] => bike
            [value] =>

            [type] => cdata
            [level] => 1
        )

    [3] => Array
        (
            [tag] => wheel
            [type] => complete
            [level] => 2
            [value] => rear
        )

    [4] => Array
        (
            [tag] => bike
            [value] =>

            [type] => cdata
            [level] => 1
        )

    [5] => Array
        (
            [tag] => chain
            [type] => open
            [level] => 2
            [value] =>

        )

    [6] => Array
        (
            [tag] => length
            [type] => complete
            [level] => 3
            [value] => 1
        )

    [7] => Array
        (
            [tag] => chain
            [value] =>

            [type] => cdata
            [level] => 2
        )

    [8] => Array
        (
            [tag] => chain
            [type] => close
            [level] => 2
        )

    [9] => Array
        (
            [tag] => bike
            [value] =>

            [type] => cdata
            [level] => 1
        )

    [10] => Array
        (
            [tag] => bike
            [type] => close
            [level] => 1
        )

)

listing 3 (parser wrapper)

Array
(
    [bike] => Array
        (
            [wheel] => Array
                (
                    [0] => front
                    [1] => rear
                )

            [chain] => Array
                (
                    [length] => 1
                )

        )

)

What Xmtk stands for?

Xmtk stands for eXtensible Markup Tool-Kit. Thanks for your interest.

USAGE

Requirements

In November, 2017 the project has been migrated to PHP 7.0. This migration was intended to avoid usage of legacy PHPUnit.

Setup

composer require xmtk/xmtk

\Xmtk\Parser

php

#!/usr/local/bin/php
<?php
require_once __DIR__.'/vendor/autoload.php';

$parser = new \Xmtk\Parser;

$xml = '<bike>
	<wheels>
		<wheel>The front one</wheel>
		<wheel>The rear one</wheel>
	</wheels>
	<chain>
		<count>191</count>
	</chain>
</bike>';

$result = $parser->xmlParseIntoArray($xml);
print_r($result);

?>

output

Array
(
    [bike] => Array
        (
            [wheels] => Array
                (
                    [wheel] => Array
                        (
                            [0] => The front one
                            [1] => The rear one
                        )

                )

            [chain] => Array
                (
                    [count] => 191
                )

        )

)

\Xmtk\Writer

The \Xmtk\Writer class accepts arrays in the same format as the \Xmtk\Parser returns. See below for the usage example.

require_once __DIR__.'/../vendor/autoload.php';
$writer = new \Xmtk\Writer;
$array = ['collection' => ['item' => ['salad', 'napkins', 'insecticide']]];
$xml = $writer->xmlWriteFromArray($array);
print_r($xml);
/* // Output.
<?xml version='1.0'?>
<collection>
    <item>salad</item>
    <item>napkins</item>
    <item>insecticide</item>
</collection>
*/

Error Handling

Instances of the \Xmtk\Parser class returns empty arrays (array()) if you passed invalid XML string, or arrays with parsed beginnings of XML strings with valid start but invalid continuation. In other words the instances of the Parser always return at least empty arrays in case of error.

Instances of the \Xmtk\Writer will interrupt execution of your scripts in case of errors with the exit() PHP construct. For example if you will pass non-array variable to the xmlWriteFromArray() method of the Writer instance. At the moment of writing this documentation the \Xmtk\Writer offered the possibility to override this behavior.

To implement custom error handling you just need to implement a descendant class inherit it from the \Xmtk\Writer and override its error() method. This method gets a single parameter $message of type string. It holds the error message. The example is below.

implementing a writer with custom error handling

class MyWriter extends Writer {
	public $err_msg;
	protected function error(string $message) {
		$this->err_msg = $message;
	}
}

unit test to check if the error handling implemented properly

\Xmtk\Writer->xmlWriteFromArray() return value

The \Xmtk\Writer->xmlWriteFromArray() method returns string values when passed array structure of the XML document had been serialized properly or empty string ('') otherwise.

function testCanGetErrorMessageForCustomHandling() {
	$my_writer = new MyWriter;
	$my_writer->xmlWriteFromArray(NULL);
	$this->assertEquals(
		'\\Xmtk\\Writer: xmlWriteFromArray() expects an array.',
		$my_writer->err_msg);
}

class diagram

cd

As you can see, it is possible to override error handling in the descendants of the Parser class too. It may have effect in a future.

IMPORTANT NOTES

arrays

The \Xmtk\Parser treats repeating tags placed on the same level as arrays. This means that if you have two or more <bar/> tags inside the <foo/> node, then the array for the foo tag will have child array bar indexed by numbers. Look at the <wheel/> tags in the listing 1 and how they were processed by the \Xmtk\Parser in the listing 3.

invalid xml

Results of \Xmtk\Parser work in cases when XML is invalid or partially valid will be the same as of the underlying xml_parse_into_struct() function: empty arrays (when XML is invalid) or arrays with the parsed beginning of the XML (in cases when the beginning part of XML is valid).

For example:

invalid xml

Unit test:

function testCanReturnEmptyArrayIfXmlIsInvalid() {
	$value = $this->parser->xmlParseIntoArray(
		'invalid XML');
	$this->assertTrue(is_array($value));
	$this->assertEquals(0, count($value));
	}

The value of the $value variable is:

Array
(
)

partially valid xml

Unit test:

function testCanParseFirstTagOfTwoWithoutRoot() {
	$value = $this->parser->xmlParseIntoArray(
		'<tag>1</tag><node>2</node');
	$this->assertTrue(is_array($value));
	$this->assertEquals(1, count($value));
	$this->assertArrayHasKey('tag', $value);
	$this->assertEquals('1', $value['tag']);
}

Result of the $this->parser->xmlParseIntoArray() is:

Array
(
    [tag] => 1
)

KNOWN ISSUES

attributes

All we love XML attributes. But support of this important XML specification part is not implemented yet. Contribute if you see that Xmtk is cool!

DEVELOPMENT

Tools

  • PL: Xmtk written in the PHP7 programming language. You may need to install the next packages (FreeBSD 10.x): `php70`, `php70-filter`, `php70-hash`, `php70-iconv`, `php70-json`, `php70-openssl`, `php70-phar`, `php70-xml`, `php70-zlib`.
  • IDE: Not used (no projects like `nbproject/`).
  • UT: PHPUnit is the unit-testing framework used. Install it according to the official manual.

composer

Composer is used as an application level package manager. You may want to install Composer to your system for more convenient development process. For FreeBSD the command to setup Composer system-widely will look like the next one.

sudo pkg install php-composer

tests

This package uses PHPUnit for unit testing. PHPUnit should be installed to the $PATH.

To run test you can use make. There are several targets in the Makefile.

  1. `parser-tests` is to run only unit tests to test the `Parser` class.
  2. `writer-tests` is to run only unit tests to test the `Writer` class.
  3. `cdata-tests` is to run only unit tests to test the `CData` class.
  4. `tests` is to run all the unit testing targets defined in the `Makefile`: `parser-tests`, `writer-tests`, `cdata-tests` etc.

EXAMPLES

make tests
make parser-tests


  Files folder image Files (12)  
File Role Description
Files folder imagesrc (5 files)
Files folder imagetests (3 files)
Accessible without login Plain text file composer.json Data Composer package configuration.
Accessible without login Plain text file composer.lock Data Composer dependencies lock file.
Accessible without login Plain text file Makefile Data Auxiliary data
Accessible without login Plain text file README.md Doc. README file. Documentation.

  Files folder image Files (12)  /  src  
File Role Description
  Plain text file CData.php Class Class source
  Plain text file Composite.php Class Class source
  Plain text file ErrorHandler.php Class Class source
  Plain text file Parser.php Class The class.
  Plain text file Writer.php Class Class source

  Files folder image Files (12)  /  tests  
File Role Description
  Accessible without login Plain text file CDataTests.php Test Class source
  Accessible without login Plain text file ParserTests.php Test Class source
  Accessible without login Plain text file WriterTests.php Test Class source

The PHP Classes site has supported package installation using the Composer tool since 2013, as you may verify by reading this instructions page.
Install with Composer Install with Composer
 Version Control Unique User Downloads Download Rankings  
 100%
Total:104
This week:0
All time:9,744
This week:660Up