3 * This file is part of libomb
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.
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.
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/>.
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
27 require_once 'invalidparameterexception.php';
28 require_once 'Validate.php';
29 require_once 'helper.php';
32 * OMB Notice representation
34 * This class represents an OMB notice.
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.
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. */
51 /* The notice as OMB param array. Cached and rebuild on usage.
52 false while outdated. */
53 protected $param_array;
56 * Constructor for OMB_Notice
58 * Initializes the OMB_Notice object with author, uri and content.
59 * These parameters are mandatory for postNotice.
61 * @param object $author An OMB_Profile object representing the author of
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.
70 public function __construct($author, $uri, $content)
72 $this->content = $content;
73 if (is_null($author)) {
74 throw new OMB_InvalidParameterException('', 'notice', 'omb_listenee');
76 $this->author = $author;
78 if (!Validate::uri($uri)) {
79 throw new OMB_InvalidParameterException($uri, 'notice', 'omb_notice');
83 $this->param_array = false;
87 * Return the notice as array
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.
94 * @return array The notice as parameter array
96 public function asParameters()
98 if ($this->param_array !== false) {
99 return $this->param_array;
102 $this->param_array = array(
103 'omb_notice' => $this->uri,
104 'omb_notice_content' => $this->content);
106 if (!is_null($this->url))
107 $this->param_array['omb_notice_url'] = $this->url;
109 if (!is_null($this->license_url))
110 $this->param_array['omb_notice_license'] = $this->license_url;
112 if (!is_null($this->seealso_url)) {
113 $this->param_array['omb_seealso'] = $this->seealso_url;
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;
122 if (!is_null($this->seealso_mediatype))
123 $this->param_array['omb_seealso_mediatype'] =
124 $this->seealso_mediatype;
126 if (!is_null($this->seealso_license_url))
127 $this->param_array['omb_seealso_license'] =
128 $this->seealso_license_url;
130 return $this->param_array;
134 * Build an OMB_Notice object from array
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.
142 * @param object $author An OMB_Profile object representing the author
144 * @param string $parameters An array containing the notice parameters.
148 * @returns OMB_Notice The built OMB_Notice.
150 public static function fromParameters($author, $parameters)
152 $notice = new OMB_Notice($author, $parameters['omb_notice'],
153 $parameters['omb_notice_content']);
155 if (isset($parameters['omb_notice_url'])) {
156 $notice->setURL($parameters['omb_notice_url']);
159 if (isset($parameters['omb_notice_license'])) {
160 $notice->setLicenseURL($parameters['omb_notice_license']);
163 if (isset($parameters['omb_seealso'])) {
164 $notice->setSeealsoURL($parameters['omb_seealso']);
167 if (isset($parameters['omb_seealso_disposition'])) {
168 $notice->setSeealsoDisposition($parameters['omb_seealso_disposition']);
171 if (isset($parameters['omb_seealso_mediatype'])) {
172 $notice->setSeealsoMediatype($parameters['omb_seealso_mediatype']);
175 if (isset($parameters['omb_seealso_license'])) {
176 $notice->setSeealsoLicenseURL($parameters['omb_seealso_license']);
181 public function getAuthor()
183 return $this->author;
186 public function getIdentifierURI()
191 public function getContent()
193 return $this->content;
196 public function getURL()
201 public function getLicenseURL()
203 return $this->license_url;
206 public function getSeealsoURL()
208 return $this->seealso_url;
211 public function getSeealsoDisposition()
213 return $this->seealso_disposition;
216 public function getSeealsoMediatype()
218 return $this->seealso_mediatype;
221 public function getSeealsoLicenseURL()
223 return $this->seealso_license_url;
226 public function setURL($url)
228 $this->setVal('notice_url', $url, 'OMB_Helper::validateURL', 'url');
231 public function setLicenseURL($license_url)
233 $this->setVal('license', $license_url, 'OMB_Helper::validateURL',
237 public function setSeealsoURL($seealso_url)
239 $this->setVal('seealso', $seealso_url, 'OMB_Helper::validateURL',
243 public function setSeealsoDisposition($seealso_disposition)
245 $this->setVal('seealso_disposition', $seealso_disposition,
246 'OMB_Notice::validateDisposition');
249 protected static function validateDisposition($str)
251 return in_array($str, array('link', 'inline'));
254 public function setSeealsoMediatype($seealso_mediatype)
256 $this->setVal('seealso_mediatype', $seealso_mediatype,
257 'OMB_Helper::validateMediaType');
260 public function setSeealsoLicenseURL($seealso_license_url)
262 $this->setVal('seealso_license', $seealso_license_url,
263 'OMB_Helper::validateURL', 'seealso_license_url');
269 * Updates a value specified by a parameter name and the new value.
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
277 protected function setVal($param, $value, $validator, $field = null,
280 if (is_null($field)) {
283 if ($value === '' && !$force) {
285 } elseif (!call_user_func($validator, $value)) {
286 throw new OMB_InvalidParameterException($value, 'notice', $param);
288 if ($this->$field !== $value) {
289 $this->$field = $value;
290 $this->param_array = false;