3 * Methods to help with the actor table migration
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
23 use MediaWiki\MediaWikiServices
;
24 use MediaWiki\User\UserIdentity
;
25 use Wikimedia\Rdbms\IDatabase
;
28 * This class handles the logic for the actor table migration.
30 * This is not intended to be a long-term part of MediaWiki; it will be
31 * deprecated and removed once actor migration is complete.
34 * @since 1.34 Use with 'ar_user', 'img_user', 'oi_user', 'fa_user',
35 * 'rc_user', 'log_user', and 'ipb_by' is deprecated. Callers should
36 * reference the corresponding actor fields directly.
38 class ActorMigration
{
41 * Constant for extensions to feature-test whether $wgActorTableSchemaMigrationStage
42 * (in MW <1.34) expects MIGRATION_* or SCHEMA_COMPAT_*
44 const MIGRATION_STAGE_SCHEMA_COMPAT
= 1;
47 * Define fields that use temporary tables for transitional purposes
48 * @var array Keys are '$key', values are arrays with four fields:
49 * - table: Temporary table name
50 * - pk: Temporary table column referring to the main table's primary key
51 * - field: Temporary table column referring actor.actor_id
52 * - joinPK: Main table's primary key
54 private static $tempTables = [
56 'table' => 'revision_actor_temp',
57 'pk' => 'revactor_rev',
58 'field' => 'revactor_actor',
61 'revactor_timestamp' => 'rev_timestamp',
62 'revactor_page' => 'rev_page',
68 * Fields that formerly used $tempTables
69 * @var array Key is '$key', value is the MediaWiki version in which it was
70 * removed from $tempTables.
72 private static $formerTempTables = [];
75 * Define fields that are deprecated for use with this class.
76 * @var (string|null)[] Keys are '$key', value is null for soft deprecation
77 * or a string naming the deprecated version for hard deprecation.
79 private static $deprecated = [
80 'ar_user' => null, // 1.34
81 'img_user' => null, // 1.34
82 'oi_user' => null, // 1.34
83 'fa_user' => null, // 1.34
84 'rc_user' => null, // 1.34
85 'log_user' => null, // 1.34
86 'ipb_by' => null, // 1.34
90 * Define fields that are removed for use with this class.
91 * @var string[] Keys are '$key', value is the MediaWiki version in which
94 private static $removed = [];
97 * Define fields that use non-standard mapping
98 * @var array Keys are the user id column name, values are arrays with two
99 * elements (the user text column name and the actor id column name)
101 private static $specialFields = [
102 'ipb_by' => [ 'ipb_by_text', 'ipb_by_actor' ],
105 /** @var array|null Cache for `self::getJoin()` */
106 private $joinCache = null;
108 /** @var int Combination of SCHEMA_COMPAT_* constants */
112 public function __construct( $stage ) {
113 if ( ( $stage & SCHEMA_COMPAT_WRITE_BOTH
) === 0 ) {
114 throw new InvalidArgumentException( '$stage must include a write mode' );
116 if ( ( $stage & SCHEMA_COMPAT_READ_BOTH
) === 0 ) {
117 throw new InvalidArgumentException( '$stage must include a read mode' );
119 if ( ( $stage & SCHEMA_COMPAT_READ_BOTH
) === SCHEMA_COMPAT_READ_BOTH
) {
120 throw new InvalidArgumentException( 'Cannot read both schemas' );
122 if ( ( $stage & SCHEMA_COMPAT_READ_OLD
) && !( $stage & SCHEMA_COMPAT_WRITE_OLD
) ) {
123 throw new InvalidArgumentException( 'Cannot read the old schema without also writing it' );
125 if ( ( $stage & SCHEMA_COMPAT_READ_NEW
) && !( $stage & SCHEMA_COMPAT_WRITE_NEW
) ) {
126 throw new InvalidArgumentException( 'Cannot read the new schema without also writing it' );
129 $this->stage
= $stage;
134 * @return ActorMigration
136 public static function newMigration() {
137 return MediaWikiServices
::getInstance()->getActorMigration();
141 * Issue deprecation warning/error as appropriate.
144 private static function checkDeprecation( $key ) {
145 if ( isset( self
::$removed[$key] ) ) {
146 throw new InvalidArgumentException(
147 "Use of " . static::class . " for '$key' was removed in MediaWiki " . self
::$removed[$key]
150 if ( !empty( self
::$deprecated[$key] ) ) {
151 wfDeprecated( static::class . " for '$key'", self
::$deprecated[$key], false, 3 );
156 * Return an SQL condition to test if a user field is anonymous
157 * @param string $field Field name or SQL fragment
160 public function isAnon( $field ) {
161 return ( $this->stage
& SCHEMA_COMPAT_READ_NEW
) ?
"$field IS NULL" : "$field = 0";
165 * Return an SQL condition to test if a user field is non-anonymous
166 * @param string $field Field name or SQL fragment
169 public function isNotAnon( $field ) {
170 return ( $this->stage
& SCHEMA_COMPAT_READ_NEW
) ?
"$field IS NOT NULL" : "$field != 0";
174 * @param string $key A key such as "rev_user" identifying the actor
175 * field being fetched.
176 * @return string[] [ $text, $actor ]
178 private static function getFieldNames( $key ) {
179 return self
::$specialFields[$key] ??
[ $key . '_text', substr( $key, 0, -5 ) . '_actor' ];
183 * Get SELECT fields and joins for the actor key
185 * @param string $key A key such as "rev_user" identifying the actor
186 * field being fetched.
187 * @return array[] With three keys:
188 * - tables: (string[]) to include in the `$table` to `IDatabase->select()`
189 * - fields: (string[]) to include in the `$vars` to `IDatabase->select()`
190 * - joins: (array) to include in the `$join_conds` to `IDatabase->select()`
191 * All tables, fields, and joins are aliased, so `+` is safe to use.
192 * @phan-return array{tables:string[],fields:string[],joins:array}
194 public function getJoin( $key ) {
195 self
::checkDeprecation( $key );
197 if ( !isset( $this->joinCache
[$key] ) ) {
202 list( $text, $actor ) = self
::getFieldNames( $key );
204 if ( $this->stage
& SCHEMA_COMPAT_READ_OLD
) {
205 $fields[$key] = $key;
206 $fields[$text] = $text;
207 $fields[$actor] = 'NULL';
209 if ( isset( self
::$tempTables[$key] ) ) {
210 $t = self
::$tempTables[$key];
211 $alias = "temp_$key";
212 $tables[$alias] = $t['table'];
213 $joins[$alias] = [ 'JOIN', "{$alias}.{$t['pk']} = {$t['joinPK']}" ];
214 $joinField = "{$alias}.{$t['field']}";
219 $alias = "actor_$key";
220 $tables[$alias] = 'actor';
221 $joins[$alias] = [ 'JOIN', "{$alias}.actor_id = {$joinField}" ];
223 $fields[$key] = "{$alias}.actor_user";
224 $fields[$text] = "{$alias}.actor_name";
225 $fields[$actor] = $joinField;
228 $this->joinCache
[$key] = [
235 return $this->joinCache
[$key];
239 * Get UPDATE fields for the actor
241 * @param IDatabase $dbw Database to use for creating an actor ID, if necessary
242 * @param string $key A key such as "rev_user" identifying the actor
243 * field being fetched.
244 * @param UserIdentity $user User to set in the update
245 * @return array to merge into `$values` to `IDatabase->update()` or `$a` to `IDatabase->insert()`
247 public function getInsertValues( IDatabase
$dbw, $key, UserIdentity
$user ) {
248 self
::checkDeprecation( $key );
250 if ( isset( self
::$tempTables[$key] ) ) {
251 throw new InvalidArgumentException( "Must use getInsertValuesWithTempTable() for $key" );
254 list( $text, $actor ) = self
::getFieldNames( $key );
256 if ( $this->stage
& SCHEMA_COMPAT_WRITE_OLD
) {
257 $ret[$key] = $user->getId();
258 $ret[$text] = $user->getName();
260 if ( $this->stage
& SCHEMA_COMPAT_WRITE_NEW
) {
261 // We need to be able to assign an actor ID if none exists
262 if ( !$user instanceof User
&& !$user->getActorId() ) {
263 $user = User
::newFromAnyId( $user->getId(), $user->getName(), null );
265 $ret[$actor] = $user->getActorId( $dbw );
271 * Get UPDATE fields for the actor
273 * @param IDatabase $dbw Database to use for creating an actor ID, if necessary
274 * @param string $key A key such as "rev_user" identifying the actor
275 * field being fetched.
276 * @param UserIdentity $user User to set in the update
277 * @return array with two values:
278 * - array to merge into `$values` to `IDatabase->update()` or `$a` to `IDatabase->insert()`
279 * - callback to call with the primary key for the main table insert
280 * and extra fields needed for the temp table.
282 public function getInsertValuesWithTempTable( IDatabase
$dbw, $key, UserIdentity
$user ) {
283 self
::checkDeprecation( $key );
285 if ( isset( self
::$formerTempTables[$key] ) ) {
286 wfDeprecated( __METHOD__
. " for $key", self
::$formerTempTables[$key] );
287 } elseif ( !isset( self
::$tempTables[$key] ) ) {
288 throw new InvalidArgumentException( "Must use getInsertValues() for $key" );
291 list( $text, $actor ) = self
::getFieldNames( $key );
294 if ( $this->stage
& SCHEMA_COMPAT_WRITE_OLD
) {
295 $ret[$key] = $user->getId();
296 $ret[$text] = $user->getName();
298 if ( $this->stage
& SCHEMA_COMPAT_WRITE_NEW
) {
299 // We need to be able to assign an actor ID if none exists
300 if ( !$user instanceof User
&& !$user->getActorId() ) {
301 $user = User
::newFromAnyId( $user->getId(), $user->getName(), null );
303 $id = $user->getActorId( $dbw );
305 if ( isset( self
::$tempTables[$key] ) ) {
307 $callback = function ( $pk, array $extra ) use ( $dbw, $key, $id, $func ) {
308 $t = self
::$tempTables[$key];
309 $set = [ $t['field'] => $id ];
310 foreach ( $t['extra'] as $to => $from ) {
311 if ( !array_key_exists( $from, $extra ) ) {
312 throw new InvalidArgumentException( "$func callback: \$extra[$from] is not provided" );
314 $set[$to] = $extra[$from];
318 [ $t['pk'] => $pk ] +
$set,
326 $callback = function ( $pk, array $extra ) {
329 } elseif ( isset( self
::$tempTables[$key] ) ) {
331 $callback = function ( $pk, array $extra ) use ( $key, $func ) {
332 $t = self
::$tempTables[$key];
333 foreach ( $t['extra'] as $to => $from ) {
334 if ( !array_key_exists( $from, $extra ) ) {
335 throw new InvalidArgumentException( "$func callback: \$extra[$from] is not provided" );
340 $callback = function ( $pk, array $extra ) {
343 return [ $ret, $callback ];
347 * Get WHERE condition for the actor
349 * @param IDatabase $db Database to use for quoting and list-making
350 * @param string $key A key such as "rev_user" identifying the actor
351 * field being fetched.
352 * @param UserIdentity|UserIdentity[] $users Users to test for
353 * @param bool $useId If false, don't try to query by the user ID.
354 * Intended for use with rc_user since it has an index on
355 * (rc_user_text,rc_timestamp) but not (rc_user,rc_timestamp).
356 * @return array With three keys:
357 * - tables: (string[]) to include in the `$table` to `IDatabase->select()`
358 * - conds: (string) to include in the `$cond` to `IDatabase->select()`
359 * - orconds: (array[]) array of alternatives in case a union of multiple
360 * queries would be more efficient than a query with OR. May have keys
361 * 'actor', 'userid', 'username'.
362 * Since 1.32, this is guaranteed to contain just one alternative if
363 * $users contains a single user.
364 * - joins: (array) to include in the `$join_conds` to `IDatabase->select()`
365 * All tables and joins are aliased, so `+` is safe to use.
367 public function getWhere( IDatabase
$db, $key, $users, $useId = true ) {
368 self
::checkDeprecation( $key );
374 if ( $users instanceof UserIdentity
) {
378 // Get information about all the passed users
382 foreach ( $users as $user ) {
383 if ( $useId && $user->getId() ) {
384 $ids[] = $user->getId();
386 $names[] = $user->getName();
388 $actorId = $user->getActorId();
390 $actors[] = $actorId;
394 list( $text, $actor ) = self
::getFieldNames( $key );
396 // Combine data into conditions to be ORed together
397 if ( $this->stage
& SCHEMA_COMPAT_READ_NEW
) {
399 if ( isset( self
::$tempTables[$key] ) ) {
400 $t = self
::$tempTables[$key];
401 $alias = "temp_$key";
402 $tables[$alias] = $t['table'];
403 $joins[$alias] = [ 'JOIN', "{$alias}.{$t['pk']} = {$t['joinPK']}" ];
404 $joinField = "{$alias}.{$t['field']}";
408 $conds['actor'] = $db->makeList( [ $joinField => $actors ], IDatabase
::LIST_AND
);
412 $conds['userid'] = $db->makeList( [ $key => $ids ], IDatabase
::LIST_AND
);
415 $conds['username'] = $db->makeList( [ $text => $names ], IDatabase
::LIST_AND
);
421 'conds' => $conds ?
$db->makeList( array_values( $conds ), IDatabase
::LIST_OR
) : '1=0',