readme

来自「视频监控网络部分的协议ddns,的模块的实现代码,请大家大胆指正.」· 代码 · 共 497 行 · 第 1/2 页

XML Transformer Tutorial
By Kristian K鰄ntopp and Sebastian Bergmann.


0. This file

This file is a supplementary document for the online documentation of the
XML_Transformer PEAR package. It is not a comprehensive manual of methods and
parameters, that's what the PEAR online documentation is good for.

Instead, this document acts as a guide and tutorial to XML_Transformer and
friends. It aims at explaining the architecture of XML_Transformer and the
choices that governed its design. Also, it should contain a number of simple
applications of XML_Transformer to illustrate its typical use.


1. What is it good for?

The XML Transformer is a system of PEAR classes that can be used to transform
XML files into other XML files. The transformation is specified using PHP
functions.

We created XML Transformer because we were annoyed with the syntax and
capabilities of XSLT. XSLT is a very verbose language that needs many lines of
text to express even the simplest of algorithms. Also, XSLT is a functional
language offering all the drawbacks of languages of this class (variables are
actually a kind of constant, recursion is needed to express many loops etc)
without the advantages that come with such languages (closures, functions as
first-order datatypes etc). Finally, XSLT is badly integrated into almost all
development environments, offering little in the way of character manipulation,
and nothing in the way to database access, image manipulation, flat file output
control and so on.

XML Transformer can do many things that linear (non-reordering) XSLT can. It can
do some things XSLT can't (such as recursively reparsing its own output), and it
can utilize all PHP built-in functions and classes to do this. Transformations
are specified using the syntax of PHP with which you're already familiar, and
there is a simplified syntax to specify simple replacement transformations that
does not even need PHP at all.

Since XML Transformer uses a SAX parser to do its work, it can't do anything a
SAX parser can't do. That is, it cannot do reordering transformations in a
single pass. You won't be able to generate indices, tables of contents and other
summary operations in a single pass. If you run into such problems, think LaTeX
and use the solutions LaTeX uses for this problems as well - we have recently
added support for multipassing, so that implementing such a mechanism shouldn't
be too difficult. Also, we are providing the Docbook Namespace Handler as an
example for such mechanisms.

Finally, we are considering an implementation of XML Transformer using a DOM
parser and XPath queries to enable single pass reordering operations in PHP as
well.


2. What are all these files and classes?

2.1 XML_Transformer

The heart of the XML Transformer is defined in XML/Transformer.php. All the work
is being done within the transform() method, which takes an XML string,
transforms it and returns the transformed result.

As transform() uses PHP's XML extension internally, the XML string must in
theory be a well-formed XML fragment in order for the transformation to work.
That is, it should be starting with a tag and ending with the same tag. For
your convenience we internally wrap everything that is being transformed
into a <_>...</_> container in order to satisfy this requirement.

To set up a transformation, you need to create an instance of the class
XML_Transformer and then add options and transformations to it.

  $t = new XML_Transformer();
  $t->setDebug(true);
  $t->overloadNamespace('php', new XML_Transformer_PHP);

Options are added using the set-type methods setDebug(),
setRecursiveOperation(), and setCaseFolding(). Transformations are added using
overloadNamespace(). All of these options and then some can be set as parameters
to the constructor. You'd be using an array that is being passed to the c'tor
for this.

  $t = new XML_Transformer(
    'debug'                => true,
    'overloadedNamespaces' => array(
      'php',
      new XML_Transformer_PHP
    )
  );


2.2 XML_Transformer_CallbackRegistry and XML_Util

Internally, XML Transformer uses two auxiliary classes to do its work. One of
them is the XML_Transformer_CallbackRegistry, which does all the bookkeeping for
XML_Transformer, tracking which methods are to call for which namespace and so
on. XML_Transformer_CallbackRegistry is a Singleton, and the instance is
maintained automatically by XML_Transformer. You never use it directly.

The other used to be XML_Transformer_Util, which was later merged with other
methods and is now XML_Util, a PEAR package in its own right. Please refer
to the XML_Util documentation for more information on this class.

2.3 XML_Transformer_Namespace

Using XML_Transformer, all transformations are specified for namespaces. You may
specifiy transformations for the empty namespace, that is, you may transform
simple tags such as <body/> or <p/>. The name of the empty namespace is '' or
'&MAIN'.

To make the definition of namespaces easy, we supply a class
XML_Transformer_Namespace from which you can inherit (Note that
XML_Transformer_namespace is only one possible implementation for a namespace.
You are free to choose a different implementation schema anytime, for example if
the direct mapping of classes to namespaces is not applicable for your
deployment scenario). The class is suitable for all non-nesting tags and the
implementation schemata shown here are suitable for non-nesting tags such as
<img/> or <h1/>, but you'd need something more sophisticated to implement a
nesting structure such as <table/> which can contain itself.

In order to define a tag called <tag />, you create a class and implement
methods called start_tag($attributes) and end_tag($cdata). These methods must
return the result of the transformation as strings, and it must be a valid XML
fragment. By our coding conventions, start_tag() never returns anything but
only records the tags attributes. All code is being generated in end_tag().
That way we avoid problems with invalid XML in recursive parsing.

class MyNamespace extends XML_Transformer_Namespace {
  var $tag_attributes = array();

  function start_tag($att) {
    $this->tag_attributes = $att;

    return '';
  }

  function end_tag($cdata) {
    if (isset($this->tag_attributes['name'])) {
      $name = $this->tag_attributes['name'];
      $thline = "<tr><th>$name</th></tr>";
    } else {
      $thline = '';
    }

    return "<table>$thline<tr><td>$cdata</td></tr></table>";
  }
}

This minimal sample implements a container tag called <...:tag name="headline"
/>, which places its content in a table, and additionally supplied a table
headline in a <th/> cell if an attribute "name" is present.

The example is pretty much useless, but illustrates attribute capture, access to
the tags cdata content, and returning of results. Also, it illustrates how easy
namespaces are created by inheriting from XML_Transformer_Namespace.

To activate the namespace and assign it a namespace prefix, you'd use
overloadNamespace():

  $t = new XML_Transformer(...);
  $t->overloadNamespace('my', new MyNamespace());

This tag can now be used as "<my:tag name='heading'>content</my:tag>".

The XML_Transformer_Namespace class has a few instance variables which may come
in handy in some cases. One of them is _transformer, which is indeed a reference
to the owning transformer.

Another is an array _prefix, which is an enumeration of namespace prefixes of
this namespace class. In our example above, that array would have just one
element, $this->_prefix[0], and it would contain the string 'my'. As you might
have guessed from the fact that _prefix is an array, we consider it legal to
register a single namespace class under multiple prefixes, if you can manage to
keep your references straight and not inadvertantly copy your instance. We have
not bothered to implement namespace scopes, though, as we should have were we in
the business of implementing the complete XML specification.

The XML_Transformer has a handy feature where Namespaces are autoloaded and
registered under their default namespace names, if they define one. In order for
autoloading to work, define an instance variable defaultNamespacePrefix as a
string. This string is the prefix under which the namespace will register itself
when autoloading.

Finally, a namespace may indicate that it requires two passes in order to
generate indicies or other data collections. If this is needed, the namespace
should set secondPassRequired to true (default: false).


2.3.1 Using autoloading

We have supplied a number of subclasses to XML_Transformer_Namespace. These
reside in a directory "./Transformer/Namespace" relative to the directory of the
actual Transformer.php file itself, and can be autoloaded.

In order to autoload namespaces, supply the flag "autoload" to your transformer
constructor. You may set the flag simply to "true" in order to load all
Namespaces, or you may pass a single string or an array of strings indicating
the namespaces you want to load.

Namespaces are connected to their default prefixes, and in order for this to
work they must define such prefixes in defaultNamespacePrefix.

Example:

 $t = new XML_Transformer(
            array(
              'autoload' => true
            )
          );
 Load all Namespaces

 $t = new XML_Transformer(
            array(
              'autoload' => 'PHP'
            )
          );
 Load XML/Transformer/Namespace/PHP.php.

 $t = new XML_Transformer(
            array(
              'autoload' => array('PHP', 'Image', 'Anchor')
            )
          );
 Load the indicated namespaces.

Limitations of autoloading:

- currently, there is no pathname support. Only classes in
  "./Transformer/Namespace" can be autoloaded. Your project directories are
  not searched.

- currently, there is no separate method to trigger autoload.
  You must specify autoloading as a flag to the constructor.


2.4 supplied XML_Transformer Namespaces

All namespaces we supply are derived from XML_Transformer_Namespace and subject
to the limitations and interfaces of this baseclass.

If you are looking into our code in order to write your own namespaces, we
recommend you look into Anchor first. Anchor is your plain vanilla namespace
with no tricks and extra features.

The DocBook namespace is an example of a two-pass namespace. If you have an
application that needs to generate tables of contents, cross references or other
stuff that cannot be done without reordering, you should read DocBook as an
example.

The Image namespace generates PNG images, and uses a local cache for this. That