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     /**
 146      * output a start tag for an element
 147      *
 148      * Mostly used for when an element has content that's
 149      * not a simple string.
 150      *
 151      * If $attrs is a string instead of an array, it will be treated
 152      * as the class attribute of the element.
 153      *
 154      * @param string $tag   Element type or tagname
 155      * @param array  $attrs Array of element attributes
 156      *
 157      * @return void
 158      */
 159
 160     function elementStart($tag, $attrs=null)
 161     {
 162         $this->xw->startElement($tag);
 163         if (is_array($attrs)) {
 164             foreach ($attrs as $name => $value) {
 165                 $this->xw->writeAttribute($name, $value);
 166             }
 167         } else if (is_string($attrs)) {
 168             $this->xw->writeAttribute('class', $attrs);
 169         }
 170     }
 171
 172     /**
 173      * output an end tag for an element
 174      *
 175      * Used in conjunction with elementStart(). $tag param
 176      * should match the elementStart() param.
 177      *
 178      * For HTML 4 compatibility, this method will force
 179      * a full end element (</tag>) even if the element is
 180      * empty, except for a handful of exception tagnames.
 181      * This is a hack.
 182      *
 183      * @param string $tag Element type or tagname.
 184      *
 185      * @return void
 186      */
 187
 188     function elementEnd($tag)
 189     {
 190         static $empty_tag = array('base', 'meta', 'link', 'hr',
 191                                   'br', 'param', 'img', 'area',
 192                                   'input', 'col');
 193         // XXX: check namespace
 194         if (in_array($tag, $empty_tag)) {
 195             $this->xw->endElement();
 196         } else {
 197             $this->xw->fullEndElement();
 198         }
 199     }
 200
 201     /**
 202      * output plain text
 203      *
 204      * Text will be escaped. If you need it not to be,
 205      * use raw() instead.
 206      *
 207      * @param string $txt Text to output.
 208      *
 209      * @return void
 210      */
 211
 212     function text($txt)
 213     {
 214         $this->xw->text($txt);
 215     }
 216
 217     /**
 218      * output raw xml
 219      *
 220      * This will spit out its argument verbatim -- no escaping is
 221      * done.
 222      *
 223      * @param string $xml XML to output.
 224      *
 225      * @return void
 226      */
 227
 228     function raw($xml)
 229     {
 230         $this->xw->writeRaw($xml);
 231     }
 232
 233     /**
 234      * output a comment
 235      *
 236      * @param string $txt text of the comment
 237      *
 238      * @return void
 239      */
 240
 241     function comment($txt)
 242     {
 243         $this->xw->writeComment($txt);
 244     }
 245 }