Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
56.36% covered (warning)
56.36%
31 / 55
64.29% covered (warning)
64.29%
9 / 14
 CRAP
0.00% covered (danger)
0.00%
0 / 1
CentralIdLookup
57.41% covered (warning)
57.41%
31 / 54
64.29% covered (warning)
64.29%
9 / 14
 68.51
0.00% covered (danger)
0.00%
0 / 1
 factory
0.00% covered (danger)
0.00%
0 / 6
0.00% covered (danger)
0.00%
0 / 1
 6
 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
1<?php
2/**
3 * This program is free software; you can redistribute it and/or modify
4 * it under the terms of the GNU General Public License as published by
5 * the Free Software Foundation; either version 2 of the License, or
6 * (at your option) any later version.
7 *
8 * This program is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 * GNU General Public License for more details.
12 *
13 * You should have received a copy of the GNU General Public License along
14 * with this program; if not, write to the Free Software Foundation, Inc.,
15 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
16 * http://www.gnu.org/copyleft/gpl.html
17 *
18 * @file
19 */
20
21namespace MediaWiki\User\CentralId;
22
23use InvalidArgumentException;
24use LogicException;
25use MediaWiki\MediaWikiServices;
26use MediaWiki\Permissions\Authority;
27use MediaWiki\User\UserFactory;
28use MediaWiki\User\UserIdentity;
29use MediaWiki\User\UserIdentityLookup;
30use Throwable;
31use Wikimedia\Rdbms\IDBAccessObject;
32
33/**
34 * Find central user IDs associated with local user IDs, e.g. across a wiki farm.
35 *
36 * Default implementation is MediaWiki\User\CentralId\LocalIdLookup.
37 *
38 * @since 1.27
39 * @stable to extend
40 * @ingroup User
41 */
42abstract class CentralIdLookup {
43    // Audience options for accessors
44    public const AUDIENCE_PUBLIC = 1;
45    public const AUDIENCE_RAW = 2;
46
47    public const FILTER_NONE = 'none';
48    public const FILTER_ATTACHED = 'attached';
49    public const FILTER_OWNED = 'owned';
50
51    /** @var string */
52    private $providerId;
53
54    private UserIdentityLookup $userIdentityLookup;
55    private UserFactory $userFactory;
56
57    /**
58     * Fetch a CentralIdLookup
59     * @deprecated since 1.37 Use MediaWikiServices to obtain an instance.
60     * @param string|null $providerId Provider ID from $wgCentralIdLookupProviders
61     * @return CentralIdLookup|null
62     */
63    public static function factory( $providerId = null ) {
64        wfDeprecated( __METHOD__, '1.37' );
65        try {
66            return MediaWikiServices::getInstance()
67                ->getCentralIdLookupFactory()
68                ->getLookup( $providerId );
69        } catch ( Throwable $unused ) {
70            return null;
71        }
72    }
73
74    /**
75     * Initialize the provider.
76     *
77     * @internal
78     */
79    public function init(
80        string $providerId,
81        UserIdentityLookup $userIdentityLookup,
82        UserFactory $userFactory
83    ) {
84        if ( $this->providerId !== null ) {
85            throw new LogicException( "CentralIdProvider $providerId already initialized" );
86        }
87        $this->providerId = $providerId;
88        $this->userIdentityLookup = $userIdentityLookup;
89        $this->userFactory = $userFactory;
90    }
91
92    public function getProviderId(): string {
93        return $this->providerId;
94    }
95
96    /**
97     * Check that the "audience" parameter is valid
98     * @param int|Authority $audience One of the audience constants, or a specific authority
99     * @return Authority|null authority to check against, or null if no checks are needed
100     * @throws InvalidArgumentException
101     */
102    protected function checkAudience( $audience ): ?Authority {
103        if ( $audience instanceof Authority ) {
104            return $audience;
105        }
106        if ( $audience === self::AUDIENCE_PUBLIC ) {
107            // TODO: when available, inject AuthorityFactory
108            // via init and use it to create anon authority
109            return $this->userFactory->newAnonymous();
110        }
111        if ( $audience === self::AUDIENCE_RAW ) {
112            return null;
113        }
114        throw new InvalidArgumentException( 'Invalid audience' );
115    }
116
117    /**
118     * Check that a user is attached on the specified wiki.
119     *
120     * If unattached local accounts don't exist in your extension, this comes
121     * down to a check whether the central account exists at all and that
122     * $wikiId is using the same central database.
123     *
124     * @param UserIdentity $user
125     * @param string|false $wikiId Wiki to check attachment status. If false, check the current wiki.
126     * @return bool
127     */
128    abstract public function isAttached( UserIdentity $user, $wikiId = UserIdentity::LOCAL ): bool;
129
130    /**
131     * Check that a username is owned by the central user on the specified wiki.
132     *
133     * This should return true if the local account exists and is attached (see isAttached()),
134     * or if it does not exist but is reserved for the central user (it's guaranteed that
135     * if it's ever created, then it will be attached to the central user).
136     *
137     * @since 1.43
138     * @stable to override
139     * @param UserIdentity $user
140     * @param string|false $wikiId Wiki to check attachment status. If false, check the current wiki.
141     * @return bool
142     */
143    public function isOwned( UserIdentity $user, $wikiId = UserIdentity::LOCAL ): bool {
144        return $this->isAttached( $user, $wikiId );
145    }
146
147    /**
148     * Given central user IDs, return the (local) user names
149     * @note There's no requirement that the user names actually exist locally,
150     *  or if they do that they're actually attached to the central account.
151     * @param array $idToName Array with keys being central user IDs
152     * @param int|Authority $audience One of the audience constants, or a specific authority
153     * @param int $flags IDBAccessObject read flags
154     * @return string[] Copy of $idToName with values set to user names (or
155     *  empty-string if the user exists but $audience lacks the rights needed
156     *  to see it). IDs not corresponding to a user are unchanged.
157     */
158    abstract public function lookupCentralIds(
159        array $idToName, $audience = self::AUDIENCE_PUBLIC, $flags = IDBAccessObject::READ_NORMAL
160    ): array;
161
162    /**
163     * Given (local) user names, return the central IDs
164     * @note There's no requirement that the user names actually exist locally,
165     *  or if they do that they're actually attached to the central account.
166     * @param array $nameToId Array with keys being canonicalized user names
167     * @param int|Authority $audience One of the audience constants, or a specific authority
168     * @param int $flags IDBAccessObject read flags
169     * @return int[] Copy of $nameToId with values set to central IDs.
170     *  Names not corresponding to a user (or $audience lacks the rights needed
171     *  to see it) are unchanged.
172     */
173    public function lookupUserNames(
174        array $nameToId, $audience = self::AUDIENCE_PUBLIC, $flags = IDBAccessObject::READ_NORMAL
175    ): array {
176        return $this->lookupUserNamesWithFilter( $nameToId, self::FILTER_NONE,
177            $audience, $flags );
178    }
179
180    /**
181     * Given user names on the wiki specified by $wikiId, return the central
182     * IDs, but only include IDs for local users owned by the central user,
183     * i.e. isOwned() would be true.
184     *
185     * @since 1.44
186     *
187     * @param array $nameToId Array with keys being canonicalized user names
188     * @param int|Authority $audience One of the audience constants, or a specific authority
189     * @param int $flags IDBAccessObject read flags
190     * @param string|false $wikiId Wiki to check attachment status. If false, check the current
191     *   wiki.
192     * @return int[] Copy of $nameToId with values set to central IDs.
193     *   Names not owned by the central user are unchanged.
194     */
195    public function lookupOwnedUserNames(
196        array $nameToId,
197        $audience = self::AUDIENCE_PUBLIC,
198        $flags = IDBAccessObject::READ_NORMAL,
199        $wikiId = UserIdentity::LOCAL
200    ) {
201        return $this->lookupUserNamesWithFilter( $nameToId, self::FILTER_OWNED,
202            $audience, $flags, $wikiId );
203    }
204
205    /**
206     * Given user names on the wiki specified by $wikiId, return the central
207     * IDs, but only include IDs for local users attached to the central user,
208     * i.e. isAttached() would be true.
209     *
210     * @since 1.44
211     *
212     * @param array $nameToId Array with keys being canonicalized user names
213     * @param int|Authority $audience One of the audience constants, or a specific authority
214     * @param int $flags IDBAccessObject read flags
215     * @param string|false $wikiId Wiki to check attachment status. If false, check the current
216     *   wiki.
217     * @return int[] Copy of $nameToId with values set to central IDs.
218     *   Names not attached to the central user are unchanged.
219     */
220    public function lookupAttachedUserNames(
221        array $nameToId,
222        $audience = self::AUDIENCE_PUBLIC,
223        $flags = IDBAccessObject::READ_NORMAL,
224        $wikiId = UserIdentity::LOCAL
225    ) {
226        return $this->lookupUserNamesWithFilter( $nameToId, self::FILTER_ATTACHED,
227            $audience, $flags, $wikiId );
228    }
229
230    /**
231     * Given user names on the wiki specified by $wikiId, return the central
232     * IDs. If $filter is not FILTER_NONE, filter the users by owned or
233     * attached status.
234     *
235     * @since 1.44
236     *
237     * @param array $nameToId Array with keys being canonicalized user names
238     * @param string $filter One of:
239     *   - self::FILTER_NONE: Get all users with the specified names
240     *   - self::FILTER_ATTACHED: Only get IDs for attached users
241     *   - self::FILTER_OWNED: Only get IDs for owned users
242     * @param int|Authority $audience One of the audience constants, or a specific authority
243     * @param int $flags IDBAccessObject read flags
244     * @param string|false $wikiId Wiki to check attachment status. If false, check the current
245     *   wiki.
246     * @return int[] Copy of $nameToId with values set to central IDs.
247     *   Names not owned by the central user are unchanged.
248     */
249    abstract protected function lookupUserNamesWithFilter(
250        array $nameToId,
251        $filter,
252        $audience = self::AUDIENCE_PUBLIC,
253        $flags = IDBAccessObject::READ_NORMAL,
254        $wikiId = UserIdentity::LOCAL
255    ): array;
256
257    /**
258     * Given a central user ID, return the (local) user name
259     * @note There's no requirement that the user name actually exists locally,
260     *  or if it does that it's actually attached to the central account.
261     * @param int $id Central user ID
262     * @param int|Authority $audience One of the audience constants, or a specific authority
263     * @param int $flags IDBAccessObject read flags
264     * @return string|null user name, or empty string if $audience lacks the
265     *  rights needed to see it, or null if $id doesn't correspond to a user
266     */
267    public function nameFromCentralId(
268        $id, $audience = self::AUDIENCE_PUBLIC, $flags = IDBAccessObject::READ_NORMAL
269    ): ?string {
270        $idToName = $this->lookupCentralIds( [ $id => null ], $audience, $flags );
271        return $idToName[$id];
272    }
273
274    /**
275     * Given a an array of central user IDs, return the (local) user names.
276     * @param int[] $ids Central user IDs
277     * @param int|Authority $audience One of the audience constants, or a specific authority
278     * @param int $flags IDBAccessObject read flags
279     * @return string[] user names
280     * @since 1.30
281     */
282    public function namesFromCentralIds(
283        array $ids, $audience = self::AUDIENCE_PUBLIC, $flags = IDBAccessObject::READ_NORMAL
284    ): array {
285        $idToName = array_fill_keys( $ids, false );
286        $names = $this->lookupCentralIds( $idToName, $audience, $flags );
287        $names = array_unique( $names );
288        $names = array_filter( $names, static function ( $name ) {
289            return $name !== false && $name !== '';
290        } );
291
292        return array_values( $names );
293    }
294
295    /**
296     * Given a (local) user name, return the central ID
297     * @note There's no requirement that the user name actually exists locally,
298     *  or if it does that it's actually attached to the central account.
299     * @param string $name Canonicalized user name
300     * @param int|Authority $audience One of the audience constants, or a specific authority
301     * @param int $flags IDBAccessObject read flags
302     * @return int user ID; 0 if the name does not correspond to a user or
303     *  $audience lacks the rights needed to see it.
304     */
305    public function centralIdFromName(
306        $name, $audience = self::AUDIENCE_PUBLIC, $flags = IDBAccessObject::READ_NORMAL
307    ): int {
308        $nameToId = $this->lookupUserNames( [ $name => 0 ], $audience, $flags );
309        return $nameToId[$name];
310    }
311
312    /**
313     * Given an array of (local) user names, return the central IDs.
314     * @param string[] $names Canonicalized user names
315     * @param int|Authority $audience One of the audience constants, or a specific authority
316     * @param int $flags IDBAccessObject read flags
317     * @return int[] user IDs
318     * @since 1.30
319     */
320    public function centralIdsFromNames(
321        array $names, $audience = self::AUDIENCE_PUBLIC, $flags = IDBAccessObject::READ_NORMAL
322    ): array {
323        $nameToId = array_fill_keys( $names, false );
324        $ids = $this->lookupUserNames( $nameToId, $audience, $flags );
325        $ids = array_unique( $ids );
326        $ids = array_filter( $ids, static function ( $id ) {
327            return $id !== false;
328        } );
329
330        return array_values( $ids );
331    }
332
333    /**
334     * Given a central user ID, return a local user object
335     * @note Unlike nameFromCentralId(), this does guarantee that the local
336     *  user exists and is attached to the central account.
337     * @stable to override
338     * @param int $id Central user ID
339     * @param int|Authority $audience One of the audience constants, or a specific authority
340     * @param int $flags IDBAccessObject read flags
341     * @return UserIdentity|null Local user, or null if: $id doesn't correspond to a
342     *  user, $audience lacks the rights needed to see the user, the user
343     *  doesn't exist locally, or the user isn't locally attached.
344     */
345    public function localUserFromCentralId(
346        $id, $audience = self::AUDIENCE_PUBLIC, $flags = IDBAccessObject::READ_NORMAL
347    ): ?UserIdentity {
348        $name = $this->nameFromCentralId( $id, $audience, $flags );
349        if ( !$name ) {
350            return null;
351        }
352        $user = $this->userIdentityLookup->getUserIdentityByName( $name );
353        if ( $user && $user->isRegistered() && $this->isAttached( $user ) ) {
354            return $user;
355        }
356        return null;
357    }
358
359    /**
360     * Given a local UserIdentity object, return the central ID
361     * @stable to override
362     * @note Unlike centralIdFromName(), this does guarantee that the local
363     *  user is attached to the central account.
364     * @param UserIdentity $user Local user
365     * @param int|Authority $audience One of the audience constants, or a specific authority
366     * @param int $flags IDBAccessObject read flags
367     * @return int user ID; 0 if the local user does not correspond to a
368     *  central user, $audience lacks the rights needed to see it, or the
369     *  central user isn't locally attached.
370     */
371    public function centralIdFromLocalUser(
372        UserIdentity $user, $audience = self::AUDIENCE_PUBLIC, $flags = IDBAccessObject::READ_NORMAL
373    ): int {
374        $name = $user->getName();
375        $nameToId = $this->lookupAttachedUserNames( [ $name => 0 ], $audience, $flags );
376        return $nameToId[$name];
377    }
378
379}
380
381/** @deprecated class alias since 1.41 */
382class_alias( CentralIdLookup::class, 'CentralIdLookup' );