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         $this->fillFromArray($values);
  56         if (!isset($this->user_id) || !isset($this->hruid)) {
  57             list($this->user_id, $this->hruid) = $this->getLogin($login);
  58         }
  59     }
  60
  61
  62     // Properties accessors.
  63     public function id() { return $this->user_id; }
  64     public function login() { return $this->hruid; }
  65     abstract public function bestEmail();
  66     abstract public function forlifeEmail();
  67
  68
  69     // Determines if the @p id is a valid identifier; if so, returns the user_id
  70     // and the hruid. Otherwise raises UserNotFoundException.
  71     abstract protected function getLogin($login);
  72
  73     // Fills the object from associative arrays containing our data.
  74     // The use case is for arrays got directly from anoter SQL request.
  75     protected function fillFromArray(array $values)
  76     {
  77         foreach ($values as $key => $value) {
  78             if (property_exists($this, $key) && !isset($this->$key)) {
  79                 $this->$key = $value;
  80             }
  81         }
  82     }
  83
  84
  85     // Returns a valid User object built from the @p id and optionnal @p values,
  86     // or returns false and calls the callback if the @p id is not valid.
  87     public static function get($login, $callback = false)
  88     {
  89         return User::getWithValues($login, array(), $callback);
  90     }
  91
  92     public static function getWithValues($login, $values, $callback = false)
  93     {
  94         if (!$callback) {
  95             $callback = array(__CLASS__, '_default_user_callback');
  96         }
  97
  98         try {
  99             return new User($login, $values);
 100         } catch (UserNotFoundException $e) {
 101             return call_user_func($callback, $login, $e->results);
 102         }
 103     }
 104
 105     // Alias on get() with the silent callback.
 106     public static function getSilent($login)
 107     {
 108         return User::getWithValues($login, array(), array(__CLASS__, '_silent_user_callback'));
 109     }
 110
 111     // Returns the forlife emails for @p members. If @p strict mode is enabled,
 112     // it returns the list of validated forlife emails. If strict mode is not,
 113     // it also returns unvalidated values (but still call the callback for them).
 114     public static function getBulkForlifeEmails($logins, $strict = true, $callback = false)
 115     {
 116         if (!is_array($logins)) {
 117             if (strlen(trim($logins)) == 0) {
 118                 return null;
 119             }
 120             $logins = explode(' ', $logins);
 121         }
 122
 123         if ($logins) {
 124             $list = array();
 125             foreach ($logins as $i => $login) {
 126                 if (($user = User::get($login, $callback))) {
 127                     $list[$i] = $user->forlifeEmail();
 128                 } else if(!$strict) {
 129                     $list[$i] = $login;
 130                 }
 131             }
 132             return $list;
 133         }
 134         return null;
 135     }
 136
 137     // Silent callback for the user lookup -- does nothing.
 138     public static function _silent_user_callback($login, $results)
 139     {
 140         return;
 141     }
 142
 143     // Default callback for user lookup -- displays an error message w.r.t. the
 144     // number of matching users found.
 145     abstract public static function _default_user_callback($login, $results);
 146 }
 147
 148 // vim:set et sw=4 sts=4 sws=4 foldmethod=marker enc=utf-8:
 149 ?>