Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
62.00% covered (warning)
62.00%
31 / 50
64.29% covered (warning)
64.29%
9 / 14
 CRAP
0.00% covered (danger)
0.00%
0 / 1
CentralIdLookup
63.27% covered (warning)
63.27%
31 / 49
64.29% covered (warning)
64.29%
9 / 14
 49.22
0.00% covered (danger)
0.00%
0 / 1
 init
100.00% covered (success)
100.00%
5 / 5
100.00% covered (success)
100.00%
1 / 1
 2
 getProviderId
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
 1
 checkAudience
100.00% covered (success)
100.00%
7 / 7
100.00% covered (success)
100.00%
1 / 1
 4
 isAttached
n/a
0 / 0
n/a
0 / 0
 0
 isOwned
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 lookupCentralIds
n/a
0 / 0
n/a
0 / 0
 0
 lookupUserNames
100.00% covered (success)
100.00%
2 / 2
100.00% covered (success)
100.00%
1 / 1
 1
 lookupOwnedUserNames
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
 2
 lookupAttachedUserNames
100.00% covered (success)
100.00%
2 / 2
100.00% covered (success)
100.00%
1 / 1
 1
 lookupUserNamesWithFilter
n/a
0 / 0
n/a
0 / 0
 0
 nameFromCentralId
100.00% covered (success)
100.00%
2 / 2
100.00% covered (success)
100.00%
1 / 1
 1
 namesFromCentralIds
0.00% covered (danger)
0.00%
0 / 7
0.00% covered (danger)
0.00%
0 / 1
 6
 centralIdFromName
100.00% covered (success)
100.00%
2 / 2
100.00% covered (success)
100.00%
1 / 1
 1
 centralIdsFromNames
0.00% covered (danger)
0.00%
0 / 7
0.00% covered (danger)
0.00%
0 / 1
 2
 localUserFromCentralId
100.00% covered (success)
100.00%
7 / 7
100.00% covered (success)
100.00%
1 / 1
 5
 centralIdFromLocalUser
100.00% covered (success)
100.00%
3 / 3
100.00% covered (success)
100.00%
1 / 1
 1
 getScope
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
1<?php
2/**
3 * @license GPL-2.0-or-later
4 * @file
5 */
6
7namespace MediaWiki\User\CentralId;
8
9use InvalidArgumentException;
10use LogicException;
11use MediaWiki\Permissions\Authority;
12use MediaWiki\User\UserFactory;
13use MediaWiki\User\UserIdentity;
14use MediaWiki\User\UserIdentityLookup;
15use MediaWiki\WikiMap\WikiMap;
16use 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 */
27abstract 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     *
118     * 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     *
121     * @param array $idToName Array with keys being central user IDs
122     * @param int|Authority $audience One of the audience constants, or a specific authority
123     * @param int $flags IDBAccessObject read flags
124     * @return string[] Copy of $idToName with values set to user names (or
125     *  empty-string if the user exists but $audience lacks the rights needed
126     *  to see it). IDs not corresponding to a user are unchanged.
127     */
128    abstract public function lookupCentralIds(
129        array $idToName, $audience = self::AUDIENCE_PUBLIC, $flags = IDBAccessObject::READ_NORMAL
130    ): array;
131
132    /**
133     * Given (local) user names, return the central IDs
134     *
135     * There's no requirement that the user names actually exist locally,
136     * or if they do that they're actually attached to the central account.
137     *
138     * @param array $nameToId Array with keys being canonicalized user names
139     * @param int|Authority $audience One of the audience constants, or a specific authority
140     * @param int $flags IDBAccessObject read flags
141     * @return int[] Copy of $nameToId with values set to central IDs.
142     *  Names not corresponding to a user (or $audience lacks the rights needed
143     *  to see it) are unchanged.
144     */
145    public function lookupUserNames(
146        array $nameToId, $audience = self::AUDIENCE_PUBLIC, $flags = IDBAccessObject::READ_NORMAL
147    ): array {
148        return $this->lookupUserNamesWithFilter( $nameToId, self::FILTER_NONE,
149            $audience, $flags );
150    }
151
152    /**
153     * Given user names on the wiki specified by $wikiId, return the central
154     * IDs, but only include IDs for local users owned by the central user,
155     * i.e. isOwned() would be true.
156     *
157     * @since 1.44
158     *
159     * @param array $nameToId Array with keys being canonicalized user names
160     * @param int|Authority $audience One of the audience constants, or a specific authority
161     * @param int $flags IDBAccessObject read flags
162     * @param string|false $wikiId Wiki to check attachment status. If false, check the current
163     *   wiki.
164     * @return int[] Copy of $nameToId with values set to central IDs.
165     *   Names not owned by the central user are unchanged.
166     */
167    public function lookupOwnedUserNames(
168        array $nameToId,
169        $audience = self::AUDIENCE_PUBLIC,
170        $flags = IDBAccessObject::READ_NORMAL,
171        $wikiId = UserIdentity::LOCAL
172    ) {
173        return $this->lookupUserNamesWithFilter( $nameToId, self::FILTER_OWNED,
174            $audience, $flags, $wikiId );
175    }
176
177    /**
178     * Given user names on the wiki specified by $wikiId, return the central
179     * IDs, but only include IDs for local users attached to the central user,
180     * i.e. isAttached() would be true.
181     *
182     * @since 1.44
183     *
184     * @param array $nameToId Array with keys being canonicalized user names
185     * @param int|Authority $audience One of the audience constants, or a specific authority
186     * @param int $flags IDBAccessObject read flags
187     * @param string|false $wikiId Wiki to check attachment status. If false, check the current
188     *   wiki.
189     * @return int[] Copy of $nameToId with values set to central IDs.
190     *   Names not attached to the central user are unchanged.
191     */
192    public function lookupAttachedUserNames(
193        array $nameToId,
194        $audience = self::AUDIENCE_PUBLIC,
195        $flags = IDBAccessObject::READ_NORMAL,
196        $wikiId = UserIdentity::LOCAL
197    ) {
198        return $this->lookupUserNamesWithFilter( $nameToId, self::FILTER_ATTACHED,
199            $audience, $flags, $wikiId );
200    }
201
202    /**
203     * Given user names on the wiki specified by $wikiId, return the central
204     * IDs. If $filter is not FILTER_NONE, filter the users by owned or
205     * attached status.
206     *
207     * @since 1.44
208     *
209     * @param array $nameToId Array with keys being canonicalized user names
210     * @param string $filter One of:
211     *   - self::FILTER_NONE: Get all users with the specified names
212     *   - self::FILTER_ATTACHED: Only get IDs for attached users
213     *   - self::FILTER_OWNED: Only get IDs for owned users
214     * @param int|Authority $audience One of the audience constants, or a specific authority
215     * @param int $flags IDBAccessObject read flags
216     * @param string|false $wikiId Wiki to check attachment status. If false, check the current
217     *   wiki.
218     * @return int[] Copy of $nameToId with values set to central IDs.
219     *   Names not owned by the central user are unchanged.
220     */
221    abstract protected function lookupUserNamesWithFilter(
222        array $nameToId,
223        $filter,
224        $audience = self::AUDIENCE_PUBLIC,
225        $flags = IDBAccessObject::READ_NORMAL,
226        $wikiId = UserIdentity::LOCAL
227    ): array;
228
229    /**
230     * Given a central user ID, return the (local) user name
231     *
232     * There's no requirement that the user name actually exists locally,
233     * or if it does that it's actually attached to the central account.
234     *
235     * @param int $id Central user ID
236     * @param int|Authority $audience One of the audience constants, or a specific authority
237     * @param int $flags IDBAccessObject read flags
238     * @return string|null user name, or empty string if $audience lacks the
239     *  rights needed to see it, or null if $id doesn't correspond to a user
240     */
241    public function nameFromCentralId(
242        $id, $audience = self::AUDIENCE_PUBLIC, $flags = IDBAccessObject::READ_NORMAL
243    ): ?string {
244        $idToName = $this->lookupCentralIds( [ $id => null ], $audience, $flags );
245        return $idToName[$id];
246    }
247
248    /**
249     * Given a an array of central user IDs, return the (local) user names.
250     * @param int[] $ids Central user IDs
251     * @param int|Authority $audience One of the audience constants, or a specific authority
252     * @param int $flags IDBAccessObject read flags
253     * @return string[] user names
254     * @since 1.30
255     */
256    public function namesFromCentralIds(
257        array $ids, $audience = self::AUDIENCE_PUBLIC, $flags = IDBAccessObject::READ_NORMAL
258    ): array {
259        $idToName = array_fill_keys( $ids, false );
260        $names = $this->lookupCentralIds( $idToName, $audience, $flags );
261        $names = array_unique( $names );
262        $names = array_filter( $names, static function ( $name ) {
263            return $name !== false && $name !== '';
264        } );
265
266        return array_values( $names );
267    }
268
269    /**
270     * Given a (local) user name, return the central ID
271     *
272     * There's no requirement that the user name actually exists locally,
273     * or if it does that it's actually attached to the central account.
274     *
275     * @param string $name Canonicalized user name
276     * @param int|Authority $audience One of the audience constants, or a specific authority
277     * @param int $flags IDBAccessObject read flags
278     * @return int user ID; 0 if the name does not correspond to a user or
279     *  $audience lacks the rights needed to see it.
280     */
281    public function centralIdFromName(
282        $name, $audience = self::AUDIENCE_PUBLIC, $flags = IDBAccessObject::READ_NORMAL
283    ): int {
284        $nameToId = $this->lookupUserNames( [ $name => 0 ], $audience, $flags );
285        return $nameToId[$name];
286    }
287
288    /**
289     * Given an array of (local) user names, return the central IDs.
290     * @param string[] $names Canonicalized user names
291     * @param int|Authority $audience One of the audience constants, or a specific authority
292     * @param int $flags IDBAccessObject read flags
293     * @return int[] user IDs
294     * @since 1.30
295     */
296    public function centralIdsFromNames(
297        array $names, $audience = self::AUDIENCE_PUBLIC, $flags = IDBAccessObject::READ_NORMAL
298    ): array {
299        $nameToId = array_fill_keys( $names, false );
300        $ids = $this->lookupUserNames( $nameToId, $audience, $flags );
301        $ids = array_unique( $ids );
302        $ids = array_filter( $ids, static function ( $id ) {
303            return $id !== false;
304        } );
305
306        return array_values( $ids );
307    }
308
309    /**
310     * Given a central user ID, return a local user object
311     *
312     * Unlike nameFromCentralId(), this does guarantee that the local
313     * user exists and is attached to the central account.
314     *
315     * @stable to override
316     * @param int $id Central user ID
317     * @param int|Authority $audience One of the audience constants, or a specific authority
318     * @param int $flags IDBAccessObject read flags
319     * @return UserIdentity|null Local user, or null if: $id doesn't correspond to a
320     *  user, $audience lacks the rights needed to see the user, the user
321     *  doesn't exist locally, or the user isn't locally attached.
322     */
323    public function localUserFromCentralId(
324        $id, $audience = self::AUDIENCE_PUBLIC, $flags = IDBAccessObject::READ_NORMAL
325    ): ?UserIdentity {
326        $name = $this->nameFromCentralId( $id, $audience, $flags );
327        if ( !$name ) {
328            return null;
329        }
330        $user = $this->userIdentityLookup->getUserIdentityByName( $name );
331        if ( $user && $user->isRegistered() && $this->isAttached( $user ) ) {
332            return $user;
333        }
334        return null;
335    }
336
337    /**
338     * Given a local UserIdentity object, return the central ID
339     *
340     * Unlike centralIdFromName(), this does guarantee that the local
341     * user is attached to the central account.
342     *
343     * @stable to override
344     * @param UserIdentity $user Local user
345     * @param int|Authority $audience One of the audience constants, or a specific authority
346     * @param int $flags IDBAccessObject read flags
347     * @return int user ID; 0 if the local user does not correspond to a
348     *  central user, $audience lacks the rights needed to see it, or the
349     *  central user isn't locally attached.
350     */
351    public function centralIdFromLocalUser(
352        UserIdentity $user, $audience = self::AUDIENCE_PUBLIC, $flags = IDBAccessObject::READ_NORMAL
353    ): int {
354        $name = $user->getName();
355        $nameToId = $this->lookupAttachedUserNames( [ $name => 0 ], $audience, $flags );
356        return $nameToId[$name];
357    }
358
359    /**
360     * Return a scope that can be used to differentiate the central IDs returned by this object
361     * from central IDs returned by different CentralIdLookup implementations and/or on
362     * different wikis of the same farm.
363     *
364     * The scope will take the form of `<provider-id>:<instance-id>` where `<provider-id>` is the
365     * CentralIdLookup provider's ID (as in {@link ::getProviderId()}), and `<instance-id>` is used
366     * to differentiate between multiple instances of the same provider (e.g. could be a wiki ID
367     * for farms where each wiki has its own userbase); it is an arbitrary string (possibly empty)
368     * except it can't contain any more `:` characters.
369     *
370     * Most subclasses should override the default implementation.
371     *
372     * @stable to override
373     * @return string
374     * @since 1.45
375     */
376    public function getScope(): string {
377        return $this->getProviderId() . ':' . strtr( WikiMap::getCurrentWikiId(), [ ':' => '-' ] );
378    }
379
380}
381
382/** @deprecated class alias since 1.41 */
383class_alias( CentralIdLookup::class, 'CentralIdLookup' );