README

Installation

Use Composer to install the package:

$ composer require nilportugues/xml

Usage

Given a PHP Object, and a series of mappings, the XML Transformer will represent the given data as a XML object.

For instance, given the following piece of code, defining a Blog Post and some comments:

$post = new Post(
  new PostId(9),
  'Hello World',
  'Your first post',
  new User(
      new UserId(1),
      'Post Author'
  ),
  [
      new Comment(
          new CommentId(1000),
          'Have no fear, sers, your king is safe.',
          new User(new UserId(2), 'Barristan Selmy'),
          [
              'created_at' => (new DateTime('2015/07/18 12:13:00'))->format('c'),
              'accepted_at' => (new DateTime('2015/07/19 00:00:00'))->format('c'),
          ]
      ),
  ]
);

And a Mapping array for all the involved classes:

use NilPortugues\Api\Mapping\Mapper;

$mappings = [
    [
        'class' => Post::class,
        'alias' => 'Message',
        'aliased_properties' => [
            'author' => 'author',
            'title' => 'headline',
            'content' => 'body',
        ],
        'hide_properties' => [

        ],
        'id_properties' => [
            'postId',
        ],
        'urls' => [
            'self' => 'http://example.com/posts/{postId}',
            'comments' => 'http://example.com/posts/{postId}/comments'
        ],
    ],
    [
        'class' => PostId::class,
        'alias' => '',
        'aliased_properties' => [],
        'hide_properties' => [],
        'id_properties' => [
            'postId',
        ],
        'urls' => [
            'self' => 'http://example.com/posts/{postId}',
        ],
    ],
    [
        'class' => User::class,
        'alias' => '',
        'aliased_properties' => [],
        'hide_properties' => [],
        'id_properties' => [
            'userId',
        ],
        'urls' => [
            'self' => 'http://example.com/users/{userId}',
            'friends' => 'http://example.com/users/{userId}/friends',
            'comments' => 'http://example.com/users/{userId}/comments',
        ],
    ],
    [
        'class' => UserId::class,
        'alias' => '',
        'aliased_properties' => [],
        'hide_properties' => [],
        'id_properties' => [
            'userId',
        ],
        'urls' => [
            'self' => 'http://example.com/users/{userId}',
            'friends' => 'http://example.com/users/{userId}/friends',
            'comments' => 'http://example.com/users/{userId}/comments',
        ],
    ],
    [
        'class' => Comment::class,
        'alias' => '',
        'aliased_properties' => [],
        'hide_properties' => [],
        'id_properties' => [
            'commentId',
        ],
        'urls' => [
            'self' => 'http://example.com/comments/{commentId}',
        ],
    ],
    [
        'class' => CommentId::class,
        'alias' => '',
        'aliased_properties' => [],
        'hide_properties' => [],
        'id_properties' => [
            'commentId',
        ],
        'urls' => [
            'self' => 'http://example.com/comments/{commentId}',
        ],
    ],
];

$mapper = new Mapper($mappings);

Calling the transformer will output a valid XML response using the correct formatting:

use NilPortugues\Api\Xml\XmlSerializer;
use NilPortugues\Api\Xml\Http\Message\Response;

$serializer = new XmlSerializer($mapper);
$output = $serializer->serialize($post);

//PSR7 Response with headers and content.
$response = new Response($output);

header(
    sprintf(
        'HTTP/%s %s %s',
        $response->getProtocolVersion(),
        $response->getStatusCode(),
        $response->getReasonPhrase()
    )
);
foreach($response->getHeaders() as $header => $values) {
    header(sprintf("%s:%s\n", $header, implode(', ', $values)));
}

echo $response->getBody();

Output:

HTTP/1.1 200 OK
Cache-Control: private, max-age=0, must-revalidate
Content-type: text/xml; charset=utf-8

<?xml version="1.0" encoding="UTF-8"?>
<data>
  <postId><![CDATA[9]]></postId>
  <headline><![CDATA[Hello World]]></headline>
  <body><![CDATA[Your first post]]></body>
  <author>
    <userId><![CDATA[1]]></userId>
    <name><![CDATA[Post Author]]></name>
  </author>
  <comments>
    <resource>
      <commentId><![CDATA[1000]]></commentId>
      <dates>
        <created_at><![CDATA[2015-07-18T12:13:00+02:00]]></created_at>
        <accepted_at><![CDATA[2015-07-19T00:00:00+02:00]]></accepted_at>
      </dates>
      <comment><![CDATA[Have no fear, sers, your king is safe.]]></comment>
      <user>
        <userId><![CDATA[2]]></userId>
        <name><![CDATA[Barristan Selmy]]></name>
      </user>
    </resource>
  </comments>
  <links>
    <link rel="self" href="http://example.com/posts/9"/>
    <link rel="comments" href="http://example.com/posts/9/comments"/>
  </links>
</data>

Quality

To run the PHPUnit tests at the command line, go to the tests directory and issue phpunit.

This library attempts to comply with PSR-1, PSR-2, PSR-4 and PSR-7.

If you notice compliance oversights, please send a patch via Pull Request.

Contribute

Contributions to the package are always welcome!

Report any bugs or issues you find on the issue tracker.
You can grab the source code at the package's Git repository.

Support

Get in touch with me using one of the following means:

Emailing me at contact@nilportugues.com
Opening an Issue

Authors

License

The code base is licensed under the MIT license.

nilportugues / xml

Maintainers

Details