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