Code Coverage |
||||||||||
Lines |
Functions and Methods |
Classes and Traits |
||||||||
| Total | |
62.00% |
31 / 50 |
|
64.29% |
9 / 14 |
CRAP | |
0.00% |
0 / 1 |
| CentralIdLookup | |
63.27% |
31 / 49 |
|
64.29% |
9 / 14 |
49.22 | |
0.00% |
0 / 1 |
| init | |
100.00% |
5 / 5 |
|
100.00% |
1 / 1 |
2 | |||
| getProviderId | |
100.00% |
1 / 1 |
|
100.00% |
1 / 1 |
1 | |||
| checkAudience | |
100.00% |
7 / 7 |
|
100.00% |
1 / 1 |
4 | |||
| isAttached | n/a |
0 / 0 |
n/a |
0 / 0 |
0 | |||||
| isOwned | |
0.00% |
0 / 1 |
|
0.00% |
0 / 1 |
2 | |||
| lookupCentralIds | n/a |
0 / 0 |
n/a |
0 / 0 |
0 | |||||
| lookupUserNames | |
100.00% |
2 / 2 |
|
100.00% |
1 / 1 |
1 | |||
| lookupOwnedUserNames | |
0.00% |
0 / 2 |
|
0.00% |
0 / 1 |
2 | |||
| lookupAttachedUserNames | |
100.00% |
2 / 2 |
|
100.00% |
1 / 1 |
1 | |||
| lookupUserNamesWithFilter | n/a |
0 / 0 |
n/a |
0 / 0 |
0 | |||||
| nameFromCentralId | |
100.00% |
2 / 2 |
|
100.00% |
1 / 1 |
1 | |||
| namesFromCentralIds | |
0.00% |
0 / 7 |
|
0.00% |
0 / 1 |
6 | |||
| centralIdFromName | |
100.00% |
2 / 2 |
|
100.00% |
1 / 1 |
1 | |||
| centralIdsFromNames | |
0.00% |
0 / 7 |
|
0.00% |
0 / 1 |
2 | |||
| localUserFromCentralId | |
100.00% |
7 / 7 |
|
100.00% |
1 / 1 |
5 | |||
| centralIdFromLocalUser | |
100.00% |
3 / 3 |
|
100.00% |
1 / 1 |
1 | |||
| getScope | |
0.00% |
0 / 1 |
|
0.00% |
0 / 1 |
2 | |||
| 1 | <?php |
| 2 | /** |
| 3 | * @license GPL-2.0-or-later |
| 4 | * @file |
| 5 | */ |
| 6 | |
| 7 | namespace MediaWiki\User\CentralId; |
| 8 | |
| 9 | use InvalidArgumentException; |
| 10 | use LogicException; |
| 11 | use MediaWiki\Permissions\Authority; |
| 12 | use MediaWiki\User\UserFactory; |
| 13 | use MediaWiki\User\UserIdentity; |
| 14 | use MediaWiki\User\UserIdentityLookup; |
| 15 | use MediaWiki\WikiMap\WikiMap; |
| 16 | use Wikimedia\Rdbms\IDBAccessObject; |
| 17 | |
| 18 | /** |
| 19 | * Find central user IDs associated with local user IDs, e.g. across a wiki farm. |
| 20 | * |
| 21 | * Default implementation is MediaWiki\User\CentralId\LocalIdLookup. |
| 22 | * |
| 23 | * @since 1.27 |
| 24 | * @stable to extend |
| 25 | * @ingroup User |
| 26 | */ |
| 27 | abstract class CentralIdLookup { |
| 28 | // Audience options for accessors |
| 29 | public const AUDIENCE_PUBLIC = 1; |
| 30 | public const AUDIENCE_RAW = 2; |
| 31 | |
| 32 | public const FILTER_NONE = 'none'; |
| 33 | public const FILTER_ATTACHED = 'attached'; |
| 34 | public const FILTER_OWNED = 'owned'; |
| 35 | |
| 36 | /** @var string */ |
| 37 | private $providerId; |
| 38 | |
| 39 | private UserIdentityLookup $userIdentityLookup; |
| 40 | private UserFactory $userFactory; |
| 41 | |
| 42 | /** |
| 43 | * Initialize the provider. |
| 44 | * |
| 45 | * @internal |
| 46 | */ |
| 47 | public function init( |
| 48 | string $providerId, |
| 49 | UserIdentityLookup $userIdentityLookup, |
| 50 | UserFactory $userFactory |
| 51 | ) { |
| 52 | if ( $this->providerId !== null ) { |
| 53 | throw new LogicException( "CentralIdProvider $providerId already initialized" ); |
| 54 | } |
| 55 | $this->providerId = $providerId; |
| 56 | $this->userIdentityLookup = $userIdentityLookup; |
| 57 | $this->userFactory = $userFactory; |
| 58 | } |
| 59 | |
| 60 | public function getProviderId(): string { |
| 61 | return $this->providerId; |
| 62 | } |
| 63 | |
| 64 | /** |
| 65 | * Check that the "audience" parameter is valid |
| 66 | * @param int|Authority $audience One of the audience constants, or a specific authority |
| 67 | * @return Authority|null authority to check against, or null if no checks are needed |
| 68 | * @throws InvalidArgumentException |
| 69 | */ |
| 70 | protected function checkAudience( $audience ): ?Authority { |
| 71 | if ( $audience instanceof Authority ) { |
| 72 | return $audience; |
| 73 | } |
| 74 | if ( $audience === self::AUDIENCE_PUBLIC ) { |
| 75 | // TODO: when available, inject AuthorityFactory |
| 76 | // via init and use it to create anon authority |
| 77 | return $this->userFactory->newAnonymous(); |
| 78 | } |
| 79 | if ( $audience === self::AUDIENCE_RAW ) { |
| 80 | return null; |
| 81 | } |
| 82 | throw new InvalidArgumentException( 'Invalid audience' ); |
| 83 | } |
| 84 | |
| 85 | /** |
| 86 | * Check that a user is attached on the specified wiki. |
| 87 | * |
| 88 | * If unattached local accounts don't exist in your extension, this comes |
| 89 | * down to a check whether the central account exists at all and that |
| 90 | * $wikiId is using the same central database. |
| 91 | * |
| 92 | * @param UserIdentity $user |
| 93 | * @param string|false $wikiId Wiki to check attachment status. If false, check the current wiki. |
| 94 | * @return bool |
| 95 | */ |
| 96 | abstract public function isAttached( UserIdentity $user, $wikiId = UserIdentity::LOCAL ): bool; |
| 97 | |
| 98 | /** |
| 99 | * Check that a username is owned by the central user on the specified wiki. |
| 100 | * |
| 101 | * This should return true if the local account exists and is attached (see isAttached()), |
| 102 | * or if it does not exist but is reserved for the central user (it's guaranteed that |
| 103 | * if it's ever created, then it will be attached to the central user). |
| 104 | * |
| 105 | * @since 1.43 |
| 106 | * @stable to override |
| 107 | * @param UserIdentity $user |
| 108 | * @param string|false $wikiId Wiki to check attachment status. If false, check the current wiki. |
| 109 | * @return bool |
| 110 | */ |
| 111 | public function isOwned( UserIdentity $user, $wikiId = UserIdentity::LOCAL ): bool { |
| 112 | return $this->isAttached( $user, $wikiId ); |
| 113 | } |
| 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|Authority $audience One of the audience constants, or a specific authority |
| 121 | * @param int $flags IDBAccessObject read flags |
| 122 | * @return string[] 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 = IDBAccessObject::READ_NORMAL |
| 128 | ): array; |
| 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|Authority $audience One of the audience constants, or a specific authority |
| 136 | * @param int $flags IDBAccessObject read flags |
| 137 | * @return int[] 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 | public function lookupUserNames( |
| 142 | array $nameToId, $audience = self::AUDIENCE_PUBLIC, $flags = IDBAccessObject::READ_NORMAL |
| 143 | ): array { |
| 144 | return $this->lookupUserNamesWithFilter( $nameToId, self::FILTER_NONE, |
| 145 | $audience, $flags ); |
| 146 | } |
| 147 | |
| 148 | /** |
| 149 | * Given user names on the wiki specified by $wikiId, return the central |
| 150 | * IDs, but only include IDs for local users owned by the central user, |
| 151 | * i.e. isOwned() would be true. |
| 152 | * |
| 153 | * @since 1.44 |
| 154 | * |
| 155 | * @param array $nameToId Array with keys being canonicalized user names |
| 156 | * @param int|Authority $audience One of the audience constants, or a specific authority |
| 157 | * @param int $flags IDBAccessObject read flags |
| 158 | * @param string|false $wikiId Wiki to check attachment status. If false, check the current |
| 159 | * wiki. |
| 160 | * @return int[] Copy of $nameToId with values set to central IDs. |
| 161 | * Names not owned by the central user are unchanged. |
| 162 | */ |
| 163 | public function lookupOwnedUserNames( |
| 164 | array $nameToId, |
| 165 | $audience = self::AUDIENCE_PUBLIC, |
| 166 | $flags = IDBAccessObject::READ_NORMAL, |
| 167 | $wikiId = UserIdentity::LOCAL |
| 168 | ) { |
| 169 | return $this->lookupUserNamesWithFilter( $nameToId, self::FILTER_OWNED, |
| 170 | $audience, $flags, $wikiId ); |
| 171 | } |
| 172 | |
| 173 | /** |
| 174 | * Given user names on the wiki specified by $wikiId, return the central |
| 175 | * IDs, but only include IDs for local users attached to the central user, |
| 176 | * i.e. isAttached() would be true. |
| 177 | * |
| 178 | * @since 1.44 |
| 179 | * |
| 180 | * @param array $nameToId Array with keys being canonicalized user names |
| 181 | * @param int|Authority $audience One of the audience constants, or a specific authority |
| 182 | * @param int $flags IDBAccessObject read flags |
| 183 | * @param string|false $wikiId Wiki to check attachment status. If false, check the current |
| 184 | * wiki. |
| 185 | * @return int[] Copy of $nameToId with values set to central IDs. |
| 186 | * Names not attached to the central user are unchanged. |
| 187 | */ |
| 188 | public function lookupAttachedUserNames( |
| 189 | array $nameToId, |
| 190 | $audience = self::AUDIENCE_PUBLIC, |
| 191 | $flags = IDBAccessObject::READ_NORMAL, |
| 192 | $wikiId = UserIdentity::LOCAL |
| 193 | ) { |
| 194 | return $this->lookupUserNamesWithFilter( $nameToId, self::FILTER_ATTACHED, |
| 195 | $audience, $flags, $wikiId ); |
| 196 | } |
| 197 | |
| 198 | /** |
| 199 | * Given user names on the wiki specified by $wikiId, return the central |
| 200 | * IDs. If $filter is not FILTER_NONE, filter the users by owned or |
| 201 | * attached status. |
| 202 | * |
| 203 | * @since 1.44 |
| 204 | * |
| 205 | * @param array $nameToId Array with keys being canonicalized user names |
| 206 | * @param string $filter One of: |
| 207 | * - self::FILTER_NONE: Get all users with the specified names |
| 208 | * - self::FILTER_ATTACHED: Only get IDs for attached users |
| 209 | * - self::FILTER_OWNED: Only get IDs for owned users |
| 210 | * @param int|Authority $audience One of the audience constants, or a specific authority |
| 211 | * @param int $flags IDBAccessObject read flags |
| 212 | * @param string|false $wikiId Wiki to check attachment status. If false, check the current |
| 213 | * wiki. |
| 214 | * @return int[] Copy of $nameToId with values set to central IDs. |
| 215 | * Names not owned by the central user are unchanged. |
| 216 | */ |
| 217 | abstract protected function lookupUserNamesWithFilter( |
| 218 | array $nameToId, |
| 219 | $filter, |
| 220 | $audience = self::AUDIENCE_PUBLIC, |
| 221 | $flags = IDBAccessObject::READ_NORMAL, |
| 222 | $wikiId = UserIdentity::LOCAL |
| 223 | ): array; |
| 224 | |
| 225 | /** |
| 226 | * Given a central user ID, return the (local) user name |
| 227 | * @note There's no requirement that the user name actually exists locally, |
| 228 | * or if it does that it's actually attached to the central account. |
| 229 | * @param int $id Central user ID |
| 230 | * @param int|Authority $audience One of the audience constants, or a specific authority |
| 231 | * @param int $flags IDBAccessObject read flags |
| 232 | * @return string|null user name, or empty string if $audience lacks the |
| 233 | * rights needed to see it, or null if $id doesn't correspond to a user |
| 234 | */ |
| 235 | public function nameFromCentralId( |
| 236 | $id, $audience = self::AUDIENCE_PUBLIC, $flags = IDBAccessObject::READ_NORMAL |
| 237 | ): ?string { |
| 238 | $idToName = $this->lookupCentralIds( [ $id => null ], $audience, $flags ); |
| 239 | return $idToName[$id]; |
| 240 | } |
| 241 | |
| 242 | /** |
| 243 | * Given a an array of central user IDs, return the (local) user names. |
| 244 | * @param int[] $ids Central user IDs |
| 245 | * @param int|Authority $audience One of the audience constants, or a specific authority |
| 246 | * @param int $flags IDBAccessObject read flags |
| 247 | * @return string[] user names |
| 248 | * @since 1.30 |
| 249 | */ |
| 250 | public function namesFromCentralIds( |
| 251 | array $ids, $audience = self::AUDIENCE_PUBLIC, $flags = IDBAccessObject::READ_NORMAL |
| 252 | ): array { |
| 253 | $idToName = array_fill_keys( $ids, false ); |
| 254 | $names = $this->lookupCentralIds( $idToName, $audience, $flags ); |
| 255 | $names = array_unique( $names ); |
| 256 | $names = array_filter( $names, static function ( $name ) { |
| 257 | return $name !== false && $name !== ''; |
| 258 | } ); |
| 259 | |
| 260 | return array_values( $names ); |
| 261 | } |
| 262 | |
| 263 | /** |
| 264 | * Given a (local) user name, return the central ID |
| 265 | * @note There's no requirement that the user name actually exists locally, |
| 266 | * or if it does that it's actually attached to the central account. |
| 267 | * @param string $name Canonicalized user name |
| 268 | * @param int|Authority $audience One of the audience constants, or a specific authority |
| 269 | * @param int $flags IDBAccessObject read flags |
| 270 | * @return int user ID; 0 if the name does not correspond to a user or |
| 271 | * $audience lacks the rights needed to see it. |
| 272 | */ |
| 273 | public function centralIdFromName( |
| 274 | $name, $audience = self::AUDIENCE_PUBLIC, $flags = IDBAccessObject::READ_NORMAL |
| 275 | ): int { |
| 276 | $nameToId = $this->lookupUserNames( [ $name => 0 ], $audience, $flags ); |
| 277 | return $nameToId[$name]; |
| 278 | } |
| 279 | |
| 280 | /** |
| 281 | * Given an array of (local) user names, return the central IDs. |
| 282 | * @param string[] $names Canonicalized user names |
| 283 | * @param int|Authority $audience One of the audience constants, or a specific authority |
| 284 | * @param int $flags IDBAccessObject read flags |
| 285 | * @return int[] user IDs |
| 286 | * @since 1.30 |
| 287 | */ |
| 288 | public function centralIdsFromNames( |
| 289 | array $names, $audience = self::AUDIENCE_PUBLIC, $flags = IDBAccessObject::READ_NORMAL |
| 290 | ): array { |
| 291 | $nameToId = array_fill_keys( $names, false ); |
| 292 | $ids = $this->lookupUserNames( $nameToId, $audience, $flags ); |
| 293 | $ids = array_unique( $ids ); |
| 294 | $ids = array_filter( $ids, static function ( $id ) { |
| 295 | return $id !== false; |
| 296 | } ); |
| 297 | |
| 298 | return array_values( $ids ); |
| 299 | } |
| 300 | |
| 301 | /** |
| 302 | * Given a central user ID, return a local user object |
| 303 | * @note Unlike nameFromCentralId(), this does guarantee that the local |
| 304 | * user exists and is attached to the central account. |
| 305 | * @stable to override |
| 306 | * @param int $id Central user ID |
| 307 | * @param int|Authority $audience One of the audience constants, or a specific authority |
| 308 | * @param int $flags IDBAccessObject read flags |
| 309 | * @return UserIdentity|null Local user, or null if: $id doesn't correspond to a |
| 310 | * user, $audience lacks the rights needed to see the user, the user |
| 311 | * doesn't exist locally, or the user isn't locally attached. |
| 312 | */ |
| 313 | public function localUserFromCentralId( |
| 314 | $id, $audience = self::AUDIENCE_PUBLIC, $flags = IDBAccessObject::READ_NORMAL |
| 315 | ): ?UserIdentity { |
| 316 | $name = $this->nameFromCentralId( $id, $audience, $flags ); |
| 317 | if ( !$name ) { |
| 318 | return null; |
| 319 | } |
| 320 | $user = $this->userIdentityLookup->getUserIdentityByName( $name ); |
| 321 | if ( $user && $user->isRegistered() && $this->isAttached( $user ) ) { |
| 322 | return $user; |
| 323 | } |
| 324 | return null; |
| 325 | } |
| 326 | |
| 327 | /** |
| 328 | * Given a local UserIdentity object, return the central ID |
| 329 | * @stable to override |
| 330 | * @note Unlike centralIdFromName(), this does guarantee that the local |
| 331 | * user is attached to the central account. |
| 332 | * @param UserIdentity $user Local user |
| 333 | * @param int|Authority $audience One of the audience constants, or a specific authority |
| 334 | * @param int $flags IDBAccessObject read flags |
| 335 | * @return int user ID; 0 if the local user does not correspond to a |
| 336 | * central user, $audience lacks the rights needed to see it, or the |
| 337 | * central user isn't locally attached. |
| 338 | */ |
| 339 | public function centralIdFromLocalUser( |
| 340 | UserIdentity $user, $audience = self::AUDIENCE_PUBLIC, $flags = IDBAccessObject::READ_NORMAL |
| 341 | ): int { |
| 342 | $name = $user->getName(); |
| 343 | $nameToId = $this->lookupAttachedUserNames( [ $name => 0 ], $audience, $flags ); |
| 344 | return $nameToId[$name]; |
| 345 | } |
| 346 | |
| 347 | /** |
| 348 | * Return a scope that can be used to differentiate the central IDs returned by this object |
| 349 | * from central IDs returned by different CentralIdLookup implementations and/or on |
| 350 | * different wikis of the same farm. |
| 351 | * |
| 352 | * The scope will take the form of `<provider-id>:<instance-id>` where `<provider-id>` is the |
| 353 | * CentralIdLookup provider's ID (as in {@link ::getProviderId()}), and `<instance-id>` is used |
| 354 | * to differentiate between multiple instances of the same provider (e.g. could be a wiki ID |
| 355 | * for farms where each wiki has its own userbase); it is an arbitrary string (possibly empty) |
| 356 | * except it can't contain any more `:` characters. |
| 357 | * |
| 358 | * Most subclasses should override the default implementation. |
| 359 | * |
| 360 | * @stable to override |
| 361 | * @return string |
| 362 | * @since 1.45 |
| 363 | */ |
| 364 | public function getScope(): string { |
| 365 | return $this->getProviderId() . ':' . strtr( WikiMap::getCurrentWikiId(), [ ':' => '-' ] ); |
| 366 | } |
| 367 | |
| 368 | } |
| 369 | |
| 370 | /** @deprecated class alias since 1.41 */ |
| 371 | class_alias( CentralIdLookup::class, 'CentralIdLookup' ); |