README

Simple and fast package to convert XML into plain PHP objects.

Why?

Working with third-party APIs often means dealing with raw arrays, stdClass objects or some kind of xml readers.

This package allows you to:

• Convert XML into typed PHP objects
• Use IDE autocompletion and static analysis
• Keep your code clean and maintainable
• Generate model directly from response
• Do it with performance in mind

Note: this package will not be suitable for cases when you need to work with almost raw xml, like parsing metadata fields, reading comments, etc. Take a look at the examples and tests before using.

Requirements

• PHP 8+

Installation

composer require zamaldev/xml-model

Basic Usage

use Zamaldev\XmlModel\XmlModel;

require 'vendor/autoload.php';

class Model {
    public string $key;

    public int $key2;
}

$parser = new XmlModel();

$data = <<<XML
<xml>
    <key>value</key>
    <key2>2</key2>
</xml>
XML;

$model = $parser->parse($data, Model::class);

echo $model->key; // "value"
echo $model->key2; // 2

Key mapping

You can use Attributes\Map property attribute, so map XML keys to model properties.

use Zamaldev\XmlModel\Attributes\Map;
use Zamaldev\XmlModel\XmlModel;

require 'vendor/autoload.php';

class Model {
    #[Map(name: 'key')]
    public string $string;

    #[Map(name: 'key2')]
    public int $int;
}

$parser = new XmlModel();

$data = <<<XML
<xml>
    <key>value</key>
    <key2>2</key2>
</xml>
XML;

$model = $parser->parse($data, Model::class);

echo $model->string; // "value"
echo $model->int; // 2

Arrays

To parse XML into array of models or scalars, Attributes\AsArray property attribute can be used. By default, array will be parsed into array of string, but you can specify type with additional properties.

use Zamaldev\XmlModel\Attributes\AsArray;
use Zamaldev\XmlModel\Attributes\Map;
use Zamaldev\XmlModel\XmlModel;

require 'vendor/autoload.php';

class Model
{
    #[Map(name: '@level')]
    public ?string $level = null;

    /**
     * @var array<Model>
     */
    #[AsArray(itemType: Model::class)]
    public array $item = [];
}

$parser = new XmlModel();

$data = <<<XML
<xml>
    <item level="1">
        <item level="2">
            <item level="3"/>
            <item level="3"/>
            <item level="3"/>
        </item>
        <item level="2">
            <item level="3"/>
            <item level="3"/>
            <item level="3"/>
        </item>
    </item>
</xml>
XML;

$model = $parser->parse($data, Model::class);

echo $model->item[0]->level; // "1"
echo $model->item[0]->item[0]->level; // "2"
echo $model->item[0]->item[0]->item[0]->level; // "3"

DNF types

While working with inconsistent APIs, sometime you may need to support few types per one property. This is possible using Attributes\Caster interface. However, only you know the resolution logic, so you should write your own implementation for your specific case. If you need to cast value to any model, you have the $xmlModel parameter, this is current XmlModel instance, so you could use parse method.

use Zamaldev\XmlModel\Attributes\Caster;
use Zamaldev\XmlModel\XmlModel;
use Zamaldev\XmlModel\XmlModelInterface;

require 'vendor/autoload.php';

#[Attribute(Attribute::TARGET_PROPERTY)]
class CustomCaster implements Caster
{
    public function cast(XmlModelInterface $xmlModel, mixed $value): mixed
    {
        /** @var SimpleXMLElement $value */

        // Here will be your logic.
        if (count($value) > 1) {
            return (array) $value;
        }
        if (count($value->children()) > 0) {
            return $xmlModel->parse($value, Model::class);
        }

        return (string) $value;
    }
}

class Model {
    #[CustomCaster]
    public self|string|array $result;
}

$parser = new XmlModel();

$data = <<<XML
<xml>
    <result>1</result>
    <result>2</result>
    <result>3</result>
</xml>
XML;

$model = $parser->parse($data, Model::class);

echo $model->result[0]; // "1"
echo $model->result[1]; // "2"
echo $model->result[2]; // "3"

$data = <<<XML
<xml>
    <result>1</result>
</xml>
XML;

$model = $parser->parse($data, Model::class);

echo $model->result; // "1"

$data = <<<XML
<xml>
    <result>
        <result>1</result>
    </result>
</xml>
XML;

$model = $parser->parse($data, Model::class);

echo $model->result->result; // "1"

Sanitizer

Don't blind trust any third party API you work with. It is important to validate or at least simple sanitize the input. For this purpose, you can use Attributes\Sanitizer interface. Package already provides Attributes\SimpleSanitizer, but you can write your own for your needs.

use Zamaldev\XmlModel\Attributes\SimpleSanitizer;
use Zamaldev\XmlModel\XmlModel;

require 'vendor/autoload.php';

class Model {
    #[SimpleSanitizer('trim')]
    #[SimpleSanitizer('strtolower')]
    #[SimpleSanitizer('ucfirst')]
    public string $result;
}

$parser = new XmlModel();

$data = <<<XML
<xml>
    <result>   vAlUe   </result>
</xml>
XML;

$model = $parser->parse($data, Model::class);

echo $model->result; // "Value"

Note attributes order. As you can see from example, it goes from top to bottom, so sanitize chain will goes like this:

" vAlUe " -(trim)-> "vAlUe" -(strtolower)-> "value" -(ucfirst)-> "Value"

Generator

Working with many third party requests and huge responses, it is useful to just autogenerate everything. For this purposes XmlGenerator class exists.

Here is an example on how to use it:

use Zamaldev\XmlModel\XmlGenerator;

require 'vendor/autoload.php';

$xml = <<<XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xml>
    <key id="1">
        <subkey id="3"/>
        <subkey id="4"/>
    </key>
    <key id="2">
        <subkey id="5"/>
        <subkey id="6"/>
    </key>
</xml>
XML;

$generate = (new XmlGenerator())
    ->namespace('Demo')
    ->rootModel('Demo')
    ->rootPath(__DIR__)
    ->strictTypes(true)
    ->generate($xml);

This script will generate those files:

// Demo.php
<?php

declare(strict_types=1);

namespace Demo;

use Zamaldev\XmlModel\Attributes\AsArray;

class Demo
{
    /**
     * @var array<DemoKey> $key
     */
    #[AsArray(itemType: DemoKey::class)]
    public array $key = [];
}

// DemoKey.php
<?php

declare(strict_types=1);

namespace Demo;

use Zamaldev\XmlModel\Attributes\AsArray;
use Zamaldev\XmlModel\Attributes\Map;

class DemoKey
{
    /**
     * @var ?string $_id
     */
    #[Map(name: '@id')]
    public ?string $_id = null;

    /**
     * @var array<DemoSubkey> $subkey
     */
    #[AsArray(itemType: DemoSubkey::class)]
    public array $subkey = [];
}

// DemoSubKey.php
<?php

declare(strict_types=1);

namespace Demo;

use Zamaldev\XmlModel\Attributes\Map;

class DemoSubkey
{
    /**
     * @var ?string $_id
     */
    #[Map(name: '@id')]
    public ?string $_id = null;

    /**
     * @var ?string $_
     */
    #[Map(name: '#')]
    public ?string $_ = null;
}

Some rules on how generator works:

• New class names generated at [root model][key]
• If key has prohibited symbols for class properties, they are simply omitted, but Attributes\Map is added
• When there same class name is used for different objects (even with same structure), they resolved with incremental index [root model][key][index]
• If array has different types inside, mixed type will be used, so the xml text values will be used "as is"