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
24 * The CentralIdLookup service allows for connecting local users with
27 abstract class CentralIdLookup
implements IDBAccessObject
{
28 // Audience options for accessors
29 const AUDIENCE_PUBLIC
= 1;
30 const AUDIENCE_RAW
= 2;
32 /** @var CentralIdLookup[][] */
33 private static $instances = array();
39 * Fetch a CentralIdLookup
40 * @param string|null $providerId Provider ID from $wgCentralIdLookupProviders
41 * @return CentralIdLookup|null
43 public static function factory( $providerId = null ) {
44 global $wgCentralIdLookupProviders, $wgCentralIdLookupProvider;
46 if ( $providerId === null ) {
47 $providerId = $wgCentralIdLookupProvider;
50 if ( !array_key_exists( $providerId, self
::$instances ) ) {
51 self
::$instances[$providerId] = null;
53 if ( isset( $wgCentralIdLookupProviders[$providerId] ) ) {
54 $provider = ObjectFactory
::getObjectFromSpec( $wgCentralIdLookupProviders[$providerId] );
55 if ( $provider instanceof CentralIdLookup
) {
56 $provider->providerId
= $providerId;
57 self
::$instances[$providerId] = $provider;
62 return self
::$instances[$providerId];
66 * Reset internal cache for unit testing
68 public static function resetCache() {
69 if ( !defined( 'MW_PHPUNIT_TEST' ) ) {
70 throw new MWException( __METHOD__
. ' may only be called from unit tests!' );
72 self
::$instances = array();
75 final public function getProviderId() {
76 return $this->providerId
;
80 * Check that the "audience" parameter is valid
81 * @param int|User $audience One of the audience constants, or a specific user
82 * @return User|null User to check against, or null if no checks are needed
83 * @throws InvalidArgumentException
85 protected function checkAudience( $audience ) {
86 if ( $audience instanceof User
) {
89 if ( $audience === self
::AUDIENCE_PUBLIC
) {
92 if ( $audience === self
::AUDIENCE_RAW
) {
95 throw new InvalidArgumentException( 'Invalid audience' );
99 * Check that a User is attached on the specified wiki.
101 * If unattached local accounts don't exist in your extension, this comes
102 * down to a check whether the central account exists at all and that
103 * $wikiId is using the same central database.
106 * @param string|null $wikiId Wiki to check attachment status. If null, check the current wiki.
109 abstract public function isAttached( User
$user, $wikiId = null );
112 * Given central user IDs, return the (local) user names
113 * @note There's no requirement that the user names actually exist locally,
114 * or if they do that they're actually attached to the central account.
115 * @param array $idToName Array with keys being central user IDs
116 * @param int|User $audience One of the audience constants, or a specific user
117 * @param int $flags IDBAccessObject read flags
118 * @return array Copy of $idToName with values set to user names (or
119 * empty-string if the user exists but $audience lacks the rights needed
120 * to see it). IDs not corresponding to a user are unchanged.
122 abstract public function lookupCentralIds(
123 array $idToName, $audience = self
::AUDIENCE_PUBLIC
, $flags = self
::READ_NORMAL
127 * Given (local) user names, return the central IDs
128 * @note There's no requirement that the user names actually exist locally,
129 * or if they do that they're actually attached to the central account.
130 * @param array $nameToId Array with keys being canonicalized user names
131 * @param int|User $audience One of the audience constants, or a specific user
132 * @param int $flags IDBAccessObject read flags
133 * @return array Copy of $nameToId with values set to central IDs.
134 * Names not corresponding to a user (or $audience lacks the rights needed
135 * to see it) are unchanged.
137 abstract public function lookupUserNames(
138 array $nameToId, $audience = self
::AUDIENCE_PUBLIC
, $flags = self
::READ_NORMAL
142 * Given a central user ID, return the (local) user name
143 * @note There's no requirement that the user name actually exists locally,
144 * or if it does that it's actually attached to the central account.
145 * @param int $id Central user ID
146 * @param int|User $audience One of the audience constants, or a specific user
147 * @param int $flags IDBAccessObject read flags
148 * @return string|null User name, or empty string if $audience lacks the
149 * rights needed to see it, or null if $id doesn't correspond to a user
151 public function nameFromCentralId(
152 $id, $audience = self
::AUDIENCE_PUBLIC
, $flags = self
::READ_NORMAL
154 $idToName = $this->lookupCentralIds( array( $id => null ), $audience, $flags );
155 return $idToName[$id];
159 * Given a (local) user name, return the central ID
160 * @note There's no requirement that the user name actually exists locally,
161 * or if it does that it's actually attached to the central account.
162 * @param string $name Canonicalized user name
163 * @param int|User $audience One of the audience constants, or a specific user
164 * @param int $flags IDBAccessObject read flags
165 * @return int User ID; 0 if the name does not correspond to a user or
166 * $audience lacks the rights needed to see it.
168 public function centralIdFromName(
169 $name, $audience = self
::AUDIENCE_PUBLIC
, $flags = self
::READ_NORMAL
171 $nameToId = $this->lookupUserNames( array( $name => 0 ), $audience, $flags );
172 return $nameToId[$name];
176 * Given a central user ID, return a local User object
177 * @note Unlike nameFromCentralId(), this does guarantee that the local
178 * user exists and is attached to the central account.
179 * @param int $id Central user ID
180 * @param int|User $audience One of the audience constants, or a specific user
181 * @param int $flags IDBAccessObject read flags
182 * @return User|null Local user, or null if: $id doesn't correspond to a
183 * user, $audience lacks the rights needed to see the user, the user
184 * doesn't exist locally, or the user isn't locally attached.
186 public function localUserFromCentralId(
187 $id, $audience = self
::AUDIENCE_PUBLIC
, $flags = self
::READ_NORMAL
189 $name = $this->nameFromCentralId( $id, $audience, $flags );
190 if ( $name !== null && $name !== '' ) {
191 $user = User
::newFromName( $name );
192 if ( $user && $user->getId() && $this->isAttached( $user ) ) {
200 * Given a local User object, return the central ID
201 * @note Unlike centralIdFromName(), this does guarantee that the local
202 * user is attached to the central account.
203 * @param User $user Local user
204 * @param int|User $audience One of the audience constants, or a specific user
205 * @param int $flags IDBAccessObject read flags
206 * @return int User ID; 0 if the local user does not correspond to a
207 * central user, $audience lacks the rights needed to see it, or the
208 * central user isn't locally attached.
210 public function centralIdFromLocalUser(
211 User
$user, $audience = self
::AUDIENCE_PUBLIC
, $flags = self
::READ_NORMAL
213 return $this->isAttached( $user )
214 ?
$this->centralIdFromName( $user->getName(), $audience, $flags )