lib/atom10feed.php

   1 <?php
   2 /**
   3  * StatusNet, the distributed open-source microblogging tool
   4  *
   5  * Class for building an Atom feed in memory
   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  Feed
  23  * @package   StatusNet
  24  * @author    Zach Copley <zach@status.net>
  25  * @copyright 2010 StatusNet, Inc.
  26  * @license   http://www.fsf.org/licensing/licenses/agpl-3.0.html GNU Affero General Public License version 3.0
  27  * @link      http://status.net/
  28  */
  29
  30 if (!defined('STATUSNET'))
  31 {
  32     exit(1);
  33 }
  34
  35 class Atom10FeedException extends Exception
  36 {
  37 }
  38
  39 /**
  40  * Class for building an Atom feed in memory.  Get the finished doc
  41  * as a string with Atom10Feed::getString().
  42  *
  43  * @category Feed
  44  * @package  StatusNet
  45  * @author   Zach Copley <zach@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  */
  49 class Atom10Feed extends XMLStringer
  50 {
  51     public  $xw;
  52
  53     // @fixme most of these should probably be read-only properties
  54     private $namespaces;
  55     private $authors;
  56     private $subject;
  57     private $categories;
  58     private $contributors;
  59     private $generator;
  60     private $icon;
  61     private $links;
  62     private $selfLink;
  63     private $selfLinkType;
  64     public $logo;
  65     private $rights;
  66     public $subtitle;
  67     public $title;
  68     private $published;
  69     private $updated;
  70     private $entries;
  71
  72     /**
  73      * Constructor
  74      *
  75      * @param boolean $indent  flag to turn indenting on or off
  76      *
  77      * @return void
  78      */
  79     function __construct($indent = true) {
  80         parent::__construct($indent);
  81         $this->namespaces = array();
  82         $this->authors    = array();
  83         $this->links      = array();
  84         $this->entries    = array();
  85         $this->addNamespace('', 'http://www.w3.org/2005/Atom');
  86     }
  87
  88     /**
  89      * Add another namespace to the feed
  90      *
  91      * @param string $namespace the namespace
  92      * @param string $uri       namspace uri
  93      *
  94      * @return void
  95      */
  96     function addNamespace($namespace, $uri)
  97     {
  98         $ns = array($namespace => $uri);
  99         $this->namespaces = array_merge($this->namespaces, $ns);
 100     }
 101
 102     function addAuthor($name, $uri = null, $email = null)
 103     {
 104         $xs = new XMLStringer(true);
 105
 106         $xs->elementStart('author');
 107
 108         if (!empty($name)) {
 109             $xs->element('name', null, $name);
 110         } else {
 111             throw new Atom10FeedException(
 112                 // TRANS: Atom feed exception thrown when an author element does not contain a name element.
 113                 _('Author element must contain a name element.')
 114             );
 115         }
 116
 117         if (isset($uri)) {
 118             $xs->element('uri', null, $uri);
 119         }
 120
 121         if (isset($email)) {
 122             $xs->element('email', null, $email);
 123         }
 124
 125         $xs->elementEnd('author');
 126
 127         array_push($this->authors, $xs->getString());
 128     }
 129
 130     /**
 131      * Add an Author to the feed via raw XML string
 132      *
 133      * @param string $xmlAuthor An XML string representation author
 134      *
 135      * @return void
 136      */
 137     function addAuthorRaw($xmlAuthor)
 138     {
 139         array_push($this->authors, $xmlAuthor);
 140     }
 141
 142     function renderAuthors()
 143     {
 144         foreach ($this->authors as $author) {
 145             $this->raw($author);
 146         }
 147     }
 148
 149     /**
 150      * Deprecated <activity:subject>; ignored
 151      *
 152      * @param string $xmlSubject An XML string representation of the subject
 153      *
 154      * @return void
 155      */
 156
 157     function setActivitySubject($xmlSubject)
 158     {
 159         // TRANS: Server exception thrown when using the method setActivitySubject() in the class Atom10Feed.
 160         throw new ServerException(_('Do not use this method!'));
 161     }
 162
 163     function getNamespaces()
 164     {
 165         return $this->namespaces;
 166     }
 167
 168     function initFeed()
 169     {
 170         $this->xw->startDocument('1.0', 'UTF-8');
 171         $commonAttrs = array('xml:lang' => 'en-US');
 172         foreach ($this->namespaces as $prefix => $uri) {
 173             if ($prefix == '') {
 174                 $attr = 'xmlns';
 175             } else {
 176                 $attr = 'xmlns:' . $prefix;
 177             }
 178             $commonAttrs[$attr] = $uri;
 179         }
 180         $this->elementStart('feed', $commonAttrs);
 181
 182         $this->element(
 183             'generator', array(
 184                 'uri'     => 'http://status.net',
 185                 'version' => STATUSNET_VERSION
 186             ),
 187             'StatusNet'
 188         );
 189
 190         $this->element('id', null, $this->id);
 191         $this->element('title', null, $this->title);
 192         $this->element('subtitle', null, $this->subtitle);
 193
 194         if (!empty($this->logo)) {
 195             $this->element('logo', null, $this->logo);
 196         }
 197
 198         $this->element('updated', null, $this->updated);
 199
 200         $this->renderAuthors();
 201
 202         if ($this->selfLink) {
 203             $this->addLink($this->selfLink, array('rel' => 'self',
 204                                                   'type' => $this->selfLinkType));
 205         }
 206         $this->renderLinks();
 207     }
 208
 209     /**
 210      * Check that all required elements have been set, etc.
 211      * Throws an Atom10FeedException if something's missing.
 212      *
 213      * @return void
 214      */
 215     function validate()
 216     {
 217     }
 218
 219     function renderLinks()
 220     {
 221         foreach ($this->links as $attrs)
 222         {
 223             $this->element('link', $attrs, null);
 224         }
 225     }
 226
 227     function addEntryRaw($xmlEntry)
 228     {
 229         array_push($this->entries, $xmlEntry);
 230     }
 231
 232     function addEntry($entry)
 233     {
 234         array_push($this->entries, $entry->getString());
 235     }
 236
 237     function renderEntries()
 238     {
 239         foreach ($this->entries as $entry) {
 240             $this->raw($entry);
 241         }
 242     }
 243
 244     function endFeed()
 245     {
 246         $this->elementEnd('feed');
 247         $this->xw->endDocument();
 248     }
 249
 250     function getString()
 251     {
 252         if (Event::handle('StartApiAtom', array($this))) {
 253
 254             $this->validate();
 255             $this->initFeed();
 256
 257             if (!empty($this->subject)) {
 258                 $this->raw($this->subject);
 259             }
 260
 261             $this->renderEntries();
 262             $this->endFeed();
 263
 264             Event::handle('EndApiAtom', array($this));
 265         }
 266
 267         return $this->xw->outputMemory();
 268     }
 269
 270     function setId($id)
 271     {
 272         $this->id = $id;
 273     }
 274
 275     function setSelfLink($url, $type='application/atom+xml')
 276     {
 277         $this->selfLink = $url;
 278         $this->selfLinkType = $type;
 279     }
 280
 281     function setTitle($title)
 282     {
 283         $this->title = $title;
 284     }
 285
 286     function setSubtitle($subtitle)
 287     {
 288         $this->subtitle = $subtitle;
 289     }
 290
 291     function setLogo($logo)
 292     {
 293         $this->logo = $logo;
 294     }
 295
 296     function setUpdated($dt)
 297     {
 298         $this->updated = common_date_iso8601($dt);
 299     }
 300
 301     function setPublished($dt)
 302     {
 303         $this->published = common_date_iso8601($dt);
 304     }
 305
 306     /**
 307      * Adds a link element into the Atom document
 308      *
 309      * Assumes you want rel="alternate" and type="text/html" unless
 310      * you send in $otherAttrs.
 311      *
 312      * @param string $uri            the uri the href needs to point to
 313      * @param array  $otherAttrs     other attributes to stick in
 314      *
 315      * @return void
 316      */
 317     function addLink($uri, $otherAttrs = null) {
 318         $attrs = array('href' => $uri);
 319
 320         if (is_null($otherAttrs)) {
 321             $attrs['rel']  = 'alternate';
 322             $attrs['type'] = 'text/html';
 323         } else {
 324             $attrs = array_merge($attrs, $otherAttrs);
 325         }
 326
 327         array_push($this->links, $attrs);
 328     }
 329 }