Merge branch 'dev-ns'

* dev-ns: Classes and functions are wrapped under the FluidXml namespace. Changelog refactoring and FluidXml stylesheet creation improvement.
servo-php · Jan 3, 2016 · b13329b · b13329b
2 parents 747d6df + 7f28d97
commit b13329b
Show file tree

Hide file tree

Showing 9 changed files with 259 additions and 141 deletions.
diff --git a/documents/Changelog.txt b/documents/Changelog.txt
@@ -1,56 +1,73 @@
-1.20
-* appendXml() has been merged with
-- appendChild()
-- prependSibling()
-- appendSibling()
-which accept a new input set of:
-- DOMDocument
-- DOMNode
-- DOMNodeList
-- SimpleXMLElement
-- FluidXml
+1.9:
+wraps the FluidXML classes and functions under the FluidXml namespace.
+
+
+1.8: (2016-01-02)
+gives super powers to the manipulation APIs.
+
+* [changed] ->appendChild() has the super powers of ->appendXml().
+* [changed] ->appendSibling() has the super powers of ->appendXml().
+* [changed] ->prependSibling() has the super powers of ->appendXml().
+* [removed] ->appendXml() has been removed superseded by ->appendChild().
+
 
 1.7:
-* appendXml() is smarter than ever, supporting
-- DOMDocument/DOMNode/DOMNodeList/SimpleXMLElement/FluidXml
+improves dealing with other XML object instances.
+
+* [changed] ::load() adds support for DOMNode, DOMNodeList and FluidXml.
+* [changed] ->xml() can export any node with its descendants.
+* [changed] ->xml() accepts a boolean flag to remove the XML declaration headers.
+* [changed] ->appendXml() is smarter than ever, supporting
+  DOMDocument, DOMNode, DOMNodeList, SimpleXMLElement and FluidXml and XML strings.
+
 
 1.6.2:
-* Fixes a wrong path of the Composer autoloader.
+fixes a wrong path of the Composer autoloader.
+
 
 1.6.1:
-* Fixes a wrong path of the Composer autoloader.
+fixes a wrong path of the Composer autoloader.
+
 
 1.6:
-* PHP 5.6 is the new minimum version (it was PHP 7).
-* Internal cleanup.
+lowers the minimum PHP version to PHP 5.6 (it was PHP 7).
+
+* [internal] cleanup.
+
 
 1.5:
-* Supports for importing XML documents from:
-- String
-- File
-- DOMDocument
-- SimpleXMLElement
-* FluidXml::new(), FluidXml::load() and fluidify() are part of the family.
+introduces supports for importing XML documents from
+DOMDocument, SimpleXMLElement, XML strings and XML files.
+
+* [new] fluidify() is part of the family.
+* [new] FluidXml::new() is part of the family.
+* [new] FluidXml::load() is part of the family.
+
 
 1.4:
-* ->remove() can remove the results of a query and accepts multiple XPath strings.
+* [changed] ->remove() can remove the results of a query and accepts multiple XPath strings.
+
 
 1.3:
-* FluidXml::__construct accepts the 'root' option as first argument
+* [changed] FluidXml::__construct accepts the 'root' option as first argument.
+
 
 1.2:
-* query() supports a variable number of XPaths
-* namespace() supports a variable number of FluidNamespace instances
-* namespace() supports a namespace id, uri and mode as arguments
-* namespaces() returns all registered namespaces
-* FluidNamespace instances are read-only
-* FluidNamespace::id/uri/mode() can't mutate the instance
+* [changed] ->query() supports a variable number of XPaths.
+* [changed] ->namespace() supports a variable number of FluidNamespace instances.
+* [changed] ->namespace() supports a namespace id, uri and mode as arguments.
+* [changed] ->namespaces() returns all registered namespaces.
+* [changed] FluidNamespace instances are read-only.
+* [changed] FluidNamespace::{id/uri/mode}() can't mutate the instance.
+
 
 1.1.1:
-* Fixes a NOTICE error
+fixes a notice error.
+
 
 1.1:
-* XML namespaces support added
+introduces the XML namespaces support.
+
 
-1.0:
-* Initial release
+1.0: (2015-11-19)
+is the initial release of the XML library with the Super Cow powers.
diff --git a/documents/Examples.php b/documents/Examples.php
@@ -8,6 +8,11 @@
 
 require_once 'FluidXml.php';
 
+use \FluidXml\FluidXml;
+use \FluidXml\FluidNamespace;
+use function \FluidXml\fluidxml;
+use function \FluidXml\fluidns;
+use function \FluidXml\fluidify;
 
 /*****************************
  * Creating An XML Document. *
@@ -125,10 +130,10 @@
 * Raw XML/XHTML strings che be injected at any point of the document too.
 */
 
-$book->appendChild('cover', true)
-     ->appendXml(<<<XML
-        <h1>The Theory Of Everything</h1>
-        <img src="http://goo.gl/kO3Iov"/>
+$book->add('cover', true)
+        ->add(<<<XML
+                <h1>The Theory Of Everything</h1>
+                <img src="http://goo.gl/kO3Iov"/>
 XML
 );
 
@@ -137,7 +142,7 @@
 * The document can be filled with a raw XML string.
 */
 $html = fluidxml(['root' => null]);
-$html->appendXml(<<<XML
+$html->add(<<<XML
 <html>
     <head>
         <meta/>
@@ -165,6 +170,8 @@
 
 $dom = new DOMDocument();
 $dom->loadXML($fluid->xml());
+$dom->formatOutput       = true;
+$dom->preserveWhiteSpace = false;
 // DOMDocument import.
 $fluid = fluidify($dom);
 echo $fluid->xml();
@@ -181,6 +188,15 @@
 // XML file import.
 // $fluid = fluidify('path/to/file.xml');
 
+$other = fluidify($fluid->xml());
+$fluid = fluidxml();
+
+$fluid->add($other)                                     // Imports a FluidXml instance.
+      ->add([ 'query'     => $fluid->query('//meta'),   // Imports a FluidXml query.
+              'dom'       => $dom,                      // Imports a DOMDocument.
+              'domnodes'  => $dom->childNodes,          // Imports a DOMNodeList.
+              'simplexml' => $simplexml ]);             // Imports a SimpleXMLElement.
+
 
 
 /******************

diff --git a/documents/Getting-Started.md b/documents/Getting-Started.md
@@ -26,6 +26,19 @@ require_once 'FluidXml.php';
 require_once 'vendor/autoload.php';
 ```
 
+Now `use` classes and functions you need.
+> Extended syntax
+> ```php
+> use \FluidXml\FluidXml;
+> use \FluidXml\FluidNamespace;
+> ```
+> Concise syntax
+> ```php
+> use function \FluidXml\fluidxml;
+> use function \FluidXml\fluidns;
+> use function \FluidXml\fluidify;
+> ```
+
 We can proceed to create our first XML document in the simplest way.
 
 > Extended syntax
@@ -118,7 +131,7 @@ echo $book->xml();
 </book>
 ```
 
-The `appendChild`/`add` method supports up to four arguments to achieve from the simplest<br/>
+The `appendChild()`/`add()` method supports up to four arguments to achieve from the simplest<br/>
 node insertion to nested trees creation.
 
 > _Public API_
@@ -338,18 +351,18 @@ Sometimes XML/XHTML comes from legacy templating systems or external sources.<br
 In those cases the raw XML string can be injected directly into the document.
 
 ```php
-$book->appendChild('cover', true)
-     ->appendXml(<<<XML
-        <h1>The Theory Of Everything</h1>
-        <img src="http://goo.gl/kO3Iov"/>
+$book->add('cover', true)
+        ->add(<<<XML
+            <h1>The Theory Of Everything</h1>
+            <img src="http://goo.gl/kO3Iov"/>
 XML
 );
 ```
 
 
 ## Executing XPath Queries
 
-The possibilty to execute XPath queries very easily is another feature of FluidXML.
+The possibility to execute XPath queries very easily is another feature of FluidXML.
 
 ```php
 $eggs   = $food->query('//egg');
@@ -364,20 +377,20 @@ flexibility.
 > Extended syntax
 > ```php
 > $book->query('//chapter')
->      ->setAttribute('lang', 'en')
+>           ->setAttribute('lang', 'en')
 >      ->query('..')
->      ->setAttribute('lang', 'en')
+>           ->setAttribute('lang', 'en')
 >      ->query('../title')
->      ->setAttribute('lang', 'en');
+>           ->setAttribute('lang', 'en');
 > ```
 > Concise syntax
 > ```php
 > $book->query('//chapter')
->      ->attr('lang', 'en')
+>           ->attr('lang', 'en')
 >      ->query('..')
->      ->attr('lang', 'en')
+>           ->attr('lang', 'en')
 >      ->query('../title')
->      ->attr('lang', 'en');
+>           ->attr('lang', 'en');
 > ```
 
 > **Pro Tip**:<br/>
@@ -463,14 +476,14 @@ At this point you are ready to use it.
 > $book->appendChild('xhtml:h1')
 >      ->appendChild([ 'xsl:template'  => [ 'xsl:variable' ] ])
 >      ->query('//xhtml:h1')
->      ->appendChild('svg:shape');
+>           ->appendChild('svg:shape');
 > ```
 > Concise syntax
 > ```php
 > $book->add('xhtml:h1')
 >      ->add([ 'xsl:template'  => [ 'xsl:variable' ] ])
 >      ->query('//xhtml:h1')
->      ->add('svg:shape');
+>           ->add('svg:shape');
 > ```
 
 ```php
@@ -554,7 +567,7 @@ $food->query('/doc')->remove('egg');    // Removes all the eggs.
 
 ## Importing Existing Documents
 
-FluidXML provides an easy way to import existing documents from a variety of sources.
+FluidXML provides an easy way to import existing XML documents from a variety of formats.
 
 The resulting object is a `FluidXml` instance filled with the XML of the imported document.
 
@@ -614,6 +627,34 @@ The resulting object is a `FluidXml` instance filled with the XML of the importe
 > $doc = fluidify($simplexml);          // $simplexml is an instance of SimpleXMLElement.
 > ```
 
+> **Pro Tip**:<br/>
+> `fluidify()`/`FluidXml::load()` methods support the following input documents:
+> - XML string
+> - XML file path
+> - `FluidXml` instance
+> - `DOMDocument`/`DOMNode`/`DOMNodeList` instance
+> - `SimpleXMLElement`
+
+Existing XML documents instances can be injected in any point of the FluidXML document.
+
+```php
+$doc = fluidxml();
+
+$doc->add($dom)                     // A DOMDocument/DOMNode/DOMNodeList instance.
+    ->add($simplexml)               // A SimpleXMLElement instance.
+    ->add($fluidxml)                // A FluidXml instance.
+    ->add($fluidxml->query('//p')); // A FluidXml query instance.
+```
+
+Crazy things are possible too and I will not stop you from doing them.
+
+```php
+$doc->add([ 'aNode',
+            'domDoc' => $dom,
+            'file'   => fluidify('path/to/file.xml'),
+            'simple' => $simplexml ]);
+```
+
 
 ## Where To Go Next
 

diff --git a/documents/ReadMe.md b/documents/ReadMe.md
@@ -18,8 +18,8 @@
 # FluidXML
 <img src="https://bytebucket.org/daniele_orlando/hosting/raw/master/Servo_logo.png" height="64px" alt="Servo-PHP Logo"/>
 
-FluidXML is a PHP library, under the Servo PHP framework umbrella ☂,<br/>
-designed to manipulate XML documents with a **concise** and **fluent** API.
+FluidXML is a PHP library designed to manipulate XML documents with a **concise**
+and **fluent** API.
 
 It leverages XPath and the fluent programming pattern to be **fun and effective**.
 
@@ -93,20 +93,19 @@ $food->add([ 'fridge' => [ 'omelette' => 'with potato',
 
 ```php
 $book->query('//chapter')
-     ->attr('status', 'read')
      ->query('..')
-     ->attr('lang', 'en')
+        ->attr('lang', 'en')
      ->query('../title')
-     ->attr('country', 'us');
+        ->attr('country', 'us');
 ```
 
 And sometimes **string templates** are the fastest way.
 
 ```php
-$book->appendChild('cover', true)
-     ->appendXml(<<<XML
-        <h1>The Theory Of Everything</h1>
-        <img src="http://goo.gl/kO3Iov"/>
+$book->add('cover', true)
+        ->add(<<<XML
+            <h1>The Theory Of Everything</h1>
+            <img src="http://goo.gl/kO3Iov"/>
 XML
 );
 ```
@@ -125,6 +124,9 @@ Existing **DOMDocument** and **SimpleXML** documents are not a problem, just imp
 
 ```php
 $fluidxml = fluidify($domdocument);
+
+$fluidxml->query('/html/body')
+         ->add($simplexmlelement);
 ```
 
 Don't be shy and tell it: **« IT'S AWESOME! »** ^\_^
@@ -167,6 +169,13 @@ require_once 'FluidXml.php';
 require_once 'vendor/autoload.php';
 ```
 
+```php
+use \FluidXml\FluidXml;
+use \FluidXml\FluidNamespace;
+use function \FluidXml\fluidxml;
+use function \FluidXml\fluidns;
+use function \FluidXml\fluidify;
+```
 See the [documentation](#documentation) to get started and become a [ninja][ninja].
 
 
@@ -194,9 +203,8 @@ your immense gratitude **♡**, donate _1cent_.
 
 
 ## Roadmap
-* [x] Porting the XML namespace implementation from the legacy FluidXML codebase
-* [ ] Expanding the APIs
 * [x] PHP 5.6 backport
+* [ ] Expanding the APIs
 * [ ] Extending the documentation
 
 <a href='https://pledgie.com/campaigns/30607'>