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