includes/ActorMigration.php

   1 <?php
   2 /**
   3  * Methods to help with the actor table migration
   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
  23 use MediaWiki\MediaWikiServices;
  24 use MediaWiki\User\UserIdentity;
  25 use Wikimedia\Rdbms\IDatabase;
  26
  27 /**
  28  * This class handles the logic for the actor table migration.
  29  *
  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.
  32  *
  33  * @since 1.31
  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.
  37  */
  38 class ActorMigration {
  39
  40         /**
  41          * Constant for extensions to feature-test whether $wgActorTableSchemaMigrationStage
  42          * (in MW <1.34) expects MIGRATION_* or SCHEMA_COMPAT_*
  43          */
  44         const MIGRATION_STAGE_SCHEMA_COMPAT = 1;
  45
  46         /**
  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
  53          */
  54         private static $tempTables = [
  55                 'rev_user' => [
  56                         'table' => 'revision_actor_temp',
  57                         'pk' => 'revactor_rev',
  58                         'field' => 'revactor_actor',
  59                         'joinPK' => 'rev_id',
  60                         'extra' => [
  61                                 'revactor_timestamp' => 'rev_timestamp',
  62                                 'revactor_page' => 'rev_page',
  63                         ],
  64                 ],
  65         ];
  66
  67         /**
  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.
  71          */
  72         private static $formerTempTables = [];
  73
  74         /**
  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.
  78          */
  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
  87         ];
  88
  89         /**
  90          * Define fields that are removed for use with this class.
  91          * @var string[] Keys are '$key', value is the MediaWiki version in which
  92          *  use was removed.
  93          */
  94         private static $removed = [];
  95
  96         /**
  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)
 100          */
 101         private static $specialFields = [
 102                 'ipb_by' => [ 'ipb_by_text', 'ipb_by_actor' ],
 103         ];
 104
 105         /** @var array|null Cache for `self::getJoin()` */
 106         private $joinCache = null;
 107
 108         /** @var int Combination of SCHEMA_COMPAT_* constants */
 109         private $stage;
 110
 111         /** @private */
 112         public function __construct( $stage ) {
 113                 if ( ( $stage & SCHEMA_COMPAT_WRITE_BOTH ) === 0 ) {
 114                         throw new InvalidArgumentException( '$stage must include a write mode' );
 115                 }
 116                 if ( ( $stage & SCHEMA_COMPAT_READ_BOTH ) === 0 ) {
 117                         throw new InvalidArgumentException( '$stage must include a read mode' );
 118                 }
 119                 if ( ( $stage & SCHEMA_COMPAT_READ_BOTH ) === SCHEMA_COMPAT_READ_BOTH ) {
 120                         throw new InvalidArgumentException( 'Cannot read both schemas' );
 121                 }
 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' );
 124                 }
 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' );
 127                 }
 128
 129                 $this->stage = $stage;
 130         }
 131
 132         /**
 133          * Static constructor
 134          * @return ActorMigration
 135          */
 136         public static function newMigration() {
 137                 return MediaWikiServices::getInstance()->getActorMigration();
 138         }
 139
 140         /**
 141          * Issue deprecation warning/error as appropriate.
 142          * @param string $key
 143          */
 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]
 148                         );
 149                 }
 150                 if ( !empty( self::$deprecated[$key] ) ) {
 151                         wfDeprecated( static::class . " for '$key'", self::$deprecated[$key], false, 3 );
 152                 }
 153         }
 154
 155         /**
 156          * Return an SQL condition to test if a user field is anonymous
 157          * @param string $field Field name or SQL fragment
 158          * @return string
 159          */
 160         public function isAnon( $field ) {
 161                 return ( $this->stage & SCHEMA_COMPAT_READ_NEW ) ? "$field IS NULL" : "$field = 0";
 162         }
 163
 164         /**
 165          * Return an SQL condition to test if a user field is non-anonymous
 166          * @param string $field Field name or SQL fragment
 167          * @return string
 168          */
 169         public function isNotAnon( $field ) {
 170                 return ( $this->stage & SCHEMA_COMPAT_READ_NEW ) ? "$field IS NOT NULL" : "$field != 0";
 171         }
 172
 173         /**
 174          * @param string $key A key such as "rev_user" identifying the actor
 175          *  field being fetched.
 176          * @return string[] [ $text, $actor ]
 177          */
 178         private static function getFieldNames( $key ) {
 179                 return self::$specialFields[$key] ?? [ $key . '_text', substr( $key, 0, -5 ) . '_actor' ];
 180         }
 181
 182         /**
 183          * Get SELECT fields and joins for the actor key
 184          *
 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}
 193          */
 194         public function getJoin( $key ) {
 195                 self::checkDeprecation( $key );
 196
 197                 if ( !isset( $this->joinCache[$key] ) ) {
 198                         $tables = [];
 199                         $fields = [];
 200                         $joins = [];
 201
 202                         list( $text, $actor ) = self::getFieldNames( $key );
 203
 204                         if ( $this->stage & SCHEMA_COMPAT_READ_OLD ) {
 205                                 $fields[$key] = $key;
 206                                 $fields[$text] = $text;
 207                                 $fields[$actor] = 'NULL';
 208                         } else {
 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']}";
 215                                 } else {
 216                                         $joinField = $actor;
 217                                 }
 218
 219                                 $alias = "actor_$key";
 220                                 $tables[$alias] = 'actor';
 221                                 $joins[$alias] = [ 'JOIN', "{$alias}.actor_id = {$joinField}" ];
 222
 223                                 $fields[$key] = "{$alias}.actor_user";
 224                                 $fields[$text] = "{$alias}.actor_name";
 225                                 $fields[$actor] = $joinField;
 226                         }
 227
 228                         $this->joinCache[$key] = [
 229                                 'tables' => $tables,
 230                                 'fields' => $fields,
 231                                 'joins' => $joins,
 232                         ];
 233                 }
 234
 235                 return $this->joinCache[$key];
 236         }
 237
 238         /**
 239          * Get UPDATE fields for the actor
 240          *
 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()`
 246          */
 247         public function getInsertValues( IDatabase $dbw, $key, UserIdentity $user ) {
 248                 self::checkDeprecation( $key );
 249
 250                 if ( isset( self::$tempTables[$key] ) ) {
 251                         throw new InvalidArgumentException( "Must use getInsertValuesWithTempTable() for $key" );
 252                 }
 253
 254                 list( $text, $actor ) = self::getFieldNames( $key );
 255                 $ret = [];
 256                 if ( $this->stage & SCHEMA_COMPAT_WRITE_OLD ) {
 257                         $ret[$key] = $user->getId();
 258                         $ret[$text] = $user->getName();
 259                 }
 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 );
 264                         }
 265                         $ret[$actor] = $user->getActorId( $dbw );
 266                 }
 267                 return $ret;
 268         }
 269
 270         /**
 271          * Get UPDATE fields for the actor
 272          *
 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.
 281          */
 282         public function getInsertValuesWithTempTable( IDatabase $dbw, $key, UserIdentity $user ) {
 283                 self::checkDeprecation( $key );
 284
 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" );
 289                 }
 290
 291                 list( $text, $actor ) = self::getFieldNames( $key );
 292                 $ret = [];
 293                 $callback = null;
 294                 if ( $this->stage & SCHEMA_COMPAT_WRITE_OLD ) {
 295                         $ret[$key] = $user->getId();
 296                         $ret[$text] = $user->getName();
 297                 }
 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 );
 302                         }
 303                         $id = $user->getActorId( $dbw );
 304
 305                         if ( isset( self::$tempTables[$key] ) ) {
 306                                 $func = __METHOD__;
 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" );
 313                                                 }
 314                                                 $set[$to] = $extra[$from];
 315                                         }
 316                                         $dbw->upsert(
 317                                                 $t['table'],
 318                                                 [ $t['pk'] => $pk ] + $set,
 319                                                 [ $t['pk'] ],
 320                                                 $set,
 321                                                 $func
 322                                         );
 323                                 };
 324                         } else {
 325                                 $ret[$actor] = $id;
 326                                 $callback = function ( $pk, array $extra ) {
 327                                 };
 328                         }
 329                 } elseif ( isset( self::$tempTables[$key] ) ) {
 330                         $func = __METHOD__;
 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" );
 336                                         }
 337                                 }
 338                         };
 339                 } else {
 340                         $callback = function ( $pk, array $extra ) {
 341                         };
 342                 }
 343                 return [ $ret, $callback ];
 344         }
 345
 346         /**
 347          * Get WHERE condition for the actor
 348          *
 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.
 366          */
 367         public function getWhere( IDatabase $db, $key, $users, $useId = true ) {
 368                 self::checkDeprecation( $key );
 369
 370                 $tables = [];
 371                 $conds = [];
 372                 $joins = [];
 373
 374                 if ( $users instanceof UserIdentity ) {
 375                         $users = [ $users ];
 376                 }
 377
 378                 // Get information about all the passed users
 379                 $ids = [];
 380                 $names = [];
 381                 $actors = [];
 382                 foreach ( $users as $user ) {
 383                         if ( $useId && $user->getId() ) {
 384                                 $ids[] = $user->getId();
 385                         } else {
 386                                 $names[] = $user->getName();
 387                         }
 388                         $actorId = $user->getActorId();
 389                         if ( $actorId ) {
 390                                 $actors[] = $actorId;
 391                         }
 392                 }
 393
 394                 list( $text, $actor ) = self::getFieldNames( $key );
 395
 396                 // Combine data into conditions to be ORed together
 397                 if ( $this->stage & SCHEMA_COMPAT_READ_NEW ) {
 398                         if ( $actors ) {
 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']}";
 405                                 } else {
 406                                         $joinField = $actor;
 407                                 }
 408                                 $conds['actor'] = $db->makeList( [ $joinField => $actors ], IDatabase::LIST_AND );
 409                         }
 410                 } else {
 411                         if ( $ids ) {
 412                                 $conds['userid'] = $db->makeList( [ $key => $ids ], IDatabase::LIST_AND );
 413                         }
 414                         if ( $names ) {
 415                                 $conds['username'] = $db->makeList( [ $text => $names ], IDatabase::LIST_AND );
 416                         }
 417                 }
 418
 419                 return [
 420                         'tables' => $tables,
 421                         'conds' => $conds ? $db->makeList( array_values( $conds ), IDatabase::LIST_OR ) : '1=0',
 422                         'orconds' => $conds,
 423                         'joins' => $joins,
 424                 ];
 425         }
 426
 427 }