3 * A central user id lookup service
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.
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.
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
22 use Wikimedia\ObjectFactory
;
25 * The CentralIdLookup service allows for connecting local users with
30 abstract class CentralIdLookup
implements IDBAccessObject
{
31 // Audience options for accessors
32 const AUDIENCE_PUBLIC
= 1;
33 const AUDIENCE_RAW
= 2;
35 /** @var CentralIdLookup[] */
36 private static $instances = [];
42 * Fetch a CentralIdLookup
43 * @param string|null $providerId Provider ID from $wgCentralIdLookupProviders
44 * @return CentralIdLookup|null
46 public static function factory( $providerId = null ) {
47 global $wgCentralIdLookupProviders, $wgCentralIdLookupProvider;
49 if ( $providerId === null ) {
50 $providerId = $wgCentralIdLookupProvider;
53 if ( !array_key_exists( $providerId, self
::$instances ) ) {
54 self
::$instances[$providerId] = null;
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;
65 return self
::$instances[$providerId];
69 * Reset internal cache for unit testing
72 public static function resetCache() {
73 if ( !defined( 'MW_PHPUNIT_TEST' ) ) {
74 throw new MWException( __METHOD__
. ' may only be called from unit tests!' );
76 self
::$instances = [];
79 final public function getProviderId() {
80 return $this->providerId
;
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
89 protected function checkAudience( $audience ) {
90 if ( $audience instanceof User
) {
93 if ( $audience === self
::AUDIENCE_PUBLIC
) {
96 if ( $audience === self
::AUDIENCE_RAW
) {
99 throw new InvalidArgumentException( 'Invalid audience' );
103 * Check that a User is attached on the specified wiki.
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.
110 * @param string|null $wikiId Wiki to check attachment status. If null, check the current wiki.
113 abstract public function isAttached( User
$user, $wikiId = null );
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.
126 abstract public function lookupCentralIds(
127 array $idToName, $audience = self
::AUDIENCE_PUBLIC
, $flags = self
::READ_NORMAL
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.
141 abstract public function lookupUserNames(
142 array $nameToId, $audience = self
::AUDIENCE_PUBLIC
, $flags = self
::READ_NORMAL
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
155 public function nameFromCentralId(
156 $id, $audience = self
::AUDIENCE_PUBLIC
, $flags = self
::READ_NORMAL
158 $idToName = $this->lookupCentralIds( [ $id => null ], $audience, $flags );
159 return $idToName[$id];
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
170 public function namesFromCentralIds(
171 array $ids, $audience = self
::AUDIENCE_PUBLIC
, $flags = self
::READ_NORMAL
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 !== '';
180 return array_values( $names );
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.
193 public function centralIdFromName(
194 $name, $audience = self
::AUDIENCE_PUBLIC
, $flags = self
::READ_NORMAL
196 $nameToId = $this->lookupUserNames( [ $name => 0 ], $audience, $flags );
197 return $nameToId[$name];
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
208 public function centralIdsFromNames(
209 array $names, $audience = self
::AUDIENCE_PUBLIC
, $flags = self
::READ_NORMAL
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;
218 return array_values( $ids );
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.
232 public function localUserFromCentralId(
233 $id, $audience = self
::AUDIENCE_PUBLIC
, $flags = self
::READ_NORMAL
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 ) ) {
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.
256 public function centralIdFromLocalUser(
257 User
$user, $audience = self
::AUDIENCE_PUBLIC
, $flags = self
::READ_NORMAL
259 return $this->isAttached( $user )
260 ?
$this->centralIdFromName( $user->getName(), $audience, $flags )