Proposal informations

Zend_Xml (Full Fluent) is the complete refactoring of Zend_Xml that should be deprecated in favor of this new component.

Zend Framework: Zend_Xml Component Proposal

Proposed Component Name	Zend_Xml
Developer Notes	http://framework.zend.com/wiki/display/ZFDEV/Zend_Xml
Proposers	My E-mail Address
Revision	0.1 - 30 November 2007: Initial release. (wiki revision: 15)

Zend_Xml (Full Fluent) is the complete refactoring of Zend_Xml.
Zend_Xml is a component that allow you to work on a Xml document in a fluent, rapid and powerful way.
This is possible combining dom, xpath, arrays and the fluent pattern.
Oh, I was forgetting. Do you need namespace? Well, Zend_Xml is full and easy namespace compliant.

2. References

3. Component Requirements, Constraints, and Acceptance Criteria

Zend_Xml is an high level library for XML document creation and manipulation.

This component will not supports conversion in other markup languages or document types.
This component should supports all PHP5 DOM methods and properties.
This component will implements some SimpleXML interaction facilities.

4. Dependencies on Other Framework Components

Zend_Exception

5. Theory of Operation

Instantiate Zend_Xml with the root name(s) of the xml document and, if required, the external stylesheet.
Now, you are ready to build your XML document quickly and with total control on every operation.

6. Milestones / Tasks

Zend_Xml maybe improved to support XQuery, SimpleXML and xml data conversion into a native php data type to integrate it in a more complex component for data manipulation and conversion (Zend_Data ?).

Milestone 1: [DONE] Base operations support
Milestone 2: Full support for PHP5 DOM methods
Milestone 3: Support for pre-existent DOMDocument and SimpleXML objects
Milestone 4: Performance tuning
Milestone 5: SimpleXML methods and properties exposition

7. Class Index

Zend_Xml - xml document creation facade
Zend_Xml_Exception - exception handler
Zend_Xml_Dom_Abstract - shared and abstract methods for dom manipulation
Zend_Xml_Dom_Abstract_Exception - exception handler
Zend_Xml_Document - domdocument facade
Zend_Xml_Document_Exception - exception handler
Zend_Xml_Exception - exception handler
Zend_Xml_Nodes - implementation of the composite pattern
Zend_Xml_Nodes_Exception - exception handler

8. Use Cases

UC-01

<?php

require_once 'Zend/Xml.php' ;

/* Initialization */

$xml = new Zend_Xml(
    'root', /* @1 */
    'http://servo-project.sourceforge.net/stylesheet.xsl', /* @2 */
    array( /* @3 */
        'nsUri'=>'org.servo-project', // URI
        'nsId'=>'servo', // Identifier (ex ns for ns:root)
        'nsMode'=>0 // Mode (0 for implicit, 1 for explicit)
    )
) ;

/* @1 */ // root of the xml doc. ex. array('root1','root2','root3').
/* @2 */ // Stylesheet uri.
/* @3 */ // Namespace config.

UC-02

/* Very simple usage */

$ns = $xml->getNamespacePrefix() ; /* @0 */

$xml->xpaths("/{$ns}root")
        ->appendChilds('rootSub1') /* @1 */
        ->appendChilds(array( /* @2 */
            'rootSub2' ,
            'rootSub3' => 'withText'
        ))
        ->setAttributes(array( /* @3 */
            'class' => 'high' ,
            'id' => '{uniqueId}'
        )) ; 

/* @0 */ // In this way, identical to $xml->ns('root'), we can work safely with namespace.
/* @1 */ // Appends <rootSub1/> to '/root'.
/* @2 */ // Appends <rootSub2/> and '<rootSub3>withText</rootSub3> to '/root'.
/* @3 */ // Sets <root> as <root class="high" id="{uniqueId}">.

UC-03

/* Usage of 'switchContext' setted to 'true' */

$xml->xpaths("/{$ns}root")
        ->appendChilds(array(
            'rootSub4',
            'rootSub5'
        ),true) /* @1 */
            ->appendChilds('rootSub4N5Sub1') /* @2 */
            ->setAttributes(array(
                'class' => 'commonAttribute'
            )) ;

/* @1 */ // The second parameter, setted on true, enable the switch of context
         // from the precedent (xpaths(...)) to the new (appendChilds() childs)
         // in this case '/root/rootSub4' and '/root/rootSub5'.
/* @2 */ // Appends <rootSub4N5Sub1/> to '/root/rootSub4' and to '/root/rootSub5'.

UC-04

/* Concatenation of xpath queries and switch context options */

$xml->xpaths("/{$ns}root/{$ns}rootSub2")
        ->appendChilds('rootSub2Sub1',true)
            ->createTexts('shortText') ;

$xml->xpaths("/{$ns}root")
        ->xpaths("{$ns}rootSub2")
            ->appendChilds('rootSub2Sub2',true)
                ->appendChilds('rootSub2Sub2Sub1') ;

UC-05

/* Useful usage */

$xml->xpaths("/{$ns}root")
        ->xpaths(array(
            "{$ns}rootSub1" ,
            "{$ns}rootSub2"
        ))
        ->appendChilds('rootSub1N2Sub1') ;

UC-06

/* Complex namespaces usage and extended appendChilds options */

/* Zend_Xml::appendChilds($childs, $switchContext = false, array $namespace =  array(), array $commonAttributes = array(), $commonText = null) */

$root2 =& $xml->appendChilds(
    'root2', true, /* @0 */
    array( /* @1 */
        'nsId' => 'xx' ,
        'nsUri' => '/any/uri' ,
        'nsMode' => 1
    ) ,
    array( /* @2 */
        'class' => 'secondInstance' ,
        'id' => 'root2'
    )
) ; // Different uri, id and mode. Implicit vs Explicit

/* @0 */ // The true option switches the context and returns it to $root2.
/* @1 */ // Appends a root node with a different namespace
         // and with explicit namespace (xx:root2).
/* @2 */ // The fourth parameter of Zend_Xml::appendChilds() must be an array
         // and represents the attributes to apply to the appended childs.
         // It's similar to $xml->appendChilds('root',true)->setAttributes(...)
         // but without the context switch.

$root2->appendChilds( /* @3 */
    array(
        'root2Sub1' ,
        'root2Sub2'
    ), false, array(), array(),
    'commonTextForBothChilds' /* @4 */
) ;

/* @3 */ // $root2 is the node returned by $root2 =& $xml->appendChilds(..)
         // and can be manipulated in the same way.
         // Every changes applied to $root2 are applied to $xml too.
/* @4 */ // The fifth parameter of Zend_Xml::appendChilds() is very similar to the fourth /* @2 */,
         // except that it represents the text to apply to the appended childs
         // and can be either an array or a string

UC-07

echo $xml->saveXML() ;

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type='text/xsl' encoding='UTF-8' indent='yes' href='http://servo-project.sourceforge.net/stylesheet.xsl'?>
<root xmlns="org.servo-project" class="high" id="{uniqueId}">
  <rootSub1>
    <rootSub1N2Sub1/>
  </rootSub1>
  <rootSub2>
    <rootSub2Sub1>shortText</rootSub2Sub1>
    <rootSub2Sub2>
      <rootSub2Sub2Sub1/>
    </rootSub2Sub2>
    <rootSub1N2Sub1/>
  </rootSub2>
  <rootSub3>withText</rootSub3>
  <rootSub4 class="commonAttribute">
    <rootSub4N5Sub1/>
  </rootSub4>
  <rootSub5 class="commonAttribute">
    <rootSub4N5Sub1/>
  </rootSub5>
</root>
<xx:root2 xmlns:xx="/any/uri" class="secondInstance" id="root2">
  <xx:root2Sub1>commonTextForBothChilds</xx:root2Sub1>
  <xx:root2Sub2>commonTextForBothChilds</xx:root2Sub2>
</xx:root2>

9. Class Skeletons

The complete component is coded and ready
and will be published only under request of the Zend Framework team
or after a general judgment.

Page Operations

Browse Space

Zend_Xml (Full Fluent) - Daniele Orlando

Labels