extlib/libomb/notice.php

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