Commit | Line | Data |
---|---|---|
5421ab09 VZ |
1 | <?php |
2 | /*************************************************************************** | |
3 | * Copyright (C) 2003-2008 Polytechnique.org * | |
4 | * http://opensource.polytechnique.org/ * | |
5 | * * | |
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. * | |
10 | * * | |
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. * | |
15 | * * | |
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 * | |
18 | * Foundation, Inc., * | |
19 | * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA * | |
20 | ***************************************************************************/ | |
21 | ||
22 | /** | |
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). | |
25 | */ | |
26 | class UserNotFoundException extends Exception | |
27 | { | |
28 | public function __construct($results = array()) | |
29 | { | |
30 | $this->results = $results; | |
31 | parent::__construct(); | |
32 | } | |
33 | } | |
34 | ||
35 | /** | |
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 | |
40 | * 'User'. | |
41 | */ | |
42 | abstract class PlUser | |
43 | { | |
44 | /** | |
45 | * User data storage. | |
46 | * By convention, null means the information hasn't been fetched yet, and | |
47 | * false means the information is not available. | |
48 | */ | |
49 | protected $user_id = null; | |
50 | protected $hruid = null; | |
51 | ||
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; | |
56 | ||
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; | |
62 | ||
63 | // Other properties are listed in this key-value hash map. | |
64 | protected $data = array(); | |
65 | ||
66 | /** | |
67 | * Constructs the PlUser object from an identifier (any identifier which is | |
68 | * understood by getLogin() implementation). | |
69 | * | |
70 | * @param $login An user login. | |
71 | * @param $values List of known user properties. | |
72 | */ | |
73 | public function __construct($login, $values = array()) | |
74 | { | |
75 | $this->fillFromArray($values); | |
76 | ||
77 | // If the user id was not part of the known values, determines it from | |
78 | // the login. | |
79 | if (!$this->user_id) { | |
80 | $this->user_id = $this->getLogin($login); | |
81 | } | |
82 | ||
83 | // Preloads main properties (assumes the loader will lazily get them | |
84 | // from variables already set in the object). | |
85 | $this->loadMainFields(); | |
86 | } | |
87 | ||
88 | /** | |
89 | * Get the canonical user id for the @p login. | |
90 | * | |
91 | * @param $login An user login. | |
92 | * @return The canonical user id. | |
93 | * @throws UserNotFoundException when login is not found. | |
94 | */ | |
95 | abstract protected function getLogin($login); | |
96 | ||
97 | /** | |
98 | * Loads the main properties (hruid, forlife, bestalias, ...) from the | |
99 | * database. Should return immediately when the properties are already | |
100 | * available. | |
101 | */ | |
102 | abstract protected function loadMainFields(); | |
103 | ||
104 | /** | |
105 | * Accessors to the main properties, ie. those available as top level | |
106 | * object variables. | |
107 | */ | |
108 | public function id() { return $this->user_id; } | |
109 | public function login() { return $this->hruid; } | |
110 | ||
111 | public function bestEmail() { return $this->bestalias; } | |
112 | public function forlifeEmail() { return $this->forlife; } | |
113 | ||
114 | public function displayName() { return $this->display_name; } | |
115 | public function fullName() { return $this->full_name; } | |
116 | ||
117 | /** | |
118 | * Other properties are available directly through the $data array, or as | |
119 | * standard object variables, using a getter. | |
120 | */ | |
121 | public function data() { return $this->data; } | |
122 | ||
123 | public function __get($name) | |
124 | { | |
125 | if (isset($this->$name)) { | |
126 | return $this->$name; | |
127 | } | |
128 | ||
129 | if (isset($this->data[$name])) { | |
130 | return $this->data[$name]; | |
131 | } | |
132 | ||
133 | return null; | |
134 | } | |
135 | ||
136 | public function __isset($name) | |
137 | { | |
138 | return isset($this->$name) || isset($this->data[$name]); | |
139 | } | |
140 | ||
141 | /** | |
142 | * Fills the object properties using the @p associative array; the intended | |
143 | * user case is to fill the object using SQL obtained arrays. | |
144 | * | |
145 | * @param $values Key-value array of user properties. | |
146 | */ | |
147 | protected function fillFromArray(array $values) | |
148 | { | |
149 | // Merge main properties with existing ones. | |
150 | unset($values['data']); | |
151 | foreach ($values as $key => $value) { | |
152 | if (property_exists($this, $key) && !isset($this->$key)) { | |
153 | $this->$key = $value; | |
154 | } | |
155 | } | |
156 | ||
157 | // Merge all value into the $this->data placeholder. | |
158 | $this->data = array_merge($this->data, $values); | |
159 | } | |
160 | ||
161 | ||
162 | /** | |
163 | * Returns a valid User object built from the @p id and optionnal @p values, | |
164 | * or returns false and calls the callback if the @p id is not valid. | |
165 | */ | |
166 | public static function get($login, $callback = false) | |
167 | { | |
168 | return User::getWithValues($login, array(), $callback); | |
169 | } | |
170 | ||
171 | public static function getWithValues($login, $values, $callback = false) | |
172 | { | |
173 | if (!$callback) { | |
174 | $callback = array('User', '_default_user_callback'); | |
175 | } | |
176 | ||
177 | try { | |
178 | return new User($login, $values); | |
179 | } catch (UserNotFoundException $e) { | |
180 | return call_user_func($callback, $login, $e->results); | |
181 | } | |
182 | } | |
183 | ||
184 | // Same as above, but using the silent callback as default. | |
185 | public static function getSilent($login) | |
186 | { | |
187 | return User::getWithValues($login, array(), array('User', '_silent_user_callback')); | |
188 | } | |
189 | ||
190 | public static function getSilentWithValues($login, $values) | |
191 | { | |
192 | return User::getWithValues($login, $values, array('User', '_silent_user_callback')); | |
193 | } | |
194 | ||
195 | /** | |
196 | * Returns forlife emails corresponding to the @p logins. If @p strict mode | |
197 | * is disabled, it also includes login for which no forlife was found (but | |
198 | * still call the callback for them). | |
199 | * In all cases, email addresses which are not from the local domains are | |
200 | * kept. | |
201 | * | |
202 | * @param $logins Array of user logins. | |
203 | * @param $strict Should unvalidated logins be returned as-is or discarded ? | |
204 | * @param $callback Callback to call when a login is unknown to the system. | |
205 | * @return Array of validated user forlife emails. | |
206 | */ | |
207 | public static function getBulkForlifeEmails($logins, $strict = true, $callback = false) | |
208 | { | |
209 | if (!is_array($logins)) { | |
210 | if (strlen(trim($logins)) == 0) { | |
211 | return null; | |
212 | } | |
213 | $logins = split("[; ,\r\n\|]+", $logins); | |
214 | } | |
215 | ||
216 | if ($logins) { | |
217 | $list = array(); | |
218 | foreach ($logins as $i => $login) { | |
219 | $login = trim($login); | |
220 | if (empty($login)) { | |
221 | continue; | |
222 | } | |
223 | ||
224 | if (($user = User::get($login, $callback))) { | |
225 | $list[$i] = $user->forlifeEmail(); | |
226 | } else if (!$strict || User::isForeignEmailAddress($login)) { | |
227 | $list[$i] = $login; | |
228 | } | |
229 | } | |
230 | return $list; | |
231 | } | |
232 | return null; | |
233 | } | |
234 | ||
235 | /** | |
236 | * Predefined callbacks for the user lookup; they are called when a given | |
237 | * login is found not to be associated with any valid user. Silent callback | |
238 | * does nothing; default callback is supposed to display an error message, | |
239 | * using the Platal::page() hook. | |
240 | */ | |
241 | public static function _silent_user_callback($login, $results) | |
242 | { | |
243 | return; | |
244 | } | |
245 | ||
246 | abstract public static function _default_user_callback($login, $results); | |
247 | ||
248 | /** | |
249 | * Determines if the @p login is an email address, and an email address not | |
250 | * served locally by plat/al. | |
251 | */ | |
252 | abstract public static function isForeignEmailAddress($email); | |
253 | } | |
254 | ||
255 | // vim:set et sw=4 sts=4 sws=4 foldmethod=marker enc=utf-8: | |
256 | ?> |