Introduces ->each(), ->setCdata() and ->cdata().

* [+] ->each() is part of the family. * [+] ->setCdata() is part of the family. * [+] ->cdata() is part of the family. * [@] internal refactoring.
servo-php · Jan 5, 2016 · 46faa37 · 46faa37
1 parent b13329b
commit 46faa37
Show file tree

Hide file tree

Showing 10 changed files with 638 additions and 296 deletions.
diff --git a/documents/APIs.md b/documents/APIs.md
@@ -40,21 +40,21 @@ __construct($root?, array $options?);
 ->append($sibling, ...$optionals);
 ->insertSiblingAfter($sibling, ...$optionals);
 
-->appendXml($xml);
-
-->appendText($text);
-
-->appendCdata($text);
+->setAttribute(...$arguments);
 // alias:
-->cdata($text);
+->attr(...$arguments);
 
 ->setText($text);
 // alias:
 ->text($text);
 
-->setAttribute(...$arguments);
+->appendText($text);
+
+->setCdata($text);
 // alias:
-->attr(...$arguments);
+->cdata($text);
+
+->appendCdata($text);
 
 ->remove(...$xpath);
 

diff --git a/documents/Changelog.txt b/documents/Changelog.txt
@@ -1,24 +1,37 @@
+[+]: new   [~]: changed   [-]: removed   [#]: fixed   [@]: internal
+
+
+1.10: (2016-01-06)
+introduces the '->each()' method and the '->setCdata()'/'->cdata()' twins methods
+together with an internal refactoring.
+
+    * [+] ->each() is part of the family.
+    * [+] ->setCdata() is part of the family.
+    * [+] ->cdata() is part of the family.
+
+
 1.9:
-wraps the FluidXML classes and functions under the FluidXml namespace.
+wraps classes and functions under the FluidXml namespace.
 
 
-1.8: (2016-01-02)
+1.8:
 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().
+    * [~] ->appendChild() has the super powers of ->appendXml().
+    * [~] ->appendSibling() has the super powers of ->appendXml().
+    * [~] ->prependSibling() has the super powers of ->appendXml().
+
+    * [-] ->appendXml() has been removed superseded by ->appendChild().
 
 
 1.7:
 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.
+    * [~] ::load() adds support for DOMNode, DOMNodeList and FluidXml.
+    * [~] ->xml() can export any node with its descendants.
+    * [~] ->xml() accepts a boolean flag to remove the XML declaration headers.
+    * [~] ->appendXml() is smarter than ever, supporting
+      DOMDocument, DOMNode, DOMNodeList, SimpleXMLElement, FluidXml and XML strings.
 
 
 1.6.2:
@@ -32,33 +45,33 @@ fixes a wrong path of the Composer autoloader.
 1.6:
 lowers the minimum PHP version to PHP 5.6 (it was PHP 7).
 
-* [internal] cleanup.
+    * [@] cleanup.
 
 
 1.5:
-introduces supports for importing XML documents from
+introduces support 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.
+    * [+] fluidify() is part of the family.
+    * [+] FluidXml::new() is part of the family.
+    * [+] FluidXml::load() is part of the family.
 
 
 1.4:
-* [changed] ->remove() can remove the results of a query and accepts multiple XPath strings.
+    * [~] ->remove() can remove the results of a query and accepts multiple XPath strings.
 
 
 1.3:
-* [changed] FluidXml::__construct accepts the 'root' option as first argument.
+    * [~] FluidXml::__construct accepts the 'root' option as first argument.
 
 
 1.2:
-* [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.
+    * [~] ->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.
 
 
 1.1.1:

diff --git a/documents/Examples.php b/documents/Examples.php
@@ -99,9 +99,7 @@
              [ 'pasta' => 'Matriciana' ] ]);
 
 // A bunch of egg's all with the same price.
-$food->add([ ['egg'],
-             ['egg'],
-             ['egg'] ], ['price' => '0.25']);
+$food->add([ ['egg'], ['egg'], ['egg'] ], ['price' => '0.25']);
 
 // Complex array structures are supported too.
 $food->add([ 'fridge' => [
@@ -214,20 +212,18 @@
 echo "————————————————————————————————————————————————————————————————————————————————\n";
 
 $book->query('//chapter')
-     ->attr('lang', 'en')
+        ->attr('lang', 'en')
      ->query('..')
-     ->attr('lang', 'en')
+        ->attr('lang', 'en')
      ->query('../title')
-     ->attr('lang', 'en');
+        ->attr('lang', 'en');
 
 /*
 * The previous code presents a repetition: all 'setAttribute' calls are identical.
 * It can be refactored taking advantage of an advanced feature of 'query'.
 */
-$book->query('//chapter',
-             '//chapters',
-             '/book/title')
-     ->attr('lang', 'en');
+$book->query('//chapter', '//chapters', '/book/title')
+        ->attr('lang', 'en');
 
 
 

diff --git a/documents/Getting-Started.md b/documents/Getting-Started.md
@@ -411,16 +411,25 @@ what is already convenient to use.
 
 To access the node content after a query we can use the DOMNode own methods.
 
+```php
+$book->query('//chapter')
+     ->each(function($fluid, $domnode, $index) {
+            $fluid->attr('uuid', random_uuid());
+
+            echo $domnode->nodeValue;
+     });
+```
+
 Accessing the query result as array or iterating it returns the DOMNode unwrapped.
 
 ```php
 $chapters = $book->query('//chapter');
 
-$l = $chapters->length();
+$last = $chapters->length() - 1;
 
-// DOMNode access.
+// Raw DOMNode access.
 $chapters[0]->setAttribute('first', '');
-$chapters[$l - 1]->setAttribute('last', '');
+$chapters[$last]->setAttribute('last', '');
 
 foreach ($chapters as $i => $chapter) {
         // $chapter is an instance of DOMNode.
@@ -439,9 +448,7 @@ foreach ($chapters as $i => $chapter) {
 ```
 
 > **Pro Tip**:<br/>
-> The `setAttribute()` method used in the previous example is the `DOMNode::setAttribute()`,<br/>
-> not the `FluidXml::setAttribute()/attr()`.<br/>
-> Many other DOMNode methods and properties are available like:
+> Many DOMNode methods and properties are available like:
 > - `hasAttribute()`
 > - `getAttribute()`
 > - `nodeValue`

diff --git a/documents/ReadMe.md b/documents/ReadMe.md
@@ -15,6 +15,34 @@
 
 [![Build Status][travis-badge]][travis]
 
+## Changelog
+- **1.10**: _(2016-01-06)_
+    * [+] **->each()**, **->setCdata()** and **->cdata()** are part of the family.
+
+
+- **1.9**:
+ _wraps classes and functions under the **FluidXml namespace**._
+
+
+- **1.8**:
+ _gives super powers to the manipulation APIs._
+
+    * [~] **->appendChild()**, **->appendSibling()** and **->prependSibling()**<br/>
+      have the super powers of **->appendXml()**.
+    * [-] **->appendXml()** has been removed superseded by **->appendChild()**.
+
+
+- **1.7**:
+ improves dealing with other XML object instances.
+
+    * [~] **::load()** adds support for **DOMNode**, **DOMNodeList** and **FluidXml**.
+    * [~] **->xml()** can export any node with its descendants.
+    * [~] **->xml()** accepts a boolean flag to remove the XML declaration headers.
+    * [~] **->appendXml()** is smarter than ever, supporting<br/>
+      **DOMDocument**, **DOMNode**, **DOMNodeList**, **SimpleXMLElement**, **FluidXml** and **XML strings**.
+
+- **...**
+
 # FluidXML
 <img src="https://bytebucket.org/daniele_orlando/hosting/raw/master/Servo_logo.png" height="64px" alt="Servo-PHP Logo"/>
 
@@ -69,26 +97,6 @@ echo $book->xml();
 </doc>
 ```
 
-Creating **structured documents** is so easy that you'll not believe.
-
-```php
-$food = fluidxml();
-
-// Batch insertion of nodes.
-$food->add([ 'cake'  => 'Tiramisu',
-             'pizza' => 'Margherita' ]);
-
-// A bunch of egg's all with the same attribute.
-$food->add([ ['egg'],
-             ['egg'],
-             ['egg'] ], ['price' => '0.25']);
-
-// Deep tree structures are supported too.
-$food->add([ 'fridge' => [ 'omelette' => 'with potato',
-                           'soupe'    => 'with mashrooms' ],
-             'freezer' => [ 'meat' => 'beef' ] ]);
-```
-
 **XPath** is king.
 
 ```php
@@ -99,34 +107,57 @@ $book->query('//chapter')
         ->attr('country', 'us');
 ```
 
+**XML Namespaces** are fully covered.
+
+```php
+$book->namespace('xhtml', 'http://www.w3.org/1999/xhtml')
+     ->namespace('svg',   'http://www.w3.org/2000/svg')
+     ->add('xhtml:h1')
+     ->add('svg:shape')
+     ->query('//xhtml:h1');
+```
+
 And sometimes **string templates** are the fastest way.
 
 ```php
-$book->add('cover', true)
-        ->add(<<<XML
-            <h1>The Theory Of Everything</h1>
-            <img src="http://goo.gl/kO3Iov"/>
+$book->add(<<<XML
+    <cover>
+        <h1>The Theory Of Everything</h1>
+        <img src="http://goo.gl/kO3Iov"/>
+    </cover>
 XML
 );
 ```
 
-**XML Namespaces** are fully covered too.
+Creating **structured documents** is so easy that you'll not believe.
 
 ```php
-$book->namespace('xhtml', 'http://www.w3.org/1999/xhtml')
-     ->namespace('svg',   'http://www.w3.org/2000/svg')
-     ->appendChild('xhtml:h1')
-     ->appendChild('svg:shape')
-     ->query('//xhtml:h1');
+$food = fluidxml();
+
+// Batch insertion of nodes.
+$food->add([ 'cake'  => 'Tiramisu',
+             'pizza' => 'Margherita' ]);
+
+// A bunch of egg's all with the same attribute.
+$food->add([ ['egg'], ['egg'], ['egg'] ], ['price' => '0.25']);
+
+// Deep tree structures are supported too.
+$food->add([ 'fridge' => [ 'omelette' => 'with potato',
+                           'soupe'    => 'with mashrooms' ],
+             'freezer' => [ 'meat' => 'beef' ] ]);
 ```
 
-Existing **DOMDocument** and **SimpleXML** documents are not a problem, just import them.
+
+Interoperability with existing **DOMDocument** and **SimpleXML** is simply magic.<br/>
+Import them or inject them in any point of the FluidXML document just like that.
 
 ```php
-$fluidxml = fluidify($domdocument);
+fluidify($domdocument)
+    ->query('/html/body')
+         ->add($simplexml);
 
-$fluidxml->query('/html/body')
-         ->add($simplexmlelement);
+// Yes, we merged a DOMDocument with a SimpleXMLElement
+// and everything is still fluid.
 ```
 
 Don't be shy and tell it: **« IT'S AWESOME! »** ^\_^
@@ -169,9 +200,12 @@ require_once 'FluidXml.php';
 require_once 'vendor/autoload.php';
 ```
 
+`use` classes and functions as you need.
 ```php
 use \FluidXml\FluidXml;
 use \FluidXml\FluidNamespace;
+```
+```php
 use function \FluidXml\fluidxml;
 use function \FluidXml\fluidns;
 use function \FluidXml\fluidify;
@@ -204,8 +238,7 @@ your immense gratitude **♡**, donate _1cent_.
 
 ## Roadmap
 * [x] PHP 5.6 backport
-* [ ] Expanding the APIs
-* [ ] Extending the documentation
+* [ ] Expanding the APIs and the documentation
 
 <a href='https://pledgie.com/campaigns/30607'>
     <img alt='Click here to lend your support to: FluidXML and make a donation at pledgie.com !' src='https://pledgie.com/campaigns/30607.png?skin_name=chrome' border='0' >