classes/pluser.php

   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 // PlUserNotFound is raised when a given id cannot be linked to an existing user.
  23 // The @p results give the list hruids (useful when several users are found).
  24 class UserNotFoundException extends Exception
  25 {
  26     public function __construct($results = array())
  27     {
  28         $this->results = $results;
  29         parent::__construct();
  30     }
  31 }
  32
  33 // Represents an user of the system, with a special focus on its identification
  34 // (hruid, forlife, and bestalias).
  35 // Note: each implementation of platal-core MUST create a subclass 'User' of
  36 // this abstract PlUser class.
  37 abstract class PlUser
  38 {
  39     // User's data storage. By convention, null means the information hasn't
  40     // been fetched yet, and false means the information is not available.
  41
  42     // Main (unique) identifiers.
  43     protected $user_id = null;
  44     protected $hruid = null;
  45
  46     // User's emails (bestalias should be preferred when sending emails).
  47     protected $forlife = null;
  48     protected $bestalias = null;
  49
  50
  51     // Constructs the object from an identifier (hruid/uid/email alias/email
  52     // redirection) and an optionnal array of known user properties.
  53     public function __construct($login, $values = array())
  54     {
  55         list($this->user_id, $this->hruid) = $this->getLogin($login);
  56         $this->fillFromArray($values);
  57     }
  58
  59
  60     // Properties accessors.
  61     public function id() { return $this->user_id; }
  62     public function login() { return $this->hruid; }
  63     abstract public function bestEmail();
  64     abstract public function forlifeEmail();
  65
  66
  67     // Determines if the @p id is a valid identifier; if so, returns the user_id
  68     // and the hruid. Otherwise raises UserNotFoundException.
  69     abstract protected function getLogin($login);
  70
  71     // Fills the object from associative arrays containing our data.
  72     // The use case is for arrays got directly from anoter SQL request.
  73     protected function fillFromArray(array $values)
  74     {
  75         foreach ($values as $key => $value) {
  76             if (property_exists($this, $key) && !isset($this->$key)) {
  77                 $this->$key = $value;
  78             }
  79         }
  80     }
  81
  82
  83     // Returns a valid User object built from the @p id and optionnal @p values,
  84     // or returns false and calls the callback if the @p id is not valid.
  85     public static function get($login, $callback = false)
  86     {
  87         return User::getWithValues($login, array(), $callback);
  88     }
  89
  90     public static function getWithValues($login, $values, $callback = false)
  91     {
  92         if (!$callback) {
  93             $callback = array(__CLASS__, '_default_user_callback');
  94         }
  95
  96         try {
  97             return new User($login, $values);
  98         } catch (UserNotFoundException $e) {
  99             return call_user_func($callback, $login, $e->results);
 100         }
 101     }
 102
 103     // Alias on get() with the silent callback.
 104     public static function getSilent($login)
 105     {
 106         return User::getWithValues($login, array(), array(__CLASS__, '_silent_user_callback'));
 107     }
 108
 109     // Returns the forlife emails for @p members. If @p strict mode is enabled,
 110     // it returns the list of validated forlife emails. If strict mode is not,
 111     // it also returns unvalidated values (but still call the callback for them).
 112     public static function getBulkForlifeEmails($logins, $strict = true, $callback = false)
 113     {
 114         if (!is_array($logins)) {
 115             if (strlen(trim($logins)) == 0) {
 116                 return null;
 117             }
 118             $logins = explode(' ', $logins);
 119         }
 120
 121         if ($logins) {
 122             $list = array();
 123             foreach ($logins as $i => $login) {
 124                 if (($user = User::get($login, $callback))) {
 125                     $list[$i] = $user->forlifeEmail();
 126                 } else if(!$strict) {
 127                     $list[$i] = $login;
 128                 }
 129             }
 130             return $list;
 131         }
 132         return null;
 133     }
 134
 135     // Silent callback for the user lookup -- does nothing.
 136     public static function _silent_user_callback($login, $results)
 137     {
 138         return;
 139     }
 140
 141     // Default callback for user lookup -- displays an error message w.r.t. the
 142     // number of matching users found.
 143     abstract public static function _default_user_callback($login, $results);
 144 }
 145
 146 // vim:set et sw=4 sts=4 sws=4 foldmethod=marker enc=utf-8:
 147 ?>