lib/xmloutputter.php

   1 <?php
   2 /**
   3  * Laconica, 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   Laconica
  24  * @author    Evan Prodromou <evan@controlyourself.ca>
  25  * @author    Sarven Capadisli <csarven@controlyourself.ca>
  26  * @copyright 2008 Control Yourself, Inc.
  27  * @license   http://www.fsf.org/licensing/licenses/agpl-3.0.html GNU Affero General Public License version 3.0
  28  * @link      http://laconi.ca/
  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  Laconica
  44  * @author   Evan Prodromou <evan@controlyourself.ca>
  45  * @author   Sarven Capadisli <csarven@controlyourself.ca>
  46  * @license  http://www.fsf.org/licensing/licenses/agpl-3.0.html GNU Affero General Public License version 3.0
  47  * @link     http://laconi.ca/
  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 $output URL for outputting, defaults to stdout
  67      * @param $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         $this->xw->startDocument('1.0', 'UTF-8');
  76     }
  77
  78     /**
  79      * Start a new XML document
  80      *
  81      * @param string $doc    document element
  82      * @param string $public public identifier
  83      * @param string $system system identifier
  84      *
  85      * @return void
  86      */
  87
  88     function startXML($doc=null, $public=null, $system=null)
  89     {
  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      * @param string $tag     Element type or tagname
 123      * @param array  $attrs   Array of element attributes, as
 124      *                        key-value pairs
 125      * @param string $content string content of the element
 126      *
 127      * @return void
 128      */
 129
 130     function element($tag, $attrs=null, $content=null)
 131     {
 132         $this->elementStart($tag, $attrs);
 133         if (!is_null($content)) {
 134             $this->xw->text($content);
 135         }
 136         $this->elementEnd($tag);
 137     }
 138
 139     /**
 140      * output a start tag for an element
 141      *
 142      * Mostly used for when an element has content that's
 143      * not a simple string.
 144      *
 145      * @param string $tag   Element type or tagname
 146      * @param array  $attrs Array of element attributes
 147      *
 148      * @return void
 149      */
 150
 151     function elementStart($tag, $attrs=null)
 152     {
 153         $this->xw->startElement($tag);
 154         if (is_array($attrs)) {
 155             foreach ($attrs as $name => $value) {
 156                 $this->xw->writeAttribute($name, $value);
 157             }
 158         } else if (is_string($attrs)) {
 159             $this->xw->writeAttribute('class', $attrs);
 160         }
 161     }
 162
 163     /**
 164      * output an end tag for an element
 165      *
 166      * Used in conjunction with elementStart(). $tag param
 167      * should match the elementStart() param.
 168      *
 169      * For HTML 4 compatibility, this method will force
 170      * a full end element (</tag>) even if the element is
 171      * empty, except for a handful of exception tagnames.
 172      * This is a hack.
 173      *
 174      * @param string $tag Element type or tagname.
 175      *
 176      * @return void
 177      */
 178
 179     function elementEnd($tag)
 180     {
 181         static $empty_tag = array('base', 'meta', 'link', 'hr',
 182                                   'br', 'param', 'img', 'area',
 183                                   'input', 'col');
 184         // XXX: check namespace
 185         if (in_array($tag, $empty_tag)) {
 186             $this->xw->endElement();
 187         } else {
 188             $this->xw->fullEndElement();
 189         }
 190     }
 191
 192     /**
 193      * output plain text
 194      *
 195      * Text will be escaped. If you need it not to be,
 196      * use raw() instead.
 197      *
 198      * @param string $txt Text to output.
 199      *
 200      * @return void
 201      */
 202
 203     function text($txt)
 204     {
 205         $this->xw->text($txt);
 206     }
 207
 208     /**
 209      * output raw xml
 210      *
 211      * This will spit out its argument verbatim -- no escaping is
 212      * done.
 213      *
 214      * @param string $xml XML to output.
 215      *
 216      * @return void
 217      */
 218
 219     function raw($xml)
 220     {
 221         $this->xw->writeRaw($xml);
 222     }
 223 }