includes/user/CentralIdLookup.php

   1 <?php
   2 /**
   3  * A central user id lookup service
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  18  * http://www.gnu.org/copyleft/gpl.html
  19  *
  20  * @file
  21  */
  22
  23 /**
  24  * The CentralIdLookup service allows for connecting local users with
  25  * cluster-wide IDs.
  26  */
  27 abstract class CentralIdLookup implements IDBAccessObject {
  28         // Audience options for accessors
  29         const AUDIENCE_PUBLIC = 1;
  30         const AUDIENCE_RAW = 2;
  31
  32         /** @var CentralIdLookup[][] */
  33         private static $instances = array();
  34
  35         /** @var string */
  36         private $providerId;
  37
  38         /**
  39          * Fetch a CentralIdLookup
  40          * @param string|null $providerId Provider ID from $wgCentralIdLookupProviders
  41          * @return CentralIdLookup|null
  42          */
  43         public static function factory( $providerId = null ) {
  44                 global $wgCentralIdLookupProviders, $wgCentralIdLookupProvider;
  45
  46                 if ( $providerId === null ) {
  47                         $providerId = $wgCentralIdLookupProvider;
  48                 }
  49
  50                 if ( !array_key_exists( $providerId, self::$instances ) ) {
  51                         self::$instances[$providerId] = null;
  52
  53                         if ( isset( $wgCentralIdLookupProviders[$providerId] ) ) {
  54                                 $provider = ObjectFactory::getObjectFromSpec( $wgCentralIdLookupProviders[$providerId] );
  55                                 if ( $provider instanceof CentralIdLookup ) {
  56                                         $provider->providerId = $providerId;
  57                                         self::$instances[$providerId] = $provider;
  58                                 }
  59                         }
  60                 }
  61
  62                 return self::$instances[$providerId];
  63         }
  64
  65         final public function getProviderId() {
  66                 return $this->providerId;
  67         }
  68
  69         /**
  70          * Check that the "audience" parameter is valid
  71          * @param int|User $audience One of the audience constants, or a specific user
  72          * @return User|null User to check against, or null if no checks are needed
  73          * @throws InvalidArgumentException
  74          */
  75         protected function checkAudience( $audience ) {
  76                 if ( $audience instanceof User ) {
  77                         return $audience;
  78                 }
  79                 if ( $audience === self::AUDIENCE_PUBLIC ) {
  80                         return new User;
  81                 }
  82                 if ( $audience === self::AUDIENCE_RAW ) {
  83                         return null;
  84                 }
  85                 throw new InvalidArgumentException( 'Invalid audience' );
  86         }
  87
  88         /**
  89          * Check that a User is attached on the specified wiki.
  90          *
  91          * If unattached local accounts don't exist in your extension, this comes
  92          * down to a check whether the central account exists at all and that
  93          * $wikiId is using the same central database.
  94          *
  95          * @param User $user
  96          * @param string|null $wikiId Wiki to check attachment status. If null, check the current wiki.
  97          * @return bool
  98          */
  99         abstract public function isAttached( User $user, $wikiId = null );
 100
 101         /**
 102          * Given central user IDs, return the (local) user names
 103          * @note There's no requirement that the user names actually exist locally,
 104          *  or if they do that they're actually attached to the central account.
 105          * @param array $idToName Array with keys being central user IDs
 106          * @param int|User $audience One of the audience constants, or a specific user
 107          * @param int $flags IDBAccessObject read flags
 108          * @return array Copy of $idToName with values set to user names (or
 109          *  empty-string if the user exists but $audience lacks the rights needed
 110          *  to see it). IDs not corresponding to a user are unchanged.
 111          */
 112         abstract public function lookupCentralIds(
 113                 array $idToName, $audience = self::AUDIENCE_PUBLIC, $flags = self::READ_NORMAL
 114         );
 115
 116         /**
 117          * Given (local) user names, return the central IDs
 118          * @note There's no requirement that the user names actually exist locally,
 119          *  or if they do that they're actually attached to the central account.
 120          * @param array $nameToId Array with keys being canonicalized user names
 121          * @param int|User $audience One of the audience constants, or a specific user
 122          * @param int $flags IDBAccessObject read flags
 123          * @return array Copy of $nameToId with values set to central IDs.
 124          *  Names not corresponding to a user (or $audience lacks the rights needed
 125          *  to see it) are unchanged.
 126          */
 127         abstract public function lookupUserNames(
 128                 array $nameToId, $audience = self::AUDIENCE_PUBLIC, $flags = self::READ_NORMAL
 129         );
 130
 131         /**
 132          * Given a central user ID, return the (local) user name
 133          * @note There's no requirement that the user name actually exists locally,
 134          *  or if it does that it's actually attached to the central account.
 135          * @param int $id Central user ID
 136          * @param int|User $audience One of the audience constants, or a specific user
 137          * @param int $flags IDBAccessObject read flags
 138          * @return string|null User name, or empty string if $audience lacks the
 139          *  rights needed to see it, or null if $id doesn't correspond to a user
 140          */
 141         public function nameFromCentralId(
 142                 $id, $audience = self::AUDIENCE_PUBLIC, $flags = self::READ_NORMAL
 143         ) {
 144                 $idToName = $this->lookupCentralIds( array( $id => null ), $audience, $flags );
 145                 return $idToName[$id];
 146         }
 147
 148         /**
 149          * Given a (local) user name, return the central ID
 150          * @note There's no requirement that the user name actually exists locally,
 151          *  or if it does that it's actually attached to the central account.
 152          * @param string $name Canonicalized user name
 153          * @param int|User $audience One of the audience constants, or a specific user
 154          * @param int $flags IDBAccessObject read flags
 155          * @return int User ID; 0 if the name does not correspond to a user or
 156          *  $audience lacks the rights needed to see it.
 157          */
 158         public function centralIdFromName(
 159                 $name, $audience = self::AUDIENCE_PUBLIC, $flags = self::READ_NORMAL
 160         ) {
 161                 $nameToId = $this->lookupUserNames( array( $name => 0 ), $audience, $flags );
 162                 return $nameToId[$name];
 163         }
 164
 165         /**
 166          * Given a central user ID, return a local User object
 167          * @note Unlike nameFromCentralId(), this does guarantee that the local
 168          *  user exists and is attached to the central account.
 169          * @param int $id Central user ID
 170          * @param int|User $audience One of the audience constants, or a specific user
 171          * @param int $flags IDBAccessObject read flags
 172          * @return User|null Local user, or null if: $id doesn't correspond to a
 173          *  user, $audience lacks the rights needed to see the user, the user
 174          *  doesn't exist locally, or the user isn't locally attached.
 175          */
 176         public function localUserFromCentralId(
 177                 $id, $audience = self::AUDIENCE_PUBLIC, $flags = self::READ_NORMAL
 178         ) {
 179                 $name = $this->nameFromCentralId( $id, $audience, $flags );
 180                 if ( $name !== null && $name !== '' ) {
 181                         $user = User::newFromName( $name );
 182                         if ( $user && $user->getId() && $this->isAttached( $user ) ) {
 183                                 return $user;
 184                         }
 185                 }
 186                 return null;
 187         }
 188
 189         /**
 190          * Given a local User object, return the central ID
 191          * @note Unlike centralIdFromName(), this does guarantee that the local
 192          *  user is attached to the central account.
 193          * @param User $user Local user
 194          * @param int|User $audience One of the audience constants, or a specific user
 195          * @param int $flags IDBAccessObject read flags
 196          * @return int User ID; 0 if the local user does not correspond to a
 197          *  central user, $audience lacks the rights needed to see it, or the
 198          *  central user isn't locally attached.
 199          */
 200         public function centralIdFromLocalUser(
 201                 User $user, $audience = self::AUDIENCE_PUBLIC, $flags = self::READ_NORMAL
 202         ) {
 203                 return $this->isAttached( $user )
 204                         ? $this->centralIdFromName( $user->getName(), $audience, $flags )
 205                         : 0;
 206         }
 207
 208 }