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, if null it defaults to stdout ('php://output')
  67      * @param boolean $indent Whether to indent output, default true
  68      */
  69
  70     function __construct($output=null, $indent=null)
  71     {
  72         if (is_null($output)) {
  73             $output = 'php://output';
  74         }
  75         $this->xw = new XMLWriter();
  76         $this->xw->openURI($output);
  77         if(is_null($indent)) {
  78             $indent = common_config('site', 'indent');
  79         }
  80         $this->xw->setIndent($indent);
  81     }
  82
  83     /**
  84      * Start a new XML document
  85      *
  86      * @param string $doc    document element
  87      * @param string $public public identifier
  88      * @param string $system system identifier
  89      *
  90      * @return void
  91      */
  92
  93     function startXML($doc=null, $public=null, $system=null)
  94     {
  95         $this->xw->startDocument('1.0', 'UTF-8');
  96         if ($doc) {
  97             $this->xw->writeDTD($doc, $public, $system);
  98         }
  99     }
 100
 101     /**
 102      * finish an XML document
 103      *
 104      * It's probably a bad idea to continue to use this object
 105      * after calling endXML().
 106      *
 107      * @return void
 108      */
 109
 110     function endXML()
 111     {
 112         $this->xw->endDocument();
 113         $this->xw->flush();
 114     }
 115
 116     /**
 117      * output an XML element
 118      *
 119      * Utility for outputting an XML element. A convenient wrapper
 120      * for a bunch of longer XMLWriter calls. This is best for
 121      * when an element doesn't have any sub-elements; if that's the
 122      * case, use elementStart() and elementEnd() instead.
 123      *
 124      * The $content element will be escaped for XML. If you need
 125      * raw output, use elementStart() and elementEnd() with a call
 126      * to raw() in the middle.
 127      *
 128      * If $attrs is a string instead of an array, it will be treated
 129      * as the class attribute of the element.
 130      *
 131      * @param string $tag     Element type or tagname
 132      * @param array  $attrs   Array of element attributes, as
 133      *                        key-value pairs
 134      * @param string $content string content of the element
 135      *
 136      * @return void
 137      */
 138
 139     function element($tag, $attrs=null, $content=null)
 140     {
 141         $this->elementStart($tag, $attrs);
 142         if (!is_null($content)) {
 143             $this->xw->text($content);
 144         }
 145         $this->elementEnd($tag);
 146     }
 147
 148     function elementNS(array $ns, $tag, $attrs=null, $content=null)
 149     {
 150         $this->elementStartNS($ns, $tag, $attrs);
 151         if (!is_null($content)) {
 152             $this->xw->text($content);
 153         }
 154         $this->elementEnd($tag);
 155     }
 156
 157     /**
 158      * output a start tag for an element
 159      *
 160      * Mostly used for when an element has content that's
 161      * not a simple string.
 162      *
 163      * If $attrs is a string instead of an array, it will be treated
 164      * as the class attribute of the element.
 165      *
 166      * @param string $tag   Element type or tagname
 167      * @param array  $attrs Array of element attributes
 168      *
 169      * @return void
 170      */
 171
 172     function elementStart($tag, $attrs=null)
 173     {
 174         $this->xw->startElement($tag);
 175         if (is_array($attrs)) {
 176             foreach ($attrs as $name => $value) {
 177                 $this->xw->writeAttribute($name, $value);
 178             }
 179         } else if (is_string($attrs)) {
 180             $this->xw->writeAttribute('class', $attrs);
 181         }
 182     }
 183
 184     function elementStartNS(array $ns, $tag, $attrs=null)
 185     {
 186         reset($ns); // array pointer to 0
 187         $uri = key($ns);
 188         $this->xw->startElementNS($ns[$uri], $tag, $uri);
 189         if (is_array($attrs)) {
 190             foreach ($attrs as $name => $value) {
 191                 $this->xw->writeAttribute($name, $value);
 192             }
 193         } else if (is_string($attrs)) {
 194             $this->xw->writeAttribute('class', $attrs);
 195         }
 196     }
 197
 198     /**
 199      * output an end tag for an element
 200      *
 201      * Used in conjunction with elementStart(). $tag param
 202      * should match the elementStart() param.
 203      *
 204      * For HTML 4 compatibility, this method will force
 205      * a full end element (</tag>) even if the element is
 206      * empty, except for a handful of exception tagnames.
 207      * This is a hack.
 208      *
 209      * @param string $tag Element type or tagname.
 210      *
 211      * @return void
 212      */
 213
 214     function elementEnd($tag)
 215     {
 216         static $empty_tag = array('base', 'meta', 'link', 'hr',
 217                                   'br', 'param', 'img', 'area',
 218                                   'input', 'col', 'source');
 219         // XXX: check namespace
 220         if (in_array($tag, $empty_tag)) {
 221             $this->xw->endElement();
 222         } else {
 223             $this->xw->fullEndElement();
 224         }
 225     }
 226
 227     /**
 228      * output plain text
 229      *
 230      * Text will be escaped. If you need it not to be,
 231      * use raw() instead.
 232      *
 233      * @param string $txt Text to output.
 234      *
 235      * @return void
 236      */
 237
 238     function text($txt)
 239     {
 240         $this->xw->text($txt);
 241     }
 242
 243     /**
 244      * output raw xml
 245      *
 246      * This will spit out its argument verbatim -- no escaping is
 247      * done.
 248      *
 249      * @param string $xml XML to output.
 250      *
 251      * @return void
 252      */
 253
 254     function raw($xml)
 255     {
 256         $this->xw->writeRaw($xml);
 257     }
 258
 259     /**
 260      * output a comment
 261      *
 262      * @param string $txt text of the comment
 263      *
 264      * @return void
 265      */
 266
 267     function comment($txt)
 268     {
 269         $this->xw->writeComment($txt);
 270     }
 271
 272     /**
 273      * Flush output buffers
 274      *
 275      * @return void
 276      */
 277
 278     function flush()
 279     {
 280         $this->xw->flush();
 281     }
 282 }