README.md

Changelog

2.0.0 (2023-11-06):

PHP 8.1 is the new minimum required version.

...

The full changes list.

FluidXML

      

FluidXML is a PHP library designed to manipulate XML documents with a concise and fluent API.
It leverages the fluent programming pattern to be fun and effective.

$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.

$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.

PHP Arrays are first class citizens.

$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.

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

And CSS Selectors rock.

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

// Many other selectors are available.

XML/CSS Namespaces are fully covered.

$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.

$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.

$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.

$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,
filtering is your friend.

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

Interoperability with existing DOMDocument and SimpleXML is simply magic.
Import them or inject them in any point of the FluidXML flow just like that.

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! » ^_^

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()
• ...

Still doubts?

FluidXML is fun to use, concise and effective.

If it's not enough, it has a comprehensive test suite with a 100% code coverage.

But you'll have the best answer trying it yourself.

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.

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.

Documentation

10 minutes reading
Follow the Getting Started tutorial to become a ninja in no time.

Many other examples are available:

• inside the doc/Examples/ folder
• inside the specs/FluidXml.php file (as test cases)

All them cover from the simplest case to the most complex scenario.

Take a look at the APIs to discover all the available manipulation operations,
and go to the Wiki Page for more reading.

Donation

If you think this code is awesome or if you want to demonstrate
your immense gratitude ♥, buy me a coffe.

Roadmap

• Extending the documentation
• Expanding the APIs

Author

Daniele Orlando <[email protected]>

License

FluidXML is licensed under the BSD 2-Clause License.

See doc/LICENSE.txt for the details.