extlib/libomb/notice.php

   1 <?php
   2 require_once 'invalidparameterexception.php';
   3 require_once 'Validate.php';
   4 require_once 'helper.php';
   5
   6 /**
   7  * OMB Notice representation
   8  *
   9  * This class represents an OMB notice.
  10  *
  11  * Do not call the setters with null values. Instead, if you want to delete a
  12  * field, pass an empty string. The getters will return null for empty fields.
  13  *
  14  * PHP version 5
  15  *
  16  * LICENSE: This program is free software: you can redistribute it and/or modify
  17  * it under the terms of the GNU Affero General Public License as published by
  18  * the Free Software Foundation, either version 3 of the License, or
  19  * (at your option) any later version.
  20  *
  21  * This program is distributed in the hope that it will be useful,
  22  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  23  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  24  * GNU Affero General Public License for more details.
  25  *
  26  * You should have received a copy of the GNU Affero General Public License
  27  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  28  *
  29  * @package   OMB
  30  * @author    Adrian Lang <mail@adrianlang.de>
  31  * @copyright 2009 Adrian Lang
  32  * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL 3.0
  33  **/
  34
  35 class OMB_Notice {
  36   protected $author;
  37   protected $uri;
  38   protected $content;
  39   protected $url;
  40   protected $license_url; /* url is an own addition for clarification. */
  41   protected $seealso_url; /* url is an own addition for clarification. */
  42   protected $seealso_disposition;
  43   protected $seealso_mediatype;
  44   protected $seealso_license_url; /* url is an addition for clarification. */
  45
  46   /* The notice as OMB param array. Cached and rebuild on usage.
  47      false while outdated. */
  48   protected $param_array;
  49
  50   /**
  51    * Constructor for OMB_Notice
  52    *
  53    * Initializes the OMB_Notice object with author, uri and content.
  54    * These parameters are mandatory for postNotice.
  55    *
  56    * @param object $author  An OMB_Profile object representing the author of the
  57    *                        notice.
  58    * @param string $uri     The notice URI as defined by the OMB. A unique and
  59    *                        unchanging identifier for a notice.
  60    * @param string $content The content of the notice. 140 chars recommended,
  61    *                        but there is no limit.
  62    *
  63    * @access public
  64    */
  65   public function __construct($author, $uri, $content) {
  66     $this->content = $content;
  67     if (is_null($author)) {
  68       throw new OMB_InvalidParameterException('', 'notice', 'omb_listenee');
  69     }
  70     $this->author = $author;
  71
  72     if (!Validate::uri($uri)) {
  73       throw new OMB_InvalidParameterException($uri, 'notice', 'omb_notice');
  74     }
  75     $this->uri = $uri;
  76
  77     $this->param_array = false;
  78   }
  79
  80   /**
  81    * Returns the notice as array
  82    *
  83    * The method returns an array which contains the whole notice as array. The
  84    * array is cached and only rebuilt on changes of the notice.
  85    * Empty optional values are not passed.
  86    *
  87    *  @access  public
  88    *  @returns array The notice as parameter array
  89    */
  90   public function asParameters() {
  91     if ($this->param_array !== false) {
  92       return $this->param_array;
  93     }
  94
  95     $this->param_array = array(
  96                  'omb_notice' => $this->uri,
  97                  'omb_notice_content' => $this->content);
  98
  99     if (!is_null($this->url))
 100       $this->param_array['omb_notice_url'] = $this->url;
 101
 102     if (!is_null($this->license_url))
 103       $this->param_array['omb_notice_license'] = $this->license_url;
 104
 105     if (!is_null($this->seealso_url)) {
 106       $this->param_array['omb_seealso'] = $this->seealso_url;
 107
 108       /* This is actually a free interpretation of the OMB standard. We assume
 109          that additional seealso parameters are not of any use if seealso itself
 110          is not set. */
 111       if (!is_null($this->seealso_disposition))
 112         $this->param_array['omb_seealso_disposition'] =
 113                                                      $this->seealso_disposition;
 114
 115       if (!is_null($this->seealso_mediatype))
 116         $this->param_array['omb_seealso_mediatype'] = $this->seealso_mediatype;
 117
 118       if (!is_null($this->seealso_license_url))
 119         $this->param_array['omb_seealso_license'] = $this->seealso_license_url;
 120     }
 121     return $this->param_array;
 122   }
 123
 124   /**
 125    * Builds an OMB_Notice object from array
 126    *
 127    * The method builds an OMB_Notice object from the passed parameters array.
 128    * The array MUST provide a notice URI and content. The array fields HAVE TO
 129    * be named according to the OMB standard, i. e. omb_notice_* and
 130    * omb_seealso_*. Values are handled as not passed if the corresponding array
 131    * fields are not set or the empty string.
 132    *
 133    * @param object $author     An OMB_Profile object representing the author of
 134    *                           the notice.
 135    * @param string $parameters An array containing the notice parameters.
 136    *
 137    * @access public
 138    *
 139    * @returns OMB_Notice The built OMB_Notice.
 140    */
 141   public static function fromParameters($author, $parameters) {
 142     $notice = new OMB_Notice($author, $parameters['omb_notice'],
 143                              $parameters['omb_notice_content']);
 144
 145     if (isset($parameters['omb_notice_url'])) {
 146       $notice->setURL($parameters['omb_notice_url']);
 147     }
 148
 149     if (isset($parameters['omb_notice_license'])) {
 150       $notice->setLicenseURL($parameters['omb_notice_license']);
 151     }
 152
 153     if (isset($parameters['omb_seealso'])) {
 154       $notice->setSeealsoURL($parameters['omb_seealso']);
 155     }
 156
 157     if (isset($parameters['omb_seealso_disposition'])) {
 158       $notice->setSeealsoDisposition($parameters['omb_seealso_disposition']);
 159     }
 160
 161     if (isset($parameters['omb_seealso_mediatype'])) {
 162       $notice->setSeealsoMediatype($parameters['omb_seealso_mediatype']);
 163     }
 164
 165     if (isset($parameters['omb_seealso_license'])) {
 166       $notice->setSeealsoLicenseURL($parameters['omb_seealso_license']);
 167     }
 168     return $notice;
 169   }
 170
 171   public function getAuthor() {
 172     return $this->author;
 173   }
 174
 175   public function getIdentifierURI() {
 176     return $this->uri;
 177   }
 178
 179   public function getContent() {
 180     return $this->content;
 181   }
 182
 183   public function getURL() {
 184     return $this->url;
 185   }
 186
 187   public function getLicenseURL() {
 188     return $this->license_url;
 189   }
 190
 191   public function getSeealsoURL() {
 192     return $this->seealso_url;
 193   }
 194
 195   public function getSeealsoDisposition() {
 196     return $this->seealso_disposition;
 197   }
 198
 199   public function getSeealsoMediatype() {
 200     return $this->seealso_mediatype;
 201   }
 202
 203   public function getSeealsoLicenseURL() {
 204     return $this->seealso_license_url;
 205   }
 206
 207   public function setURL($url) {
 208     if ($url === '') {
 209       $url = null;
 210     } elseif (!OMB_Helper::validateURL($url)) {
 211       throw new OMB_InvalidParameterException($url, 'notice', 'omb_notice_url');
 212     }
 213     $this->url = $url;
 214     $this->param_array = false;
 215   }
 216
 217   public function setLicenseURL($license_url) {
 218     if ($license_url === '') {
 219       $license_url = null;
 220     } elseif (!OMB_Helper::validateURL($license_url)) {
 221       throw new OMB_InvalidParameterException($license_url, 'notice',
 222                                               'omb_notice_license');
 223     }
 224     $this->license_url = $license_url;
 225     $this->param_array = false;
 226   }
 227
 228   public function setSeealsoURL($seealso_url) {
 229     if ($seealso_url === '') {
 230       $seealso_url = null;
 231     } elseif (!OMB_Helper::validateURL($seealso_url)) {
 232       throw new OMB_InvalidParameterException($seealso_url, 'notice',
 233                                               'omb_seealso');
 234     }
 235     $this->seealso_url = $seealso_url;
 236     $this->param_array = false;
 237   }
 238
 239   public function setSeealsoDisposition($seealso_disposition) {
 240     if ($seealso_disposition === '') {
 241       $seealso_disposition = null;
 242     } elseif ($seealso_disposition !== 'link' && $seealso_disposition !== 'inline') {
 243       throw new OMB_InvalidParameterException($seealso_disposition, 'notice',
 244                                               'omb_seealso_disposition');
 245     }
 246     $this->seealso_disposition = $seealso_disposition;
 247     $this->param_array = false;
 248   }
 249
 250   public function setSeealsoMediatype($seealso_mediatype) {
 251     if ($seealso_mediatype === '') {
 252       $seealso_mediatype = null;
 253     } elseif (!OMB_Helper::validateMediaType($seealso_mediatype)) {
 254       throw new OMB_InvalidParameterException($seealso_mediatype, 'notice',
 255                                               'omb_seealso_mediatype');
 256     }
 257     $this->seealso_mediatype = $seealso_mediatype;
 258     $this->param_array = false;
 259   }
 260
 261   public function setSeealsoLicenseURL($seealso_license_url) {
 262     if ($seealso_license_url === '') {
 263       $seealso_license_url = null;
 264     } elseif (!OMB_Helper::validateURL($seealso_license_url)) {
 265       throw new OMB_InvalidParameterException($seealso_license_url, 'notice',
 266                                               'omb_seealso_license');
 267     }
 268     $this->seealso_license_url = $seealso_license_url;
 269     $this->param_array = false;
 270   }
 271 }
 272 ?>