lib/xmloutputter.php

   1 <?php
   2 /**
   3  * StatusNet, the distributed open-source microblogging tool
   4  *
   5  * Low-level generator for XML
   6  *
   7  * PHP version 5
   8  *
   9  * LICENCE: This program is free software: you can redistribute it and/or modify
  10  * it under the terms of the GNU Affero General Public License as published by
  11  * the Free Software Foundation, either version 3 of the License, or
  12  * (at your option) any later version.
  13  *
  14  * This program is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17  * GNU Affero General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Affero General Public License
  20  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  21  *
  22  * @category  Output
  23  * @package   StatusNet
  24  * @author    Evan Prodromou <evan@status.net>
  25  * @author    Sarven Capadisli <csarven@status.net>
  26  * @copyright 2008 StatusNet, Inc.
  27  * @license   http://www.fsf.org/licensing/licenses/agpl-3.0.html GNU Affero General Public License version 3.0
  28  * @link      http://status.net/
  29  */
  30
  31 if (!defined('STATUSNET') && !defined('LACONICA')) {
  32     exit(1);
  33 }
  34
  35 /**
  36  * Low-level generator for XML
  37  *
  38  * This is a thin wrapper around PHP's XMLWriter. The main
  39  * advantage is the element() method, which simplifies outputting
  40  * an element.
  41  *
  42  * @category Output
  43  * @package  StatusNet
  44  * @author   Evan Prodromou <evan@status.net>
  45  * @author   Sarven Capadisli <csarven@status.net>
  46  * @license  http://www.fsf.org/licensing/licenses/agpl-3.0.html GNU Affero General Public License version 3.0
  47  * @link     http://status.net/
  48  * @see      Action
  49  * @see      HTMLOutputter
  50  */
  51
  52 class XMLOutputter
  53 {
  54     /**
  55      * Wrapped XMLWriter object, which does most of the heavy lifting
  56      * for output.
  57      */
  58
  59     var $xw = null;
  60
  61     /**
  62      * Constructor
  63      *
  64      * Initializes the wrapped XMLWriter.
  65      *
  66      * @param string  $output URL for outputting, defaults to stdout
  67      * @param boolean $indent Whether to indent output, default true
  68      */
  69
  70     function __construct($output='php://output', $indent=null)
  71     {
  72         $this->xw = new XMLWriter();
  73         $this->xw->openURI($output);
  74         if(is_null($indent)) {
  75             $indent = common_config('site', 'indent');
  76         }
  77         $this->xw->setIndent($indent);
  78     }
  79
  80     /**
  81      * Start a new XML document
  82      *
  83      * @param string $doc    document element
  84      * @param string $public public identifier
  85      * @param string $system system identifier
  86      *
  87      * @return void
  88      */
  89
  90     function startXML($doc=null, $public=null, $system=null)
  91     {
  92         $this->xw->startDocument('1.0', 'UTF-8');
  93         if ($doc) {
  94             $this->xw->writeDTD($doc, $public, $system);
  95         }
  96     }
  97
  98     /**
  99      * finish an XML document
 100      *
 101      * It's probably a bad idea to continue to use this object
 102      * after calling endXML().
 103      *
 104      * @return void
 105      */
 106
 107     function endXML()
 108     {
 109         $this->xw->endDocument();
 110         $this->xw->flush();
 111     }
 112
 113     /**
 114      * output an XML element
 115      *
 116      * Utility for outputting an XML element. A convenient wrapper
 117      * for a bunch of longer XMLWriter calls. This is best for
 118      * when an element doesn't have any sub-elements; if that's the
 119      * case, use elementStart() and elementEnd() instead.
 120      *
 121      * The $content element will be escaped for XML. If you need
 122      * raw output, use elementStart() and elementEnd() with a call
 123      * to raw() in the middle.
 124      *
 125      * If $attrs is a string instead of an array, it will be treated
 126      * as the class attribute of the element.
 127      *
 128      * @param string $tag     Element type or tagname
 129      * @param array  $attrs   Array of element attributes, as
 130      *                        key-value pairs
 131      * @param string $content string content of the element
 132      *
 133      * @return void
 134      */
 135
 136     function element($tag, $attrs=null, $content=null)
 137     {
 138         $this->elementStart($tag, $attrs);
 139         if (!is_null($content)) {
 140             $this->xw->text($content);
 141         }
 142         $this->elementEnd($tag);
 143     }
 144
 145     function elementNS(array $ns, $tag, $attrs=null, $content=null)
 146     {
 147         $this->elementStartNS($ns, $tag, $attrs);
 148         if (!is_null($content)) {
 149             $this->xw->text($content);
 150         }
 151         $this->elementEnd($tag);
 152     }
 153
 154     /**
 155      * output a start tag for an element
 156      *
 157      * Mostly used for when an element has content that's
 158      * not a simple string.
 159      *
 160      * If $attrs is a string instead of an array, it will be treated
 161      * as the class attribute of the element.
 162      *
 163      * @param string $tag   Element type or tagname
 164      * @param array  $attrs Array of element attributes
 165      *
 166      * @return void
 167      */
 168
 169     function elementStart($tag, $attrs=null)
 170     {
 171         $this->xw->startElement($tag);
 172         if (is_array($attrs)) {
 173             foreach ($attrs as $name => $value) {
 174                 $this->xw->writeAttribute($name, $value);
 175             }
 176         } else if (is_string($attrs)) {
 177             $this->xw->writeAttribute('class', $attrs);
 178         }
 179     }
 180
 181     function elementStartNS(array $ns, $tag, $attrs=null)
 182     {
 183         reset($ns); // array pointer to 0
 184         $uri = key($ns);
 185         $this->xw->startElementNS($ns[$uri], $tag, $uri);
 186         if (is_array($attrs)) {
 187             foreach ($attrs as $name => $value) {
 188                 $this->xw->writeAttribute($name, $value);
 189             }
 190         } else if (is_string($attrs)) {
 191             $this->xw->writeAttribute('class', $attrs);
 192         }
 193     }
 194
 195     /**
 196      * output an end tag for an element
 197      *
 198      * Used in conjunction with elementStart(). $tag param
 199      * should match the elementStart() param.
 200      *
 201      * For HTML 4 compatibility, this method will force
 202      * a full end element (</tag>) even if the element is
 203      * empty, except for a handful of exception tagnames.
 204      * This is a hack.
 205      *
 206      * @param string $tag Element type or tagname.
 207      *
 208      * @return void
 209      */
 210
 211     function elementEnd($tag)
 212     {
 213         static $empty_tag = array('base', 'meta', 'link', 'hr',
 214                                   'br', 'param', 'img', 'area',
 215                                   'input', 'col', 'source');
 216         // XXX: check namespace
 217         if (in_array($tag, $empty_tag)) {
 218             $this->xw->endElement();
 219         } else {
 220             $this->xw->fullEndElement();
 221         }
 222     }
 223
 224     /**
 225      * output plain text
 226      *
 227      * Text will be escaped. If you need it not to be,
 228      * use raw() instead.
 229      *
 230      * @param string $txt Text to output.
 231      *
 232      * @return void
 233      */
 234
 235     function text($txt)
 236     {
 237         $this->xw->text($txt);
 238     }
 239
 240     /**
 241      * output raw xml
 242      *
 243      * This will spit out its argument verbatim -- no escaping is
 244      * done.
 245      *
 246      * @param string $xml XML to output.
 247      *
 248      * @return void
 249      */
 250
 251     function raw($xml)
 252     {
 253         $this->xw->writeRaw($xml);
 254     }
 255
 256     /**
 257      * output a comment
 258      *
 259      * @param string $txt text of the comment
 260      *
 261      * @return void
 262      */
 263
 264     function comment($txt)
 265     {
 266         $this->xw->writeComment($txt);
 267     }
 268
 269     /**
 270      * Flush output buffers
 271      *
 272      * @return void
 273      */
 274
 275     function flush()
 276     {
 277         $this->xw->flush();
 278     }
 279 }