1d639b2007c3a68c86706c0f48597e12ac4d8532
2 /***************************************************************************
3 * Copyright (C) 2003-2008 Polytechnique.org *
4 * http://opensource.polytechnique.org/ *
6 * This program is free software; you can redistribute it and/or modify *
7 * it under the terms of the GNU General Public License as published by *
8 * the Free Software Foundation; either version 2 of the License, or *
9 * (at your option) any later version. *
11 * This program is distributed in the hope that it will be useful, *
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of *
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
14 * GNU General Public License for more details. *
16 * You should have received a copy of the GNU General Public License *
17 * along with this program; if not, write to the Free Software *
19 * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA *
20 ***************************************************************************/
23 * PlUserNotFound is raised when a user id cannot be linked to a real user.
24 * The @p results give the list hruids (useful when several users are found).
26 class UserNotFoundException
extends Exception
28 public function __construct($results = array())
30 $this->results
= $results;
31 parent
::__construct();
36 * Represents an user of plat/al (without any further assumption), with a
37 * special focus on always-used properties (identification fields, display name,
38 * forlife/bestalias emails, ...).
39 * NOTE: each implementation of plat/al-code MUST subclass PlUser, and name it
46 * By convention, null means the information hasn't been fetched yet, and
47 * false means the information is not available.
49 protected $user_id = null
;
50 protected $hruid = null
;
52 // User main email aliases (forlife is the for-life email address, bestalias
53 // is user-chosen preferred email address).
54 protected $forlife = null
;
55 protected $bestalias = null
;
57 // Display name is user-chosen name to display (eg. in "Welcome
58 // <display name> !"), while full name is the official full name.
59 protected $display_name = null
;
60 protected $full_name = null
;
61 protected $promo = null
;
64 protected $perms = null
;
65 protected $perm_flags = null
;
67 // Other properties are listed in this key-value hash map.
68 protected $data = array();
71 * Constructs the PlUser object from an identifier (any identifier which is
72 * understood by getLogin() implementation).
74 * @param $login An user login.
75 * @param $values List of known user properties.
77 public function __construct($login, $values = array())
79 $this->fillFromArray($values);
81 // If the user id was not part of the known values, determines it from
83 if (!$this->user_id
) {
84 $this->user_id
= $this->getLogin($login);
87 // Preloads main properties (assumes the loader will lazily get them
88 // from variables already set in the object).
89 $this->loadMainFields();
93 * Get the canonical user id for the @p login.
95 * @param $login An user login.
96 * @return The canonical user id.
97 * @throws UserNotFoundException when login is not found.
99 abstract protected function getLogin($login);
102 * Loads the main properties (hruid, forlife, bestalias, ...) from the
103 * database. Should return immediately when the properties are already
106 abstract protected function loadMainFields();
109 * Accessors to the main properties, ie. those available as top level
114 return $this->user_id
;
117 public function login()
122 public function bestEmail()
124 return $this->bestalias
;
126 public function forlifeEmail()
128 return $this->forlife
;
131 public function displayName()
133 return $this->display_name
;
135 public function fullName()
137 return $this->full_name
;
141 * Other properties are available directly through the $data array, or as
142 * standard object variables, using a getter.
144 public function data()
149 public function __get($name)
151 if (isset($this->$name)) {
155 if (isset($this->data
[$name])) {
156 return $this->data
[$name];
162 public function __isset($name)
164 return isset($this->$name) ||
isset($this->data
[$name]);
168 * Fills the object properties using the @p associative array; the intended
169 * user case is to fill the object using SQL obtained arrays.
171 * @param $values Key-value array of user properties.
173 protected function fillFromArray(array $values)
175 // Merge main properties with existing ones.
176 unset($values['data']);
177 foreach ($values as $key => $value) {
178 if (property_exists($this, $key) && !isset($this->$key)) {
179 $this->$key = $value;
183 // Merge all value into the $this->data placeholder.
184 $this->data
= array_merge($this->data
, $values);
189 * Build the permissions flags for the user.
191 abstract protected function buildPerms();
194 * Check wether the user got the given permission combination.
196 public function checkPerms($perms)
198 if (is_null($this->perm_flags
)) {
201 if (is_null($this->perm_flags
)) {
204 return $this->perm_flags
->hasFlagCombination($perms);
209 * Returns a valid User object built from the @p id and optionnal @p values,
210 * or returns false and calls the callback if the @p id is not valid.
212 public static function get($login, $callback = false
)
214 return User
::getWithValues($login, array(), $callback);
217 public static function getWithValues($login, $values, $callback = false
)
220 $callback = array('User', '_default_user_callback');
224 return new User($login, $values);
225 } catch (UserNotFoundException
$e) {
226 return call_user_func($callback, $login, $e->results
);
230 // Same as above, but using the silent callback as default.
231 public static function getSilent($login)
233 return User
::getWithValues($login, array(), array('User', '_silent_user_callback'));
236 public static function getSilentWithValues($login, $values)
238 return User
::getWithValues($login, $values, array('User', '_silent_user_callback'));
242 * Returns forlife emails corresponding to the @p logins. If @p strict mode
243 * is disabled, it also includes login for which no forlife was found (but
244 * still call the callback for them).
245 * In all cases, email addresses which are not from the local domains are
248 * @param $logins Array of user logins.
249 * @param $strict Should unvalidated logins be returned as-is or discarded ?
250 * @param $callback Callback to call when a login is unknown to the system.
251 * @return Array of validated user forlife emails.
253 public static function getBulkForlifeEmails($logins, $strict = true
, $callback = false
)
255 if (!is_array($logins)) {
256 if (strlen(trim($logins)) == 0) {
259 $logins = split("[; ,\r\n\|]+", $logins);
264 foreach ($logins as $i => $login) {
265 $login = trim($login);
270 if (($user = User
::get($login, $callback))) {
271 $list[$i] = $user->forlifeEmail();
272 } else if (!$strict || User
::isForeignEmailAddress($login)) {
282 * Predefined callbacks for the user lookup; they are called when a given
283 * login is found not to be associated with any valid user. Silent callback
284 * does nothing; default callback is supposed to display an error message,
285 * using the Platal::page() hook.
287 public static function _silent_user_callback($login, $results)
292 abstract public static function _default_user_callback($login, $results);
295 * Determines if the @p login is an email address, and an email address not
296 * served locally by plat/al.
298 abstract public static function isForeignEmailAddress($email);
301 // vim:set et sw=4 sts=4 sws=4 foldmethod=marker enc=utf-8: