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 along with $wgActorTableSchemaMigrationStage.
  32  *
  33  * @since 1.31
  34  */
  35 class ActorMigration {
  36
  37         /**
  38          * Constant for extensions to feature-test whether $wgActorTableSchemaMigrationStage
  39          * expects MIGRATION_* or SCHEMA_COMPAT_*
  40          */
  41         const MIGRATION_STAGE_SCHEMA_COMPAT = 1;
  42
  43         /**
  44          * Define fields that use temporary tables for transitional purposes
  45          * @var array Keys are '$key', values are arrays with four fields:
  46          *  - table: Temporary table name
  47          *  - pk: Temporary table column referring to the main table's primary key
  48          *  - field: Temporary table column referring actor.actor_id
  49          *  - joinPK: Main table's primary key
  50          */
  51         private static $tempTables = [
  52                 'rev_user' => [
  53                         'table' => 'revision_actor_temp',
  54                         'pk' => 'revactor_rev',
  55                         'field' => 'revactor_actor',
  56                         'joinPK' => 'rev_id',
  57                         'extra' => [
  58                                 'revactor_timestamp' => 'rev_timestamp',
  59                                 'revactor_page' => 'rev_page',
  60                         ],
  61                 ],
  62         ];
  63
  64         /**
  65          * Fields that formerly used $tempTables
  66          * @var array Key is '$key', value is the MediaWiki version in which it was
  67          *  removed from $tempTables.
  68          */
  69         private static $formerTempTables = [];
  70
  71         /**
  72          * Define fields that use non-standard mapping
  73          * @var array Keys are the user id column name, values are arrays with two
  74          *  elements (the user text column name and the actor id column name)
  75          */
  76         private static $specialFields = [
  77                 'ipb_by' => [ 'ipb_by_text', 'ipb_by_actor' ],
  78         ];
  79
  80         /** @var array|null Cache for `self::getJoin()` */
  81         private $joinCache = null;
  82
  83         /** @var int Combination of SCHEMA_COMPAT_* constants */
  84         private $stage;
  85
  86         /** @private */
  87         public function __construct( $stage ) {
  88                 if ( ( $stage & SCHEMA_COMPAT_WRITE_BOTH ) === 0 ) {
  89                         throw new InvalidArgumentException( '$stage must include a write mode' );
  90                 }
  91                 if ( ( $stage & SCHEMA_COMPAT_READ_BOTH ) === 0 ) {
  92                         throw new InvalidArgumentException( '$stage must include a read mode' );
  93                 }
  94                 if ( ( $stage & SCHEMA_COMPAT_READ_BOTH ) === SCHEMA_COMPAT_READ_BOTH ) {
  95                         throw new InvalidArgumentException( 'Cannot read both schemas' );
  96                 }
  97                 if ( ( $stage & SCHEMA_COMPAT_READ_OLD ) && !( $stage & SCHEMA_COMPAT_WRITE_OLD ) ) {
  98                         throw new InvalidArgumentException( 'Cannot read the old schema without also writing it' );
  99                 }
 100                 if ( ( $stage & SCHEMA_COMPAT_READ_NEW ) && !( $stage & SCHEMA_COMPAT_WRITE_NEW ) ) {
 101                         throw new InvalidArgumentException( 'Cannot read the new schema without also writing it' );
 102                 }
 103
 104                 $this->stage = $stage;
 105         }
 106
 107         /**
 108          * Static constructor
 109          * @return ActorMigration
 110          */
 111         public static function newMigration() {
 112                 return MediaWikiServices::getInstance()->getActorMigration();
 113         }
 114
 115         /**
 116          * Return an SQL condition to test if a user field is anonymous
 117          * @param string $field Field name or SQL fragment
 118          * @return string
 119          */
 120         public function isAnon( $field ) {
 121                 return ( $this->stage & SCHEMA_COMPAT_READ_NEW ) ? "$field IS NULL" : "$field = 0";
 122         }
 123
 124         /**
 125          * Return an SQL condition to test if a user field is non-anonymous
 126          * @param string $field Field name or SQL fragment
 127          * @return string
 128          */
 129         public function isNotAnon( $field ) {
 130                 return ( $this->stage & SCHEMA_COMPAT_READ_NEW ) ? "$field IS NOT NULL" : "$field != 0";
 131         }
 132
 133         /**
 134          * @param string $key A key such as "rev_user" identifying the actor
 135          *  field being fetched.
 136          * @return string[] [ $text, $actor ]
 137          */
 138         private static function getFieldNames( $key ) {
 139                 if ( isset( self::$specialFields[$key] ) ) {
 140                         return self::$specialFields[$key];
 141                 }
 142
 143                 return [ $key . '_text', substr( $key, 0, -5 ) . '_actor' ];
 144         }
 145
 146         /**
 147          * Get SELECT fields and joins for the actor key
 148          *
 149          * @param string $key A key such as "rev_user" identifying the actor
 150          *  field being fetched.
 151          * @return array With three keys:
 152          *   - tables: (string[]) to include in the `$table` to `IDatabase->select()`
 153          *   - fields: (string[]) to include in the `$vars` to `IDatabase->select()`
 154          *   - joins: (array) to include in the `$join_conds` to `IDatabase->select()`
 155          *  All tables, fields, and joins are aliased, so `+` is safe to use.
 156          */
 157         public function getJoin( $key ) {
 158                 if ( !isset( $this->joinCache[$key] ) ) {
 159                         $tables = [];
 160                         $fields = [];
 161                         $joins = [];
 162
 163                         list( $text, $actor ) = self::getFieldNames( $key );
 164
 165                         if ( $this->stage & SCHEMA_COMPAT_READ_OLD ) {
 166                                 $fields[$key] = $key;
 167                                 $fields[$text] = $text;
 168                                 $fields[$actor] = 'NULL';
 169                         } else {
 170                                 if ( isset( self::$tempTables[$key] ) ) {
 171                                         $t = self::$tempTables[$key];
 172                                         $alias = "temp_$key";
 173                                         $tables[$alias] = $t['table'];
 174                                         $joins[$alias] = [ 'JOIN', "{$alias}.{$t['pk']} = {$t['joinPK']}" ];
 175                                         $joinField = "{$alias}.{$t['field']}";
 176                                 } else {
 177                                         $joinField = $actor;
 178                                 }
 179
 180                                 $alias = "actor_$key";
 181                                 $tables[$alias] = 'actor';
 182                                 $joins[$alias] = [ 'JOIN', "{$alias}.actor_id = {$joinField}" ];
 183
 184                                 $fields[$key] = "{$alias}.actor_user";
 185                                 $fields[$text] = "{$alias}.actor_name";
 186                                 $fields[$actor] = $joinField;
 187                         }
 188
 189                         $this->joinCache[$key] = [
 190                                 'tables' => $tables,
 191                                 'fields' => $fields,
 192                                 'joins' => $joins,
 193                         ];
 194                 }
 195
 196                 return $this->joinCache[$key];
 197         }
 198
 199         /**
 200          * Get UPDATE fields for the actor
 201          *
 202          * @param IDatabase $dbw Database to use for creating an actor ID, if necessary
 203          * @param string $key A key such as "rev_user" identifying the actor
 204          *  field being fetched.
 205          * @param UserIdentity $user User to set in the update
 206          * @return array to merge into `$values` to `IDatabase->update()` or `$a` to `IDatabase->insert()`
 207          */
 208         public function getInsertValues( IDatabase $dbw, $key, UserIdentity $user ) {
 209                 if ( isset( self::$tempTables[$key] ) ) {
 210                         throw new InvalidArgumentException( "Must use getInsertValuesWithTempTable() for $key" );
 211                 }
 212
 213                 list( $text, $actor ) = self::getFieldNames( $key );
 214                 $ret = [];
 215                 if ( $this->stage & SCHEMA_COMPAT_WRITE_OLD ) {
 216                         $ret[$key] = $user->getId();
 217                         $ret[$text] = $user->getName();
 218                 }
 219                 if ( $this->stage & SCHEMA_COMPAT_WRITE_NEW ) {
 220                         // We need to be able to assign an actor ID if none exists
 221                         if ( !$user instanceof User && !$user->getActorId() ) {
 222                                 $user = User::newFromAnyId( $user->getId(), $user->getName(), null );
 223                         }
 224                         $ret[$actor] = $user->getActorId( $dbw );
 225                 }
 226                 return $ret;
 227         }
 228
 229         /**
 230          * Get UPDATE fields for the actor
 231          *
 232          * @param IDatabase $dbw Database to use for creating an actor ID, if necessary
 233          * @param string $key A key such as "rev_user" identifying the actor
 234          *  field being fetched.
 235          * @param UserIdentity $user User to set in the update
 236          * @return array with two values:
 237          *  - array to merge into `$values` to `IDatabase->update()` or `$a` to `IDatabase->insert()`
 238          *  - callback to call with the primary key for the main table insert
 239          *    and extra fields needed for the temp table.
 240          */
 241         public function getInsertValuesWithTempTable( IDatabase $dbw, $key, UserIdentity $user ) {
 242                 if ( isset( self::$formerTempTables[$key] ) ) {
 243                         wfDeprecated( __METHOD__ . " for $key", self::$formerTempTables[$key] );
 244                 } elseif ( !isset( self::$tempTables[$key] ) ) {
 245                         throw new InvalidArgumentException( "Must use getInsertValues() for $key" );
 246                 }
 247
 248                 list( $text, $actor ) = self::getFieldNames( $key );
 249                 $ret = [];
 250                 $callback = null;
 251                 if ( $this->stage & SCHEMA_COMPAT_WRITE_OLD ) {
 252                         $ret[$key] = $user->getId();
 253                         $ret[$text] = $user->getName();
 254                 }
 255                 if ( $this->stage & SCHEMA_COMPAT_WRITE_NEW ) {
 256                         // We need to be able to assign an actor ID if none exists
 257                         if ( !$user instanceof User && !$user->getActorId() ) {
 258                                 $user = User::newFromAnyId( $user->getId(), $user->getName(), null );
 259                         }
 260                         $id = $user->getActorId( $dbw );
 261
 262                         if ( isset( self::$tempTables[$key] ) ) {
 263                                 $func = __METHOD__;
 264                                 $callback = function ( $pk, array $extra ) use ( $dbw, $key, $id, $func ) {
 265                                         $t = self::$tempTables[$key];
 266                                         $set = [ $t['field'] => $id ];
 267                                         foreach ( $t['extra'] as $to => $from ) {
 268                                                 if ( !array_key_exists( $from, $extra ) ) {
 269                                                         throw new InvalidArgumentException( "$func callback: \$extra[$from] is not provided" );
 270                                                 }
 271                                                 $set[$to] = $extra[$from];
 272                                         }
 273                                         $dbw->upsert(
 274                                                 $t['table'],
 275                                                 [ $t['pk'] => $pk ] + $set,
 276                                                 [ $t['pk'] ],
 277                                                 $set,
 278                                                 $func
 279                                         );
 280                                 };
 281                         } else {
 282                                 $ret[$actor] = $id;
 283                                 $callback = function ( $pk, array $extra ) {
 284                                 };
 285                         }
 286                 } elseif ( isset( self::$tempTables[$key] ) ) {
 287                         $func = __METHOD__;
 288                         $callback = function ( $pk, array $extra ) use ( $key, $func ) {
 289                                 $t = self::$tempTables[$key];
 290                                 foreach ( $t['extra'] as $to => $from ) {
 291                                         if ( !array_key_exists( $from, $extra ) ) {
 292                                                 throw new InvalidArgumentException( "$func callback: \$extra[$from] is not provided" );
 293                                         }
 294                                 }
 295                         };
 296                 } else {
 297                         $callback = function ( $pk, array $extra ) {
 298                         };
 299                 }
 300                 return [ $ret, $callback ];
 301         }
 302
 303         /**
 304          * Get WHERE condition for the actor
 305          *
 306          * @param IDatabase $db Database to use for quoting and list-making
 307          * @param string $key A key such as "rev_user" identifying the actor
 308          *  field being fetched.
 309          * @param UserIdentity|UserIdentity[] $users Users to test for
 310          * @param bool $useId If false, don't try to query by the user ID.
 311          *  Intended for use with rc_user since it has an index on
 312          *  (rc_user_text,rc_timestamp) but not (rc_user,rc_timestamp).
 313          * @return array With three keys:
 314          *   - tables: (string[]) to include in the `$table` to `IDatabase->select()`
 315          *   - conds: (string) to include in the `$cond` to `IDatabase->select()`
 316          *   - orconds: (array[]) array of alternatives in case a union of multiple
 317          *     queries would be more efficient than a query with OR. May have keys
 318          *     'actor', 'userid', 'username'.
 319          *     Since 1.32, this is guaranteed to contain just one alternative if
 320          *     $users contains a single user.
 321          *   - joins: (array) to include in the `$join_conds` to `IDatabase->select()`
 322          *  All tables and joins are aliased, so `+` is safe to use.
 323          */
 324         public function getWhere( IDatabase $db, $key, $users, $useId = true ) {
 325                 $tables = [];
 326                 $conds = [];
 327                 $joins = [];
 328
 329                 if ( $users instanceof UserIdentity ) {
 330                         $users = [ $users ];
 331                 }
 332
 333                 // Get information about all the passed users
 334                 $ids = [];
 335                 $names = [];
 336                 $actors = [];
 337                 foreach ( $users as $user ) {
 338                         if ( $useId && $user->getId() ) {
 339                                 $ids[] = $user->getId();
 340                         } else {
 341                                 $names[] = $user->getName();
 342                         }
 343                         $actorId = $user->getActorId();
 344                         if ( $actorId ) {
 345                                 $actors[] = $actorId;
 346                         }
 347                 }
 348
 349                 list( $text, $actor ) = self::getFieldNames( $key );
 350
 351                 // Combine data into conditions to be ORed together
 352                 if ( $this->stage & SCHEMA_COMPAT_READ_NEW ) {
 353                         if ( $actors ) {
 354                                 if ( isset( self::$tempTables[$key] ) ) {
 355                                         $t = self::$tempTables[$key];
 356                                         $alias = "temp_$key";
 357                                         $tables[$alias] = $t['table'];
 358                                         $joins[$alias] = [ 'JOIN', "{$alias}.{$t['pk']} = {$t['joinPK']}" ];
 359                                         $joinField = "{$alias}.{$t['field']}";
 360                                 } else {
 361                                         $joinField = $actor;
 362                                 }
 363                                 $conds['actor'] = $db->makeList( [ $joinField => $actors ], IDatabase::LIST_AND );
 364                         }
 365                 } else {
 366                         if ( $ids ) {
 367                                 $conds['userid'] = $db->makeList( [ $key => $ids ], IDatabase::LIST_AND );
 368                         }
 369                         if ( $names ) {
 370                                 $conds['username'] = $db->makeList( [ $text => $names ], IDatabase::LIST_AND );
 371                         }
 372                 }
 373
 374                 return [
 375                         'tables' => $tables,
 376                         'conds' => $conds ? $db->makeList( array_values( $conds ), IDatabase::LIST_OR ) : '1=0',
 377                         'orconds' => $conds,
 378                         'joins' => $joins,
 379                 ];
 380         }
 381
 382 }