Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
51.92% covered (warning)
51.92%
27 / 52
63.64% covered (warning)
63.64%
7 / 11
 CRAP
0.00% covered (danger)
0.00%
0 / 1
CentralIdLookup
52.94% covered (warning)
52.94%
27 / 51
63.64% covered (warning)
63.64%
7 / 11
 72.44
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
 factoryNonLocal
0.00% covered (danger)
0.00%
0 / 4
0.00% covered (danger)
0.00%
0 / 1
 2
 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
 lookupCentralIds
n/a
0 / 0
n/a
0 / 0
 0
 lookupUserNames
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
 2
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
23namespace MediaWiki\User\CentralId;
24
25use IDBAccessObject;
26use InvalidArgumentException;
27use LogicException;
28use MediaWiki\MediaWikiServices;
29use MediaWiki\Permissions\Authority;
30use MediaWiki\User\UserFactory;
31use MediaWiki\User\UserIdentity;
32use MediaWiki\User\UserIdentityLookup;
33use Throwable;
34
35/**
36 * The CentralIdLookup service allows for connecting local users with
37 * cluster-wide IDs.
38 *
39 * @since 1.27
40 * @stable to extend
41 */
42abstract class CentralIdLookup {
43    // Audience options for accessors
44    public const AUDIENCE_PUBLIC = 1;
45    public const AUDIENCE_RAW = 2;
46
47    /** @var string */
48    private $providerId;
49
50    /** @var UserIdentityLookup */
51    private $userIdentityLookup;
52    private UserFactory $userFactory;
53
54    /**
55     * Fetch a CentralIdLookup
56     * @deprecated since 1.37 Use MediaWikiServices to obtain an instance.
57     * @param string|null $providerId Provider ID from $wgCentralIdLookupProviders
58     * @return CentralIdLookup|null
59     */
60    public static function factory( $providerId = null ) {
61        wfDeprecated( __METHOD__, '1.37' );
62        try {
63            return MediaWikiServices::getInstance()
64                ->getCentralIdLookupFactory()
65                ->getLookup( $providerId );
66        } catch ( Throwable $unused ) {
67            return null;
68        }
69    }
70
71    /**
72     * Returns a CentralIdLookup that is guaranteed to be non-local.
73     * If no such guarantee can be made, returns null.
74     *
75     * If this function returns a non-null CentralIdLookup,
76     * that lookup is expected to provide IDs that are shared with some set of other wikis.
77     * However, you should still be cautious when using those IDs,
78     * as they will not necessarily work with *all* other wikis,
79     * and it can be hard to tell if another wiki is in the same set as this one or not.
80     *
81     * @since 1.35
82     * @deprecated since 1.37. Use CentralIdLookupFactory::getNonLocalLookup instead.
83     * @return CentralIdLookup|null
84     */
85    public static function factoryNonLocal(): ?self {
86        wfDeprecated( __METHOD__, '1.37' );
87        return MediaWikiServices::getInstance()
88            ->getCentralIdLookupFactory()
89            ->getNonLocalLookup();
90    }
91
92    /**
93     * Initialize the provider.
94     *
95     * @param string $providerId
96     * @param UserIdentityLookup $userIdentityLookup
97     * @internal
98     */
99    public function init(
100        string $providerId,
101        UserIdentityLookup $userIdentityLookup,
102        UserFactory $userFactory
103    ) {
104        if ( $this->providerId !== null ) {
105            throw new LogicException( "CentralIdProvider $providerId already initialized" );
106        }
107        $this->providerId = $providerId;
108        $this->userIdentityLookup = $userIdentityLookup;
109        $this->userFactory = $userFactory;
110    }
111
112    /**
113     * Get the provider id.
114     *
115     * @return string
116     */
117    public function getProviderId(): string {
118        return $this->providerId;
119    }
120
121    /**
122     * Check that the "audience" parameter is valid
123     * @param int|Authority $audience One of the audience constants, or a specific authority
124     * @return Authority|null authority to check against, or null if no checks are needed
125     * @throws InvalidArgumentException
126     */
127    protected function checkAudience( $audience ): ?Authority {
128        if ( $audience instanceof Authority ) {
129            return $audience;
130        }
131        if ( $audience === self::AUDIENCE_PUBLIC ) {
132            // TODO: when available, inject AuthorityFactory
133            // via init and use it to create anon authority
134            return $this->userFactory->newAnonymous();
135        }
136        if ( $audience === self::AUDIENCE_RAW ) {
137            return null;
138        }
139        throw new InvalidArgumentException( 'Invalid audience' );
140    }
141
142    /**
143     * Check that a user is attached on the specified wiki.
144     *
145     * If unattached local accounts don't exist in your extension, this comes
146     * down to a check whether the central account exists at all and that
147     * $wikiId is using the same central database.
148     *
149     * @param UserIdentity $user
150     * @param string|false $wikiId Wiki to check attachment status. If false, check the current wiki.
151     * @return bool
152     */
153    abstract public function isAttached( UserIdentity $user, $wikiId = UserIdentity::LOCAL ): bool;
154
155    /**
156     * Given central user IDs, return the (local) user names
157     * @note There's no requirement that the user names actually exist locally,
158     *  or if they do that they're actually attached to the central account.
159     * @param array $idToName Array with keys being central user IDs
160     * @param int|Authority $audience One of the audience constants, or a specific authority
161     * @param int $flags IDBAccessObject read flags
162     * @return string[] Copy of $idToName with values set to user names (or
163     *  empty-string if the user exists but $audience lacks the rights needed
164     *  to see it). IDs not corresponding to a user are unchanged.
165     */
166    abstract public function lookupCentralIds(
167        array $idToName, $audience = self::AUDIENCE_PUBLIC, $flags = IDBAccessObject::READ_NORMAL
168    ): array;
169
170    /**
171     * Given (local) user names, return the central IDs
172     * @note There's no requirement that the user names actually exist locally,
173     *  or if they do that they're actually attached to the central account.
174     * @param array $nameToId Array with keys being canonicalized user names
175     * @param int|Authority $audience One of the audience constants, or a specific authority
176     * @param int $flags IDBAccessObject read flags
177     * @return int[] Copy of $nameToId with values set to central IDs.
178     *  Names not corresponding to a user (or $audience lacks the rights needed
179     *  to see it) are unchanged.
180     */
181    abstract public function lookupUserNames(
182        array $nameToId, $audience = self::AUDIENCE_PUBLIC, $flags = IDBAccessObject::READ_NORMAL
183    ): array;
184
185    /**
186     * Given a central user ID, return the (local) user name
187     * @note There's no requirement that the user name actually exists locally,
188     *  or if it does that it's actually attached to the central account.
189     * @param int $id Central user ID
190     * @param int|Authority $audience One of the audience constants, or a specific authority
191     * @param int $flags IDBAccessObject read flags
192     * @return string|null user name, or empty string if $audience lacks the
193     *  rights needed to see it, or null if $id doesn't correspond to a user
194     */
195    public function nameFromCentralId(
196        $id, $audience = self::AUDIENCE_PUBLIC, $flags = IDBAccessObject::READ_NORMAL
197    ): ?string {
198        $idToName = $this->lookupCentralIds( [ $id => null ], $audience, $flags );
199        return $idToName[$id];
200    }
201
202    /**
203     * Given a an array of central user IDs, return the (local) user names.
204     * @param int[] $ids Central user IDs
205     * @param int|Authority $audience One of the audience constants, or a specific authority
206     * @param int $flags IDBAccessObject read flags
207     * @return string[] user names
208     * @since 1.30
209     */
210    public function namesFromCentralIds(
211        array $ids, $audience = self::AUDIENCE_PUBLIC, $flags = IDBAccessObject::READ_NORMAL
212    ): array {
213        $idToName = array_fill_keys( $ids, false );
214        $names = $this->lookupCentralIds( $idToName, $audience, $flags );
215        $names = array_unique( $names );
216        $names = array_filter( $names, static function ( $name ) {
217            return $name !== false && $name !== '';
218        } );
219
220        return array_values( $names );
221    }
222
223    /**
224     * Given a (local) user name, return the central ID
225     * @note There's no requirement that the user name actually exists locally,
226     *  or if it does that it's actually attached to the central account.
227     * @param string $name Canonicalized user name
228     * @param int|Authority $audience One of the audience constants, or a specific authority
229     * @param int $flags IDBAccessObject read flags
230     * @return int user ID; 0 if the name does not correspond to a user or
231     *  $audience lacks the rights needed to see it.
232     */
233    public function centralIdFromName(
234        $name, $audience = self::AUDIENCE_PUBLIC, $flags = IDBAccessObject::READ_NORMAL
235    ): int {
236        $nameToId = $this->lookupUserNames( [ $name => 0 ], $audience, $flags );
237        return $nameToId[$name];
238    }
239
240    /**
241     * Given an array of (local) user names, return the central IDs.
242     * @param string[] $names Canonicalized user names
243     * @param int|Authority $audience One of the audience constants, or a specific authority
244     * @param int $flags IDBAccessObject read flags
245     * @return int[] user IDs
246     * @since 1.30
247     */
248    public function centralIdsFromNames(
249        array $names, $audience = self::AUDIENCE_PUBLIC, $flags = IDBAccessObject::READ_NORMAL
250    ): array {
251        $nameToId = array_fill_keys( $names, false );
252        $ids = $this->lookupUserNames( $nameToId, $audience, $flags );
253        $ids = array_unique( $ids );
254        $ids = array_filter( $ids, static function ( $id ) {
255            return $id !== false;
256        } );
257
258        return array_values( $ids );
259    }
260
261    /**
262     * Given a central user ID, return a local user object
263     * @note Unlike nameFromCentralId(), this does guarantee that the local
264     *  user exists and is attached to the central account.
265     * @stable to override
266     * @param int $id Central user ID
267     * @param int|Authority $audience One of the audience constants, or a specific authority
268     * @param int $flags IDBAccessObject read flags
269     * @return UserIdentity|null Local user, or null if: $id doesn't correspond to a
270     *  user, $audience lacks the rights needed to see the user, the user
271     *  doesn't exist locally, or the user isn't locally attached.
272     */
273    public function localUserFromCentralId(
274        $id, $audience = self::AUDIENCE_PUBLIC, $flags = IDBAccessObject::READ_NORMAL
275    ): ?UserIdentity {
276        $name = $this->nameFromCentralId( $id, $audience, $flags );
277        if ( !$name ) {
278            return null;
279        }
280        $user = $this->userIdentityLookup->getUserIdentityByName( $name );
281        if ( $user && $user->isRegistered() && $this->isAttached( $user ) ) {
282            return $user;
283        }
284        return null;
285    }
286
287    /**
288     * Given a local UserIdentity object, return the central ID
289     * @stable to override
290     * @note Unlike centralIdFromName(), this does guarantee that the local
291     *  user is attached to the central account.
292     * @param UserIdentity $user Local user
293     * @param int|Authority $audience One of the audience constants, or a specific authority
294     * @param int $flags IDBAccessObject read flags
295     * @return int user ID; 0 if the local user does not correspond to a
296     *  central user, $audience lacks the rights needed to see it, or the
297     *  central user isn't locally attached.
298     */
299    public function centralIdFromLocalUser(
300        UserIdentity $user, $audience = self::AUDIENCE_PUBLIC, $flags = IDBAccessObject::READ_NORMAL
301    ): int {
302        return $this->isAttached( $user )
303            ? $this->centralIdFromName( $user->getName(), $audience, $flags )
304            : 0;
305    }
306
307}
308
309/** @deprecated class alias since 1.41 */
310class_alias( CentralIdLookup::class, 'CentralIdLookup' );