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