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  * @since 1.27
  28  */
  29 abstract class CentralIdLookup implements IDBAccessObject {
  30         // Audience options for accessors
  31         const AUDIENCE_PUBLIC = 1;
  32         const AUDIENCE_RAW = 2;
  33
  34         /** @var CentralIdLookup[] */
  35         private static $instances = [];
  36
  37         /** @var string */
  38         private $providerId;
  39
  40         /**
  41          * Fetch a CentralIdLookup
  42          * @param string|null $providerId Provider ID from $wgCentralIdLookupProviders
  43          * @return CentralIdLookup|null
  44          */
  45         public static function factory( $providerId = null ) {
  46                 global $wgCentralIdLookupProviders, $wgCentralIdLookupProvider;
  47
  48                 if ( $providerId === null ) {
  49                         $providerId = $wgCentralIdLookupProvider;
  50                 }
  51
  52                 if ( !array_key_exists( $providerId, self::$instances ) ) {
  53                         self::$instances[$providerId] = null;
  54
  55                         if ( isset( $wgCentralIdLookupProviders[$providerId] ) ) {
  56                                 $provider = ObjectFactory::getObjectFromSpec( $wgCentralIdLookupProviders[$providerId] );
  57                                 if ( $provider instanceof CentralIdLookup ) {
  58                                         $provider->providerId = $providerId;
  59                                         self::$instances[$providerId] = $provider;
  60                                 }
  61                         }
  62                 }
  63
  64                 return self::$instances[$providerId];
  65         }
  66
  67         /**
  68          * Reset internal cache for unit testing
  69          */
  70         public static function resetCache() {
  71                 if ( !defined( 'MW_PHPUNIT_TEST' ) ) {
  72                         throw new MWException( __METHOD__ . ' may only be called from unit tests!' );
  73                 }
  74                 self::$instances = [];
  75         }
  76
  77         final public function getProviderId() {
  78                 return $this->providerId;
  79         }
  80
  81         /**
  82          * Check that the "audience" parameter is valid
  83          * @param int|User $audience One of the audience constants, or a specific user
  84          * @return User|null User to check against, or null if no checks are needed
  85          * @throws InvalidArgumentException
  86          */
  87         protected function checkAudience( $audience ) {
  88                 if ( $audience instanceof User ) {
  89                         return $audience;
  90                 }
  91                 if ( $audience === self::AUDIENCE_PUBLIC ) {
  92                         return new User;
  93                 }
  94                 if ( $audience === self::AUDIENCE_RAW ) {
  95                         return null;
  96                 }
  97                 throw new InvalidArgumentException( 'Invalid audience' );
  98         }
  99
 100         /**
 101          * Check that a User is attached on the specified wiki.
 102          *
 103          * If unattached local accounts don't exist in your extension, this comes
 104          * down to a check whether the central account exists at all and that
 105          * $wikiId is using the same central database.
 106          *
 107          * @param User $user
 108          * @param string|null $wikiId Wiki to check attachment status. If null, check the current wiki.
 109          * @return bool
 110          */
 111         abstract public function isAttached( User $user, $wikiId = null );
 112
 113         /**
 114          * Given central user IDs, return the (local) user names
 115          * @note There's no requirement that the user names actually exist locally,
 116          *  or if they do that they're actually attached to the central account.
 117          * @param array $idToName Array with keys being central user IDs
 118          * @param int|User $audience One of the audience constants, or a specific user
 119          * @param int $flags IDBAccessObject read flags
 120          * @return array Copy of $idToName with values set to user names (or
 121          *  empty-string if the user exists but $audience lacks the rights needed
 122          *  to see it). IDs not corresponding to a user are unchanged.
 123          */
 124         abstract public function lookupCentralIds(
 125                 array $idToName, $audience = self::AUDIENCE_PUBLIC, $flags = self::READ_NORMAL
 126         );
 127
 128         /**
 129          * Given (local) user names, return the central IDs
 130          * @note There's no requirement that the user names actually exist locally,
 131          *  or if they do that they're actually attached to the central account.
 132          * @param array $nameToId Array with keys being canonicalized user names
 133          * @param int|User $audience One of the audience constants, or a specific user
 134          * @param int $flags IDBAccessObject read flags
 135          * @return array Copy of $nameToId with values set to central IDs.
 136          *  Names not corresponding to a user (or $audience lacks the rights needed
 137          *  to see it) are unchanged.
 138          */
 139         abstract public function lookupUserNames(
 140                 array $nameToId, $audience = self::AUDIENCE_PUBLIC, $flags = self::READ_NORMAL
 141         );
 142
 143         /**
 144          * Given a central user ID, return the (local) user name
 145          * @note There's no requirement that the user name actually exists locally,
 146          *  or if it does that it's actually attached to the central account.
 147          * @param int $id Central user ID
 148          * @param int|User $audience One of the audience constants, or a specific user
 149          * @param int $flags IDBAccessObject read flags
 150          * @return string|null User name, or empty string if $audience lacks the
 151          *  rights needed to see it, or null if $id doesn't correspond to a user
 152          */
 153         public function nameFromCentralId(
 154                 $id, $audience = self::AUDIENCE_PUBLIC, $flags = self::READ_NORMAL
 155         ) {
 156                 $idToName = $this->lookupCentralIds( [ $id => null ], $audience, $flags );
 157                 return $idToName[$id];
 158         }
 159
 160         /**
 161          * Given a (local) user name, return the central ID
 162          * @note There's no requirement that the user name actually exists locally,
 163          *  or if it does that it's actually attached to the central account.
 164          * @param string $name Canonicalized user name
 165          * @param int|User $audience One of the audience constants, or a specific user
 166          * @param int $flags IDBAccessObject read flags
 167          * @return int User ID; 0 if the name does not correspond to a user or
 168          *  $audience lacks the rights needed to see it.
 169          */
 170         public function centralIdFromName(
 171                 $name, $audience = self::AUDIENCE_PUBLIC, $flags = self::READ_NORMAL
 172         ) {
 173                 $nameToId = $this->lookupUserNames( [ $name => 0 ], $audience, $flags );
 174                 return $nameToId[$name];
 175         }
 176
 177         /**
 178          * Given a central user ID, return a local User object
 179          * @note Unlike nameFromCentralId(), this does guarantee that the local
 180          *  user exists and is attached to the central account.
 181          * @param int $id Central user ID
 182          * @param int|User $audience One of the audience constants, or a specific user
 183          * @param int $flags IDBAccessObject read flags
 184          * @return User|null Local user, or null if: $id doesn't correspond to a
 185          *  user, $audience lacks the rights needed to see the user, the user
 186          *  doesn't exist locally, or the user isn't locally attached.
 187          */
 188         public function localUserFromCentralId(
 189                 $id, $audience = self::AUDIENCE_PUBLIC, $flags = self::READ_NORMAL
 190         ) {
 191                 $name = $this->nameFromCentralId( $id, $audience, $flags );
 192                 if ( $name !== null && $name !== '' ) {
 193                         $user = User::newFromName( $name );
 194                         if ( $user && $user->getId() && $this->isAttached( $user ) ) {
 195                                 return $user;
 196                         }
 197                 }
 198                 return null;
 199         }
 200
 201         /**
 202          * Given a local User object, return the central ID
 203          * @note Unlike centralIdFromName(), this does guarantee that the local
 204          *  user is attached to the central account.
 205          * @param User $user Local user
 206          * @param int|User $audience One of the audience constants, or a specific user
 207          * @param int $flags IDBAccessObject read flags
 208          * @return int User ID; 0 if the local user does not correspond to a
 209          *  central user, $audience lacks the rights needed to see it, or the
 210          *  central user isn't locally attached.
 211          */
 212         public function centralIdFromLocalUser(
 213                 User $user, $audience = self::AUDIENCE_PUBLIC, $flags = self::READ_NORMAL
 214         ) {
 215                 return $this->isAttached( $user )
 216                         ? $this->centralIdFromName( $user->getName(), $audience, $flags )
 217                         : 0;
 218         }
 219
 220 }