extlib/libomb/profile.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 profile representation
  33  *
  34  * This class represents an OMB profile.
  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_Profile
  40 {
  41     protected $identifier_uri;
  42     protected $profile_url;
  43     protected $nickname;
  44     protected $license_url;
  45     protected $fullname;
  46     protected $homepage;
  47     protected $bio;
  48     protected $location;
  49     protected $avatar_url;
  50
  51     /* The profile as OMB param array. Cached and rebuild on usage.
  52        false while outdated. */
  53     protected $param_array;
  54
  55     /**
  56      * Constructor for OMB_Profile
  57      *
  58      * Initializes the OMB_Profile object with an identifier uri.
  59      *
  60      * @param string $identifier_uri The profile URI as defined by the OMB;
  61      *                               A unique and never changing identifier for
  62      *                               a profile
  63      *
  64      * @access public
  65      */
  66     public function __construct($identifier_uri)
  67     {
  68         if (!Validate::uri($identifier_uri)) {
  69             throw new OMB_InvalidParameterException($identifier_uri, 'profile',
  70                                                 'omb_listenee or omb_listener');
  71         }
  72         $this->identifier_uri = $identifier_uri;
  73         $this->param_array    = false;
  74     }
  75
  76     /**
  77      * Return the profile as array
  78      *
  79      * Returns an array which contains the whole profile as array.
  80      * The array is cached and only rebuilt on changes of the profile.
  81      *
  82      * @param string $prefix    The common prefix to the key for all parameters
  83      * @param bool   $force_all Specifies whether empty fields should be added
  84      *                          to the array as well; This is necessary to
  85      *                          clear fields via updateProfile
  86      *
  87      * @access public
  88      *
  89      * @return array The profile as parameter array
  90      */
  91     public function asParameters($prefix, $force_all = false)
  92     {
  93         if ($this->param_array === false) {
  94             $this->param_array = array('' => $this->identifier_uri);
  95
  96             if ($force_all || !is_null($this->profile_url)) {
  97                 $this->param_array['_profile'] = $this->profile_url;
  98             }
  99
 100             if ($force_all || !is_null($this->homepage)) {
 101                 $this->param_array['_homepage'] = $this->homepage;
 102             }
 103
 104             if ($force_all || !is_null($this->nickname)) {
 105                 $this->param_array['_nickname'] = $this->nickname;
 106             }
 107
 108             if ($force_all || !is_null($this->license_url)) {
 109                 $this->param_array['_license'] = $this->license_url;
 110             }
 111
 112             if ($force_all || !is_null($this->fullname)) {
 113                 $this->param_array['_fullname'] = $this->fullname;
 114             }
 115
 116             if ($force_all || !is_null($this->bio)) {
 117                 $this->param_array['_bio'] = $this->bio;
 118             }
 119
 120             if ($force_all || !is_null($this->location)) {
 121                 $this->param_array['_location'] = $this->location;
 122             }
 123
 124             if ($force_all || !is_null($this->avatar_url)) {
 125                 $this->param_array['_avatar'] = $this->avatar_url;
 126             }
 127
 128         }
 129         $ret = array();
 130         foreach ($this->param_array as $k => $v) {
 131             $ret[$prefix . $k] = $v;
 132         }
 133         return $ret;
 134     }
 135
 136     /**
 137      * Build an OMB_Profile object from array
 138      *
 139      * Builds an OMB_Profile object from the passed parameters array. The
 140      * array MUST provide a profile URI. The array fields HAVE TO be named
 141      * according to the OMB standard. The prefix (omb_listener or omb_listenee)
 142      * is passed as a parameter.
 143      *
 144      * @param string $parameters An array containing the profile parameters
 145      * @param string $prefix     The common prefix of the profile parameter keys
 146      *
 147      * @access public
 148      *
 149      * @returns OMB_Profile The built OMB_Profile
 150      */
 151     public static function fromParameters($parameters, $prefix)
 152     {
 153         if (!isset($parameters[$prefix])) {
 154             throw new OMB_InvalidParameterException('', 'profile', $prefix);
 155         }
 156
 157         $profile = new OMB_Profile($parameters[$prefix]);
 158         $profile->updateFromParameters($parameters, $prefix);
 159         return $profile;
 160     }
 161
 162     /**
 163      * Update from array
 164      *
 165      * Updates from the passed parameters array. The array does not have to
 166      * provide a profile URI. The array fields HAVE TO be named according to the
 167      * OMB standard. The prefix (omb_listener or omb_listenee) is passed as a
 168      * parameter.
 169      *
 170      * @param string $parameters An array containing the profile parameters
 171      * @param string $prefix     The common prefix of the profile parameter keys
 172      *
 173      * @access public
 174      */
 175     public function updateFromParameters($parameters, $prefix)
 176     {
 177         if (isset($parameters[$prefix.'_profile'])) {
 178             $this->setProfileURL($parameters[$prefix.'_profile']);
 179         }
 180
 181         if (isset($parameters[$prefix.'_license'])) {
 182             $this->setLicenseURL($parameters[$prefix.'_license']);
 183         }
 184
 185         if (isset($parameters[$prefix.'_nickname'])) {
 186             $this->setNickname($parameters[$prefix.'_nickname']);
 187         }
 188
 189         if (isset($parameters[$prefix.'_fullname'])) {
 190             $this->setFullname($parameters[$prefix.'_fullname']);
 191         }
 192
 193         if (isset($parameters[$prefix.'_homepage'])) {
 194             $this->setHomepage($parameters[$prefix.'_homepage']);
 195         }
 196
 197         if (isset($parameters[$prefix.'_bio'])) {
 198             $this->setBio($parameters[$prefix.'_bio']);
 199         }
 200
 201         if (isset($parameters[$prefix.'_location'])) {
 202             $this->setLocation($parameters[$prefix.'_location']);
 203         }
 204
 205         if (isset($parameters[$prefix.'_avatar'])) {
 206             $this->setAvatarURL($parameters[$prefix.'_avatar']);
 207         }
 208     }
 209
 210     public function getIdentifierURI()
 211     {
 212         return $this->identifier_uri;
 213     }
 214
 215     public function getProfileURL()
 216     {
 217         return $this->profile_url;
 218     }
 219
 220     public function getHomepage()
 221     {
 222         return $this->homepage;
 223     }
 224
 225     public function getNickname()
 226     {
 227         return $this->nickname;
 228     }
 229
 230     public function getLicenseURL()
 231     {
 232         return $this->license_url;
 233     }
 234
 235     public function getFullname()
 236     {
 237         return $this->fullname;
 238     }
 239
 240     public function getBio()
 241     {
 242         return $this->bio;
 243     }
 244
 245     public function getLocation()
 246     {
 247         return $this->location;
 248     }
 249
 250     public function getAvatarURL()
 251     {
 252         return $this->avatar_url;
 253     }
 254
 255     public function setProfileURL($profile_url)
 256     {
 257         $this->setVal('profile', $profile_url, 'OMB_Helper::validateURL',
 258                       'profile_url');
 259     }
 260
 261     public function setNickname($nickname)
 262     {
 263         $this->setVal('nickname', $nickname, 'OMB_Profile::validateNickname',
 264                       'nickname', true);
 265     }
 266
 267     public function setLicenseURL($license_url)
 268     {
 269         $this->setVal('license', $license_url, 'OMB_Helper::validateURL',
 270                       'license_url');
 271     }
 272
 273     public function setFullname($fullname)
 274     {
 275         $this->setVal('fullname', $fullname, 'OMB_Profile::validate255');
 276     }
 277
 278     public function setHomepage($homepage)
 279     {
 280         $this->setVal('homepage', $homepage, 'OMB_Helper::validateURL');
 281     }
 282
 283     public function setBio($bio)
 284     {
 285         $this->setVal('bio', $bio, 'OMB_Profile::validate140');
 286     }
 287
 288     public function setLocation($location)
 289     {
 290         $this->setVal('location', $location, 'OMB_Profile::validate255');
 291     }
 292
 293     public function setAvatarURL($avatar_url)
 294     {
 295         $this->setVal('avatar', $avatar_url, 'OMB_Helper::validateURL',
 296                       'avatar_url');
 297     }
 298
 299     protected static function validate255($str)
 300     {
 301         return Validate::string($str, array('max_length' => 255));
 302     }
 303
 304     protected static function validate140($str)
 305     {
 306         return Validate::string($str, array('max_length' => 140));
 307     }
 308
 309     protected static function validateNickname($str)
 310     {
 311         return Validate::string($str,
 312                               array('min_length' => 1,
 313                                     'max_length' => 64,
 314                                     'format' => VALIDATE_NUM . VALIDATE_ALPHA));
 315     }
 316
 317     /**
 318      * Set a value
 319      *
 320      * Updates a value specified by a parameter name and the new value.
 321      *
 322      * @param string   $param     The parameter name according to OMB
 323      * @param string   $value     The new value
 324      * @param callback $validator A validator function for the parameter
 325      * @param string   $field     The name of the field in OMB_Profile
 326      * @param bool     $force     Whether null values should be checked as well
 327      */
 328     protected function setVal($param, $value, $validator, $field = null,
 329                               $force = false)
 330     {
 331         if (is_null($field)) {
 332             $field = $param;
 333         }
 334         if ($value === '' && !$force) {
 335             $value = null;
 336         } elseif (!call_user_func($validator, $value)) {
 337             throw new OMB_InvalidParameterException($value, 'profile', $param);
 338         }
 339         if ($this->$field !== $value) {
 340             $this->$field      = $value;
 341             $this->param_array = false;
 342         }
 343     }
 344 }
 345 ?>