servo/fluidxml

Concise and fluent XML manipulation library

![Coveralls Coverage][coveralls-coverage-badge] [][scrutinizer] , _(*1)

, _(*2)

Changelog

2.0.0 (2023-11-06):, _(*3)

PHP 8.1 is the new minimum required version., _(*4)

..., _(*5)

The full changes list., _(*6)

br/, _(*7)

, _(*8)

FluidXML

       , _(*9)

FluidXML is a PHP library designed to manipulate XML documents with a concise and fluent API.br/ It leverages the fluent programming pattern to be fun and effective., _(*10)

$book = fluidxml();

$book->add('title', 'The Theory Of Everything')
     ->add('author', 'S. Hawking')
     ->add('chapters', true)
         ->add('chapter', 'Ideas About The Universe', ['id' => 1])
         ->add('chapter', 'The Expanding Universe',   ['id' => 2]);

Or, if you prefer, there is an extended syntax., _(*11)

$book = new FluidXml();

$book->addChild('title', 'The Theory Of Everything')
     ->addChild('author', 'S. Hawking')
     ->addChild('chapters', true)
         ->addChild('chapter', 'Ideas About The Universe', ['id' => 1])
         ->addChild('chapter', 'The Expanding Universe',   ['id' => 2]);

With FluidXML the DOM manipulation becomes fast, clear and expressive., _(*12)

PHP Arrays are first class citizens., _(*13)

$book->add([ 'title'  => 'The Theory Of Everything',
             'author' => 'S. Hawking',
             'chapters' => [
                    [ 'chapter' => [
                            '@id' => '1',
                            '@'   => 'Ideas About The Universe' ] ],
                    [ 'chapter' => [
                            '@id' => '2',
                            '@'   => 'The Expanding Universe' ] ],
           ]]);

echo $book;

<?xml version="1.0" encoding="UTF-8"?>
<doc>
  <title>The Theory Of Everything</title>
  <author>S. Hawking</author>
  <chapters>
    <chapter id="1">Ideas About The Universe</chapter>
    <chapter id="2">The Expanding Universe</chapter>
  </chapters>
</doc>

XPath is king., _(*14)

$book->query('//title', '//author', '//chapter')
        ->attr('lang', 'en');

And CSS Selectors rock., _(*15)

$book->query('#id', '.class1.class2', 'div p > span')
        ->attr('lang', 'en');

// Many other selectors are available.

XML/CSS Namespaces are fully covered., _(*16)

$book->namespace('xhtml', 'http://www.w3.org/1999/xhtml')
     ->add('xhtml:h1')
     ->query('//xhtml:h1')  // XPath namespace.
     ->query('xhtml|h1');   // CSS namespace.

And sometimes XML Fragments are the fastest way., _(*17)

$book->add(<<<XML
    <cover class="front">
        <img src="http://goo.gl/kO3Iov"/>
    </cover>
    <cover class="back">
        <img src="http://goo.gl/kO3Iov"/>
    </cover>
XML
);

Everything is fluent, even iterations., _(*18)

$book->query('//chapter')->each(function ($i) {
    $this->attr('id', $i);
});

$book->query('//chapters')
        ->times(3)
            ->add('chapter')
        ->times(4, function ($i) {
            $this->add('chapter');
            $this->add('illustration');
        });

You can map nodes easily too., _(*19)

$chaptersIds = $book->query('//chapter')->map(function ($i, $it) {
    return $it->getAttribute('id');
});

$book->query('//chapters')
        ->times(3)
            ->add('chapter')
        ->times(4, function ($i) {
            $this->add('chapter');
            $this->add('illustration');
        });

Whether some queries are too complex to express with XPath/CSS,br/ filtering is your friend., _(*20)

$book->query('//chapters')
        ->filter(function ($i, $node) {
            return $i % 2 === 0;
        })
        ->attr('even');

Interoperability with existing DOMDocument and SimpleXML is simply magic.br/ Import them or inject them in any point of the FluidXML flow just like that., _(*21)

fluidxml($domdocument)
    ->query('/html/body')
         ->add($simplexml);

// Yes, we merged a DOMDocument with a SimpleXMLElement
// and everything is still fluid.

Don't be shy and tell it: « IT'S AWESOME! » ^_^, _(*22)

Many other APIs are available: - __invoke() - append()/appendSibling() - prepend()/prependSibling() - addText() - text()/setText() - addCdata() - cdata()/setCdata() - addComment() - comment()/setComment() - remove() - size()/length() - load() - save() - dom() - xml() - html() - __toString() - array() - ..., _(*23)

Still doubts?

FluidXML is fun to use, concise and effective., _(*24)

If it's not enough, it has a comprehensive test suite with a 100% code coverage., _(*25)

But you'll have the best answer trying it yourself., _(*26)

, _(*27)

Requirements

• FluidXML v2 (latest) requires PHP >= 8.1
• FluidXML v1 (legacy) requires PHP >=5.6 <8

Installation

• Cloning the repository:

git clone https://github.com/servo-php/fluidxml.git

• Using Composer:

composer require servo/fluidxml

Getting Started

• Cloning the repository:

require_once 'FluidXml.php';

• Using Composer:

require_once 'vendor/autoload.php';

use classes and functions as you need., _(*28)

use function \FluidXml\fluidxml;
use function \FluidXml\fluidns;
use function \FluidXml\fluidify;

use \FluidXml\FluidXml;
use \FluidXml\FluidNamespace;

See the documentation to get started and become a ninja., _(*29)

Documentation

_10 minutes reading_br/ Follow the Getting Started tutorial to become a ninja in no time., _(*30)

Many other examples are available: - inside the doc/Examples/ folder - inside the specs/FluidXml.php file (as test cases), _(*31)

All them cover from the simplest case to the most complex scenario., _(*32)

Take a look at the APIs to discover all the available manipulation operations,br/ and go to the Wiki Page for more reading., _(*33)

Donation

If you think this code is awesome or if you want to demonstratebr/ your immense gratitude ♥, buy me a coffe., _(*34)

, _(*35)

, _(*36)

Roadmap

• [ ] Extending the documentation
• [ ] Expanding the APIs

Author

Daniele Orlando <fluidxml@danieleorlando.io>, _(*37)

License

FluidXML is licensed under the BSD 2-Clause License., _(*38)

See doc/LICENSE.txt for the details., _(*39)