maintenance/Maintenance.php

   1 <?php
   2 /**
   3  * This program is free software; you can redistribute it and/or modify
   4  * it under the terms of the GNU General Public License as published by
   5  * the Free Software Foundation; either version 2 of the License, or
   6  * (at your option) any later version.
   7  *
   8  * This program is distributed in the hope that it will be useful,
   9  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  10  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  11  * GNU General Public License for more details.
  12  *
  13  * You should have received a copy of the GNU General Public License along
  14  * with this program; if not, write to the Free Software Foundation, Inc.,
  15  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  16  * http://www.gnu.org/copyleft/gpl.html
  17  *
  18  * @file
  19  * @ingroup Maintenance
  20  * @defgroup Maintenance Maintenance
  21  */
  22
  23 define( MW_ENTRY_POINT, 'cli' );
  24
  25 // Bail on old versions of PHP, or if composer has not been run yet to install
  26 // dependencies.
  27 require_once __DIR__ . '/../includes/PHPVersionCheck.php';
  28 wfEntryPointCheck( 'text' );
  29
  30 use MediaWiki\Shell\Shell;
  31 use Wikimedia\Rdbms\IResultWrapper;
  32
  33 /**
  34  * @defgroup MaintenanceArchive Maintenance archives
  35  * @ingroup Maintenance
  36  */
  37
  38 // Define this so scripts can easily find doMaintenance.php
  39 define( 'RUN_MAINTENANCE_IF_MAIN', __DIR__ . '/doMaintenance.php' );
  40
  41 /**
  42  * @deprecated since 1.31
  43  */
  44 define( 'DO_MAINTENANCE', RUN_MAINTENANCE_IF_MAIN ); // original name, harmless
  45
  46 $maintClass = false;
  47
  48 // Some extensions rely on MW_INSTALL_PATH to find core files to include. Setting it here helps them
  49 // if they're included by a core script (like DatabaseUpdater) after Maintenance.php has already
  50 // been run.
  51 if ( strval( getenv( 'MW_INSTALL_PATH' ) ) === '' ) {
  52         putenv( 'MW_INSTALL_PATH=' . realpath( __DIR__ . '/..' ) );
  53 }
  54
  55 use Wikimedia\Rdbms\IDatabase;
  56 use MediaWiki\Logger\LoggerFactory;
  57 use MediaWiki\MediaWikiServices;
  58 use Wikimedia\Rdbms\LBFactory;
  59 use Wikimedia\Rdbms\IMaintainableDatabase;
  60
  61 /**
  62  * Abstract maintenance class for quickly writing and churning out
  63  * maintenance scripts with minimal effort. All that _must_ be defined
  64  * is the execute() method. See docs/maintenance.txt for more info
  65  * and a quick demo of how to use it.
  66  *
  67  * Terminology:
  68  *   params: registry of named values that may be passed to the script
  69  *   arg list: registry of positional values that may be passed to the script
  70  *   options: passed param values
  71  *   args: passed positional values
  72  *
  73  * In the command:
  74  *   mwscript somescript.php --foo=bar baz
  75  * foo is a param
  76  * bar is the option value of the option for param foo
  77  * baz is the arg value at index 0 in the arg list
  78  *
  79  * @since 1.16
  80  * @ingroup Maintenance
  81  */
  82 abstract class Maintenance {
  83         /**
  84          * Constants for DB access type
  85          * @see Maintenance::getDbType()
  86          */
  87         const DB_NONE = 0;
  88         const DB_STD = 1;
  89         const DB_ADMIN = 2;
  90
  91         // Const for getStdin()
  92         const STDIN_ALL = 'all';
  93
  94         // Array of desired/allowed params
  95         protected $mParams = [];
  96
  97         // Array of mapping short parameters to long ones
  98         protected $mShortParamsMap = [];
  99
 100         // Array of desired/allowed args
 101         protected $mArgList = [];
 102
 103         // This is the list of options that were actually passed
 104         protected $mOptions = [];
 105
 106         // This is the list of arguments that were actually passed
 107         protected $mArgs = [];
 108
 109         // Allow arbitrary options to be passed, or only specified ones?
 110         protected $mAllowUnregisteredOptions = false;
 111
 112         // Name of the script currently running
 113         protected $mSelf;
 114
 115         // Special vars for params that are always used
 116         protected $mQuiet = false;
 117         protected $mDbUser, $mDbPass;
 118
 119         // A description of the script, children should change this via addDescription()
 120         protected $mDescription = '';
 121
 122         // Have we already loaded our user input?
 123         protected $mInputLoaded = false;
 124
 125         /**
 126          * Batch size. If a script supports this, they should set
 127          * a default with setBatchSize()
 128          *
 129          * @var int
 130          */
 131         protected $mBatchSize = null;
 132
 133         // Generic options added by addDefaultParams()
 134         private $mGenericParameters = [];
 135         // Generic options which might or not be supported by the script
 136         private $mDependantParameters = [];
 137
 138         /**
 139          * Used by getDB() / setDB()
 140          * @var IMaintainableDatabase
 141          */
 142         private $mDb = null;
 143
 144         /** @var float UNIX timestamp */
 145         private $lastReplicationWait = 0.0;
 146
 147         /**
 148          * Used when creating separate schema files.
 149          * @var resource
 150          */
 151         public $fileHandle;
 152
 153         /**
 154          * Accessible via getConfig()
 155          *
 156          * @var Config
 157          */
 158         private $config;
 159
 160         /**
 161          * @see Maintenance::requireExtension
 162          * @var array
 163          */
 164         private $requiredExtensions = [];
 165
 166         /**
 167          * Used to read the options in the order they were passed.
 168          * Useful for option chaining (Ex. dumpBackup.php). It will
 169          * be an empty array if the options are passed in through
 170          * loadParamsAndArgs( $self, $opts, $args ).
 171          *
 172          * This is an array of arrays where
 173          * 0 => the option and 1 => parameter value.
 174          *
 175          * @var array
 176          */
 177         public $orderedOptions = [];
 178
 179         /**
 180          * Default constructor. Children should call this *first* if implementing
 181          * their own constructors
 182          */
 183         public function __construct() {
 184                 global $IP;
 185                 $IP = getenv( 'MW_INSTALL_PATH' );
 186
 187                 $this->addDefaultParams();
 188                 register_shutdown_function( [ $this, 'outputChanneled' ], false );
 189         }
 190
 191         /**
 192          * Should we execute the maintenance script, or just allow it to be included
 193          * as a standalone class? It checks that the call stack only includes this
 194          * function and "requires" (meaning was called from the file scope)
 195          *
 196          * @return bool
 197          */
 198         public static function shouldExecute() {
 199                 global $wgCommandLineMode;
 200
 201                 if ( !function_exists( 'debug_backtrace' ) ) {
 202                         // If someone has a better idea...
 203                         return $wgCommandLineMode;
 204                 }
 205
 206                 $bt = debug_backtrace();
 207                 $count = count( $bt );
 208                 if ( $count < 2 ) {
 209                         return false; // sanity
 210                 }
 211                 if ( $bt[0]['class'] !== self::class || $bt[0]['function'] !== 'shouldExecute' ) {
 212                         return false; // last call should be to this function
 213                 }
 214                 $includeFuncs = [ 'require_once', 'require', 'include', 'include_once' ];
 215                 for ( $i = 1; $i < $count; $i++ ) {
 216                         if ( !in_array( $bt[$i]['function'], $includeFuncs ) ) {
 217                                 return false; // previous calls should all be "requires"
 218                         }
 219                 }
 220
 221                 return true;
 222         }
 223
 224         /**
 225          * Do the actual work. All child classes will need to implement this
 226          *
 227          * @return bool|null|void True for success, false for failure. Not returning
 228          *   a value, or returning null, is also interpreted as success. Returning
 229          *   false for failure will cause doMaintenance.php to exit the process
 230          *   with a non-zero exit status.
 231          */
 232         abstract public function execute();
 233
 234         /**
 235          * Checks to see if a particular option in supported.  Normally this means it
 236          * has been registered by the script via addOption.
 237          * @param string $name The name of the option
 238          * @return bool true if the option exists, false otherwise
 239          */
 240         protected function supportsOption( $name ) {
 241                 return isset( $this->mParams[$name] );
 242         }
 243
 244         /**
 245          * Add a parameter to the script. Will be displayed on --help
 246          * with the associated description
 247          *
 248          * @param string $name The name of the param (help, version, etc)
 249          * @param string $description The description of the param to show on --help
 250          * @param bool $required Is the param required?
 251          * @param bool $withArg Is an argument required with this option?
 252          * @param string|bool $shortName Character to use as short name
 253          * @param bool $multiOccurrence Can this option be passed multiple times?
 254          */
 255         protected function addOption( $name, $description, $required = false,
 256                 $withArg = false, $shortName = false, $multiOccurrence = false
 257         ) {
 258                 $this->mParams[$name] = [
 259                         'desc' => $description,
 260                         'require' => $required,
 261                         'withArg' => $withArg,
 262                         'shortName' => $shortName,
 263                         'multiOccurrence' => $multiOccurrence
 264                 ];
 265
 266                 if ( $shortName !== false ) {
 267                         $this->mShortParamsMap[$shortName] = $name;
 268                 }
 269         }
 270
 271         /**
 272          * Checks to see if a particular option exists.
 273          * @param string $name The name of the option
 274          * @return bool
 275          */
 276         protected function hasOption( $name ) {
 277                 return isset( $this->mOptions[$name] );
 278         }
 279
 280         /**
 281          * Get an option, or return the default.
 282          *
 283          * If the option was added to support multiple occurrences,
 284          * this will return an array.
 285          *
 286          * @param string $name The name of the param
 287          * @param mixed|null $default Anything you want, default null
 288          * @return mixed
 289          */
 290         protected function getOption( $name, $default = null ) {
 291                 if ( $this->hasOption( $name ) ) {
 292                         return $this->mOptions[$name];
 293                 } else {
 294                         // Set it so we don't have to provide the default again
 295                         $this->mOptions[$name] = $default;
 296
 297                         return $this->mOptions[$name];
 298                 }
 299         }
 300
 301         /**
 302          * Add some args that are needed
 303          * @param string $arg Name of the arg, like 'start'
 304          * @param string $description Short description of the arg
 305          * @param bool $required Is this required?
 306          */
 307         protected function addArg( $arg, $description, $required = true ) {
 308                 $this->mArgList[] = [
 309                         'name' => $arg,
 310                         'desc' => $description,
 311                         'require' => $required
 312                 ];
 313         }
 314
 315         /**
 316          * Remove an option.  Useful for removing options that won't be used in your script.
 317          * @param string $name The option to remove.
 318          */
 319         protected function deleteOption( $name ) {
 320                 unset( $this->mParams[$name] );
 321         }
 322
 323         /**
 324          * Sets whether to allow unregistered options, which are options passed to
 325          * a script that do not match an expected parameter.
 326          * @param bool $allow Should we allow?
 327          */
 328         protected function setAllowUnregisteredOptions( $allow ) {
 329                 $this->mAllowUnregisteredOptions = $allow;
 330         }
 331
 332         /**
 333          * Set the description text.
 334          * @param string $text The text of the description
 335          */
 336         protected function addDescription( $text ) {
 337                 $this->mDescription = $text;
 338         }
 339
 340         /**
 341          * Does a given argument exist?
 342          * @param int $argId The integer value (from zero) for the arg
 343          * @return bool
 344          */
 345         protected function hasArg( $argId = 0 ) {
 346                 if ( func_num_args() === 0 ) {
 347                         wfDeprecated( __METHOD__ . ' without an $argId', '1.33' );
 348                 }
 349
 350                 return isset( $this->mArgs[$argId] );
 351         }
 352
 353         /**
 354          * Get an argument.
 355          * @param int $argId The integer value (from zero) for the arg
 356          * @param mixed|null $default The default if it doesn't exist
 357          * @return mixed
 358          */
 359         protected function getArg( $argId = 0, $default = null ) {
 360                 if ( func_num_args() === 0 ) {
 361                         wfDeprecated( __METHOD__ . ' without an $argId', '1.33' );
 362                 }
 363
 364                 return $this->mArgs[$argId] ?? $default;
 365         }
 366
 367         /**
 368          * Returns batch size
 369          *
 370          * @since 1.31
 371          *
 372          * @return int|null
 373          */
 374         protected function getBatchSize() {
 375                 return $this->mBatchSize;
 376         }
 377
 378         /**
 379          * Set the batch size.
 380          * @param int $s The number of operations to do in a batch
 381          */
 382         protected function setBatchSize( $s = 0 ) {
 383                 $this->mBatchSize = $s;
 384
 385                 // If we support $mBatchSize, show the option.
 386                 // Used to be in addDefaultParams, but in order for that to
 387                 // work, subclasses would have to call this function in the constructor
 388                 // before they called parent::__construct which is just weird
 389                 // (and really wasn't done).
 390                 if ( $this->mBatchSize ) {
 391                         $this->addOption( 'batch-size', 'Run this many operations ' .
 392                                 'per batch, default: ' . $this->mBatchSize, false, true );
 393                         if ( isset( $this->mParams['batch-size'] ) ) {
 394                                 // This seems a little ugly...
 395                                 $this->mDependantParameters['batch-size'] = $this->mParams['batch-size'];
 396                         }
 397                 }
 398         }
 399
 400         /**
 401          * Get the script's name
 402          * @return string
 403          */
 404         public function getName() {
 405                 return $this->mSelf;
 406         }
 407
 408         /**
 409          * Return input from stdin.
 410          * @param int|null $len The number of bytes to read. If null, just return the handle.
 411          *   Maintenance::STDIN_ALL returns the full length
 412          * @return mixed
 413          */
 414         protected function getStdin( $len = null ) {
 415                 if ( $len == self::STDIN_ALL ) {
 416                         return file_get_contents( 'php://stdin' );
 417                 }
 418                 $f = fopen( 'php://stdin', 'rt' );
 419                 if ( !$len ) {
 420                         return $f;
 421                 }
 422                 $input = fgets( $f, $len );
 423                 fclose( $f );
 424
 425                 return rtrim( $input );
 426         }
 427
 428         /**
 429          * @return bool
 430          */
 431         public function isQuiet() {
 432                 return $this->mQuiet;
 433         }
 434
 435         /**
 436          * Throw some output to the user. Scripts can call this with no fears,
 437          * as we handle all --quiet stuff here
 438          * @param string $out The text to show to the user
 439          * @param mixed|null $channel Unique identifier for the channel. See function outputChanneled.
 440          */
 441         protected function output( $out, $channel = null ) {
 442                 // This is sometimes called very early, before Setup.php is included.
 443                 if ( class_exists( MediaWikiServices::class ) ) {
 444                         // Try to periodically flush buffered metrics to avoid OOMs
 445                         $stats = MediaWikiServices::getInstance()->getStatsdDataFactory();
 446                         if ( $stats->getDataCount() > 1000 ) {
 447                                 MediaWiki::emitBufferedStatsdData( $stats, $this->getConfig() );
 448                         }
 449                 }
 450
 451                 if ( $this->mQuiet ) {
 452                         return;
 453                 }
 454                 if ( $channel === null ) {
 455                         $this->cleanupChanneled();
 456                         print $out;
 457                 } else {
 458                         $out = preg_replace( '/\n\z/', '', $out );
 459                         $this->outputChanneled( $out, $channel );
 460                 }
 461         }
 462
 463         /**
 464          * Throw an error to the user. Doesn't respect --quiet, so don't use
 465          * this for non-error output
 466          * @param string $err The error to display
 467          * @param int $die Deprecated since 1.31, use Maintenance::fatalError() instead
 468          */
 469         protected function error( $err, $die = 0 ) {
 470                 if ( intval( $die ) !== 0 ) {
 471                         wfDeprecated( __METHOD__ . '( $err, $die )', '1.31' );
 472                         $this->fatalError( $err, intval( $die ) );
 473                 }
 474                 $this->outputChanneled( false );
 475                 if (
 476                         ( PHP_SAPI == 'cli' || PHP_SAPI == 'phpdbg' ) &&
 477                         !defined( 'MW_PHPUNIT_TEST' )
 478                 ) {
 479                         fwrite( STDERR, $err . "\n" );
 480                 } else {
 481                         print $err;
 482                 }
 483         }
 484
 485         /**
 486          * Output a message and terminate the current script.
 487          *
 488          * @param string $msg Error message
 489          * @param int $exitCode PHP exit status. Should be in range 1-254.
 490          * @since 1.31
 491          */
 492         protected function fatalError( $msg, $exitCode = 1 ) {
 493                 $this->error( $msg );
 494                 exit( $exitCode );
 495         }
 496
 497         private $atLineStart = true;
 498         private $lastChannel = null;
 499
 500         /**
 501          * Clean up channeled output.  Output a newline if necessary.
 502          */
 503         public function cleanupChanneled() {
 504                 if ( !$this->atLineStart ) {
 505                         print "\n";
 506                         $this->atLineStart = true;
 507                 }
 508         }
 509
 510         /**
 511          * Message outputter with channeled message support. Messages on the
 512          * same channel are concatenated, but any intervening messages in another
 513          * channel start a new line.
 514          * @param string $msg The message without trailing newline
 515          * @param string|null $channel Channel identifier or null for no
 516          *     channel. Channel comparison uses ===.
 517          */
 518         public function outputChanneled( $msg, $channel = null ) {
 519                 if ( $msg === false ) {
 520                         $this->cleanupChanneled();
 521
 522                         return;
 523                 }
 524
 525                 // End the current line if necessary
 526                 if ( !$this->atLineStart && $channel !== $this->lastChannel ) {
 527                         print "\n";
 528                 }
 529
 530                 print $msg;
 531
 532                 $this->atLineStart = false;
 533                 if ( $channel === null ) {
 534                         // For unchanneled messages, output trailing newline immediately
 535                         print "\n";
 536                         $this->atLineStart = true;
 537                 }
 538                 $this->lastChannel = $channel;
 539         }
 540
 541         /**
 542          * Does the script need different DB access? By default, we give Maintenance
 543          * scripts normal rights to the DB. Sometimes, a script needs admin rights
 544          * access for a reason and sometimes they want no access. Subclasses should
 545          * override and return one of the following values, as needed:
 546          *    Maintenance::DB_NONE  -  For no DB access at all
 547          *    Maintenance::DB_STD   -  For normal DB access, default
 548          *    Maintenance::DB_ADMIN -  For admin DB access
 549          * @return int
 550          */
 551         public function getDbType() {
 552                 return self::DB_STD;
 553         }
 554
 555         /**
 556          * Add the default parameters to the scripts
 557          */
 558         protected function addDefaultParams() {
 559                 # Generic (non script dependant) options:
 560
 561                 $this->addOption( 'help', 'Display this help message', false, false, 'h' );
 562                 $this->addOption( 'quiet', 'Whether to suppress non-error output', false, false, 'q' );
 563                 $this->addOption( 'conf', 'Location of LocalSettings.php, if not default', false, true );
 564                 $this->addOption( 'wiki', 'For specifying the wiki ID', false, true );
 565                 $this->addOption( 'globals', 'Output globals at the end of processing for debugging' );
 566                 $this->addOption(
 567                         'memory-limit',
 568                         'Set a specific memory limit for the script, '
 569                                 . '"max" for no limit or "default" to avoid changing it',
 570                         false,
 571                         true
 572                 );
 573                 $this->addOption( 'server', "The protocol and server name to use in URLs, e.g. " .
 574                         "http://en.wikipedia.org. This is sometimes necessary because " .
 575                         "server name detection may fail in command line scripts.", false, true );
 576                 $this->addOption( 'profiler', 'Profiler output format (usually "text")', false, true );
 577                 // This is named --mwdebug, because --debug would conflict in the phpunit.php CLI script.
 578                 $this->addOption( 'mwdebug', 'Enable built-in MediaWiki development settings', false, true );
 579
 580                 # Save generic options to display them separately in help
 581                 $this->mGenericParameters = $this->mParams;
 582
 583                 # Script dependant options:
 584
 585                 // If we support a DB, show the options
 586                 if ( $this->getDbType() > 0 ) {
 587                         $this->addOption( 'dbuser', 'The DB user to use for this script', false, true );
 588                         $this->addOption( 'dbpass', 'The password to use for this script', false, true );
 589                         $this->addOption( 'dbgroupdefault', 'The default DB group to use.', false, true );
 590                 }
 591
 592                 # Save additional script dependant options to display
 593                 #  them separately in help
 594                 $this->mDependantParameters = array_diff_key( $this->mParams, $this->mGenericParameters );
 595         }
 596
 597         /**
 598          * @since 1.24
 599          * @return Config
 600          */
 601         public function getConfig() {
 602                 if ( $this->config === null ) {
 603                         $this->config = MediaWikiServices::getInstance()->getMainConfig();
 604                 }
 605
 606                 return $this->config;
 607         }
 608
 609         /**
 610          * @since 1.24
 611          * @param Config $config
 612          */
 613         public function setConfig( Config $config ) {
 614                 $this->config = $config;
 615         }
 616
 617         /**
 618          * Indicate that the specified extension must be
 619          * loaded before the script can run.
 620          *
 621          * This *must* be called in the constructor.
 622          *
 623          * @since 1.28
 624          * @param string $name
 625          */
 626         protected function requireExtension( $name ) {
 627                 $this->requiredExtensions[] = $name;
 628         }
 629
 630         /**
 631          * Verify that the required extensions are installed
 632          *
 633          * @since 1.28
 634          */
 635         public function checkRequiredExtensions() {
 636                 $registry = ExtensionRegistry::getInstance();
 637                 $missing = [];
 638                 foreach ( $this->requiredExtensions as $name ) {
 639                         if ( !$registry->isLoaded( $name ) ) {
 640                                 $missing[] = $name;
 641                         }
 642                 }
 643
 644                 if ( $missing ) {
 645                         $joined = implode( ', ', $missing );
 646                         $msg = "The following extensions are required to be installed "
 647                                 . "for this script to run: $joined. Please enable them and then try again.";
 648                         $this->fatalError( $msg );
 649                 }
 650         }
 651
 652         /**
 653          * Set triggers like when to try to run deferred updates
 654          * @since 1.28
 655          */
 656         public function setAgentAndTriggers() {
 657                 if ( function_exists( 'posix_getpwuid' ) ) {
 658                         $agent = posix_getpwuid( posix_geteuid() )['name'];
 659                 } else {
 660                         $agent = 'sysadmin';
 661                 }
 662                 $agent .= '@' . wfHostname();
 663
 664                 $lbFactory = MediaWikiServices::getInstance()->getDBLoadBalancerFactory();
 665                 // Add a comment for easy SHOW PROCESSLIST interpretation
 666                 $lbFactory->setAgentName(
 667                         mb_strlen( $agent ) > 15 ? mb_substr( $agent, 0, 15 ) . '...' : $agent
 668                 );
 669                 self::setLBFactoryTriggers( $lbFactory, $this->getConfig() );
 670         }
 671
 672         /**
 673          * @param LBFactory $LBFactory
 674          * @param Config $config
 675          * @since 1.28
 676          */
 677         public static function setLBFactoryTriggers( LBFactory $LBFactory, Config $config ) {
 678                 $services = MediaWikiServices::getInstance();
 679                 $stats = $services->getStatsdDataFactory();
 680                 // Hook into period lag checks which often happen in long-running scripts
 681                 $lbFactory = $services->getDBLoadBalancerFactory();
 682                 $lbFactory->setWaitForReplicationListener(
 683                         __METHOD__,
 684                         function () use ( $stats, $config ) {
 685                                 // Check config in case of JobRunner and unit tests
 686                                 if ( $config->get( 'CommandLineMode' ) ) {
 687                                         DeferredUpdates::tryOpportunisticExecute( 'run' );
 688                                 }
 689                                 // Try to periodically flush buffered metrics to avoid OOMs
 690                                 MediaWiki::emitBufferedStatsdData( $stats, $config );
 691                         }
 692                 );
 693                 // Check for other windows to run them. A script may read or do a few writes
 694                 // to the master but mostly be writing to something else, like a file store.
 695                 $lbFactory->getMainLB()->setTransactionListener(
 696                         __METHOD__,
 697                         function ( $trigger ) use ( $stats, $config ) {
 698                                 // Check config in case of JobRunner and unit tests
 699                                 if ( $config->get( 'CommandLineMode' ) && $trigger === IDatabase::TRIGGER_COMMIT ) {
 700                                         DeferredUpdates::tryOpportunisticExecute( 'run' );
 701                                 }
 702                                 // Try to periodically flush buffered metrics to avoid OOMs
 703                                 MediaWiki::emitBufferedStatsdData( $stats, $config );
 704                         }
 705                 );
 706         }
 707
 708         /**
 709          * Run a child maintenance script. Pass all of the current arguments
 710          * to it.
 711          * @param string $maintClass A name of a child maintenance class
 712          * @param string|null $classFile Full path of where the child is
 713          * @return Maintenance
 714          */
 715         public function runChild( $maintClass, $classFile = null ) {
 716                 // Make sure the class is loaded first
 717                 if ( !class_exists( $maintClass ) ) {
 718                         if ( $classFile ) {
 719                                 require_once $classFile;
 720                         }
 721                         if ( !class_exists( $maintClass ) ) {
 722                                 $this->error( "Cannot spawn child: $maintClass" );
 723                         }
 724                 }
 725
 726                 /**
 727                  * @var Maintenance $child
 728                  */
 729                 $child = new $maintClass();
 730                 $child->loadParamsAndArgs( $this->mSelf, $this->mOptions, $this->mArgs );
 731                 if ( !is_null( $this->mDb ) ) {
 732                         $child->setDB( $this->mDb );
 733                 }
 734
 735                 return $child;
 736         }
 737
 738         /**
 739          * Do some sanity checking and basic setup
 740          */
 741         public function setup() {
 742                 global $IP, $wgCommandLineMode;
 743
 744                 # Abort if called from a web server
 745                 # wfIsCLI() is not available yet
 746                 if ( PHP_SAPI !== 'cli' && PHP_SAPI !== 'phpdbg' ) {
 747                         $this->fatalError( 'This script must be run from the command line' );
 748                 }
 749
 750                 if ( $IP === null ) {
 751                         $this->fatalError( "\$IP not set, aborting!\n" .
 752                                 '(Did you forget to call parent::__construct() in your maintenance script?)' );
 753                 }
 754
 755                 # Make sure we can handle script parameters
 756                 if ( !defined( 'HPHP_VERSION' ) && !ini_get( 'register_argc_argv' ) ) {
 757                         $this->fatalError( 'Cannot get command line arguments, register_argc_argv is set to false' );
 758                 }
 759
 760                 // Send PHP warnings and errors to stderr instead of stdout.
 761                 // This aids in diagnosing problems, while keeping messages
 762                 // out of redirected output.
 763                 if ( ini_get( 'display_errors' ) ) {
 764                         ini_set( 'display_errors', 'stderr' );
 765                 }
 766
 767                 $this->loadParamsAndArgs();
 768
 769                 # Set the memory limit
 770                 # Note we need to set it again later in cache LocalSettings changed it
 771                 $this->adjustMemoryLimit();
 772
 773                 # Set max execution time to 0 (no limit). PHP.net says that
 774                 # "When running PHP from the command line the default setting is 0."
 775                 # But sometimes this doesn't seem to be the case.
 776                 ini_set( 'max_execution_time', 0 );
 777
 778                 # Define us as being in MediaWiki
 779                 define( 'MEDIAWIKI', true );
 780
 781                 $wgCommandLineMode = true;
 782
 783                 # Turn off output buffering if it's on
 784                 while ( ob_get_level() > 0 ) {
 785                         ob_end_flush();
 786                 }
 787         }
 788
 789         /**
 790          * Normally we disable the memory_limit when running admin scripts.
 791          * Some scripts may wish to actually set a limit, however, to avoid
 792          * blowing up unexpectedly. We also support a --memory-limit option,
 793          * to allow sysadmins to explicitly set one if they'd prefer to override
 794          * defaults (or for people using Suhosin which yells at you for trying
 795          * to disable the limits)
 796          * @return string
 797          */
 798         public function memoryLimit() {
 799                 $limit = $this->getOption( 'memory-limit', 'max' );
 800                 $limit = trim( $limit, "\" '" ); // trim quotes in case someone misunderstood
 801                 return $limit;
 802         }
 803
 804         /**
 805          * Adjusts PHP's memory limit to better suit our needs, if needed.
 806          */
 807         protected function adjustMemoryLimit() {
 808                 $limit = $this->memoryLimit();
 809                 if ( $limit == 'max' ) {
 810                         $limit = -1; // no memory limit
 811                 }
 812                 if ( $limit != 'default' ) {
 813                         ini_set( 'memory_limit', $limit );
 814                 }
 815         }
 816
 817         /**
 818          * Activate the profiler (assuming $wgProfiler is set)
 819          */
 820         protected function activateProfiler() {
 821                 global $wgProfiler, $wgProfileLimit, $wgTrxProfilerLimits;
 822
 823                 $output = $this->getOption( 'profiler' );
 824                 if ( !$output ) {
 825                         return;
 826                 }
 827
 828                 if ( is_array( $wgProfiler ) && isset( $wgProfiler['class'] ) ) {
 829                         $class = $wgProfiler['class'];
 830                         /** @var Profiler $profiler */
 831                         $profiler = new $class(
 832                                 [ 'sampling' => 1, 'output' => [ $output ] ]
 833                                         + $wgProfiler
 834                                         + [ 'threshold' => $wgProfileLimit ]
 835                         );
 836                         $profiler->setAllowOutput();
 837                         Profiler::replaceStubInstance( $profiler );
 838                 }
 839
 840                 $trxProfiler = Profiler::instance()->getTransactionProfiler();
 841                 $trxProfiler->setLogger( LoggerFactory::getInstance( 'DBPerformance' ) );
 842                 $trxProfiler->setExpectations( $wgTrxProfilerLimits['Maintenance'], __METHOD__ );
 843         }
 844
 845         /**
 846          * Clear all params and arguments.
 847          */
 848         public function clearParamsAndArgs() {
 849                 $this->mOptions = [];
 850                 $this->mArgs = [];
 851                 $this->mInputLoaded = false;
 852         }
 853
 854         /**
 855          * Load params and arguments from a given array
 856          * of command-line arguments
 857          *
 858          * @since 1.27
 859          * @param array $argv
 860          */
 861         public function loadWithArgv( $argv ) {
 862                 $options = [];
 863                 $args = [];
 864                 $this->orderedOptions = [];
 865
 866                 # Parse arguments
 867                 for ( $arg = reset( $argv ); $arg !== false; $arg = next( $argv ) ) {
 868                         if ( $arg == '--' ) {
 869                                 # End of options, remainder should be considered arguments
 870                                 $arg = next( $argv );
 871                                 while ( $arg !== false ) {
 872                                         $args[] = $arg;
 873                                         $arg = next( $argv );
 874                                 }
 875                                 break;
 876                         } elseif ( substr( $arg, 0, 2 ) == '--' ) {
 877                                 # Long options
 878                                 $option = substr( $arg, 2 );
 879                                 if ( isset( $this->mParams[$option] ) && $this->mParams[$option]['withArg'] ) {
 880                                         $param = next( $argv );
 881                                         if ( $param === false ) {
 882                                                 $this->error( "\nERROR: $option parameter needs a value after it\n" );
 883                                                 $this->maybeHelp( true );
 884                                         }
 885
 886                                         $this->setParam( $options, $option, $param );
 887                                 } else {
 888                                         $bits = explode( '=', $option, 2 );
 889                                         $this->setParam( $options, $bits[0], $bits[1] ?? 1 );
 890                                 }
 891                         } elseif ( $arg == '-' ) {
 892                                 # Lonely "-", often used to indicate stdin or stdout.
 893                                 $args[] = $arg;
 894                         } elseif ( substr( $arg, 0, 1 ) == '-' ) {
 895                                 # Short options
 896                                 $argLength = strlen( $arg );
 897                                 for ( $p = 1; $p < $argLength; $p++ ) {
 898                                         $option = $arg[$p];
 899                                         if ( !isset( $this->mParams[$option] ) && isset( $this->mShortParamsMap[$option] ) ) {
 900                                                 $option = $this->mShortParamsMap[$option];
 901                                         }
 902
 903                                         if ( isset( $this->mParams[$option]['withArg'] ) && $this->mParams[$option]['withArg'] ) {
 904                                                 $param = next( $argv );
 905                                                 if ( $param === false ) {
 906                                                         $this->error( "\nERROR: $option parameter needs a value after it\n" );
 907                                                         $this->maybeHelp( true );
 908                                                 }
 909                                                 $this->setParam( $options, $option, $param );
 910                                         } else {
 911                                                 $this->setParam( $options, $option, 1 );
 912                                         }
 913                                 }
 914                         } else {
 915                                 $args[] = $arg;
 916                         }
 917                 }
 918
 919                 $this->mOptions = $options;
 920                 $this->mArgs = $args;
 921                 $this->loadSpecialVars();
 922                 $this->mInputLoaded = true;
 923         }
 924
 925         /**
 926          * Helper function used solely by loadParamsAndArgs
 927          * to prevent code duplication
 928          *
 929          * This sets the param in the options array based on
 930          * whether or not it can be specified multiple times.
 931          *
 932          * @since 1.27
 933          * @param array $options
 934          * @param string $option
 935          * @param mixed $value
 936          */
 937         private function setParam( &$options, $option, $value ) {
 938                 $this->orderedOptions[] = [ $option, $value ];
 939
 940                 if ( isset( $this->mParams[$option] ) ) {
 941                         $multi = $this->mParams[$option]['multiOccurrence'];
 942                 } else {
 943                         $multi = false;
 944                 }
 945                 $exists = array_key_exists( $option, $options );
 946                 if ( $multi && $exists ) {
 947                         $options[$option][] = $value;
 948                 } elseif ( $multi ) {
 949                         $options[$option] = [ $value ];
 950                 } elseif ( !$exists ) {
 951                         $options[$option] = $value;
 952                 } else {
 953                         $this->error( "\nERROR: $option parameter given twice\n" );
 954                         $this->maybeHelp( true );
 955                 }
 956         }
 957
 958         /**
 959          * Process command line arguments
 960          * $mOptions becomes an array with keys set to the option names
 961          * $mArgs becomes a zero-based array containing the non-option arguments
 962          *
 963          * @param string|null $self The name of the script, if any
 964          * @param array|null $opts An array of options, in form of key=>value
 965          * @param array|null $args An array of command line arguments
 966          */
 967         public function loadParamsAndArgs( $self = null, $opts = null, $args = null ) {
 968                 # If we were given opts or args, set those and return early
 969                 if ( $self ) {
 970                         $this->mSelf = $self;
 971                         $this->mInputLoaded = true;
 972                 }
 973                 if ( $opts ) {
 974                         $this->mOptions = $opts;
 975                         $this->mInputLoaded = true;
 976                 }
 977                 if ( $args ) {
 978                         $this->mArgs = $args;
 979                         $this->mInputLoaded = true;
 980                 }
 981
 982                 # If we've already loaded input (either by user values or from $argv)
 983                 # skip on loading it again. The array_shift() will corrupt values if
 984                 # it's run again and again
 985                 if ( $this->mInputLoaded ) {
 986                         $this->loadSpecialVars();
 987
 988                         return;
 989                 }
 990
 991                 global $argv;
 992                 $this->mSelf = $argv[0];
 993                 $this->loadWithArgv( array_slice( $argv, 1 ) );
 994         }
 995
 996         /**
 997          * Run some validation checks on the params, etc
 998          */
 999         public function validateParamsAndArgs() {
1000                 $die = false;
1001                 # Check to make sure we've got all the required options
1002                 foreach ( $this->mParams as $opt => $info ) {
1003                         if ( $info['require'] && !$this->hasOption( $opt ) ) {
1004                                 $this->error( "Param $opt required!" );
1005                                 $die = true;
1006                         }
1007                 }
1008                 # Check arg list too
1009                 foreach ( $this->mArgList as $k => $info ) {
1010                         if ( $info['require'] && !$this->hasArg( $k ) ) {
1011                                 $this->error( 'Argument <' . $info['name'] . '> required!' );
1012                                 $die = true;
1013                         }
1014                 }
1015                 if ( !$this->mAllowUnregisteredOptions ) {
1016                         # Check for unexpected options
1017                         foreach ( $this->mOptions as $opt => $val ) {
1018                                 if ( !$this->supportsOption( $opt ) ) {
1019                                         $this->error( "Unexpected option $opt!" );
1020                                         $die = true;
1021                                 }
1022                         }
1023                 }
1024
1025                 $this->maybeHelp( $die );
1026         }
1027
1028         /**
1029          * Handle the special variables that are global to all scripts
1030          */
1031         protected function loadSpecialVars() {
1032                 if ( $this->hasOption( 'dbuser' ) ) {
1033                         $this->mDbUser = $this->getOption( 'dbuser' );
1034                 }
1035                 if ( $this->hasOption( 'dbpass' ) ) {
1036                         $this->mDbPass = $this->getOption( 'dbpass' );
1037                 }
1038                 if ( $this->hasOption( 'quiet' ) ) {
1039                         $this->mQuiet = true;
1040                 }
1041                 if ( $this->hasOption( 'batch-size' ) ) {
1042                         $this->mBatchSize = intval( $this->getOption( 'batch-size' ) );
1043                 }
1044         }
1045
1046         /**
1047          * Maybe show the help.
1048          * @param bool $force Whether to force the help to show, default false
1049          */
1050         protected function maybeHelp( $force = false ) {
1051                 if ( !$force && !$this->hasOption( 'help' ) ) {
1052                         return;
1053                 }
1054
1055                 $screenWidth = 80; // TODO: Calculate this!
1056                 $tab = "    ";
1057                 $descWidth = $screenWidth - ( 2 * strlen( $tab ) );
1058
1059                 ksort( $this->mParams );
1060                 $this->mQuiet = false;
1061
1062                 // Description ...
1063                 if ( $this->mDescription ) {
1064                         $this->output( "\n" . wordwrap( $this->mDescription, $screenWidth ) . "\n" );
1065                 }
1066                 $output = "\nUsage: php " . basename( $this->mSelf );
1067
1068                 // ... append parameters ...
1069                 if ( $this->mParams ) {
1070                         $output .= " [--" . implode( "|--", array_keys( $this->mParams ) ) . "]";
1071                 }
1072
1073                 // ... and append arguments.
1074                 if ( $this->mArgList ) {
1075                         $output .= ' ';
1076                         foreach ( $this->mArgList as $k => $arg ) {
1077                                 if ( $arg['require'] ) {
1078                                         $output .= '<' . $arg['name'] . '>';
1079                                 } else {
1080                                         $output .= '[' . $arg['name'] . ']';
1081                                 }
1082                                 if ( $k < count( $this->mArgList ) - 1 ) {
1083                                         $output .= ' ';
1084                                 }
1085                         }
1086                 }
1087                 $this->output( "$output\n\n" );
1088
1089                 # TODO abstract some repetitive code below
1090
1091                 // Generic parameters
1092                 $this->output( "Generic maintenance parameters:\n" );
1093                 foreach ( $this->mGenericParameters as $par => $info ) {
1094                         if ( $info['shortName'] !== false ) {
1095                                 $par .= " (-{$info['shortName']})";
1096                         }
1097                         $this->output(
1098                                 wordwrap( "$tab--$par: " . $info['desc'], $descWidth,
1099                                         "\n$tab$tab" ) . "\n"
1100                         );
1101                 }
1102                 $this->output( "\n" );
1103
1104                 $scriptDependantParams = $this->mDependantParameters;
1105                 if ( count( $scriptDependantParams ) > 0 ) {
1106                         $this->output( "Script dependant parameters:\n" );
1107                         // Parameters description
1108                         foreach ( $scriptDependantParams as $par => $info ) {
1109                                 if ( $info['shortName'] !== false ) {
1110                                         $par .= " (-{$info['shortName']})";
1111                                 }
1112                                 $this->output(
1113                                         wordwrap( "$tab--$par: " . $info['desc'], $descWidth,
1114                                                 "\n$tab$tab" ) . "\n"
1115                                 );
1116                         }
1117                         $this->output( "\n" );
1118                 }
1119
1120                 // Script specific parameters not defined on construction by
1121                 // Maintenance::addDefaultParams()
1122                 $scriptSpecificParams = array_diff_key(
1123                         # all script parameters:
1124                         $this->mParams,
1125                         # remove the Maintenance default parameters:
1126                         $this->mGenericParameters,
1127                         $this->mDependantParameters
1128                 );
1129                 if ( count( $scriptSpecificParams ) > 0 ) {
1130                         $this->output( "Script specific parameters:\n" );
1131                         // Parameters description
1132                         foreach ( $scriptSpecificParams as $par => $info ) {
1133                                 if ( $info['shortName'] !== false ) {
1134                                         $par .= " (-{$info['shortName']})";
1135                                 }
1136                                 $this->output(
1137                                         wordwrap( "$tab--$par: " . $info['desc'], $descWidth,
1138                                                 "\n$tab$tab" ) . "\n"
1139                                 );
1140                         }
1141                         $this->output( "\n" );
1142                 }
1143
1144                 // Print arguments
1145                 if ( count( $this->mArgList ) > 0 ) {
1146                         $this->output( "Arguments:\n" );
1147                         // Arguments description
1148                         foreach ( $this->mArgList as $info ) {
1149                                 $openChar = $info['require'] ? '<' : '[';
1150                                 $closeChar = $info['require'] ? '>' : ']';
1151                                 $this->output(
1152                                         wordwrap( "$tab$openChar" . $info['name'] . "$closeChar: " .
1153                                                 $info['desc'], $descWidth, "\n$tab$tab" ) . "\n"
1154                                 );
1155                         }
1156                         $this->output( "\n" );
1157                 }
1158
1159                 die( 1 );
1160         }
1161
1162         /**
1163          * Handle some last-minute setup here.
1164          */
1165         public function finalSetup() {
1166                 global $wgCommandLineMode, $wgServer, $wgShowExceptionDetails, $wgShowHostnames;
1167                 global $wgDBadminuser, $wgDBadminpassword, $wgDBDefaultGroup;
1168                 global $wgDBuser, $wgDBpassword, $wgDBservers, $wgLBFactoryConf;
1169
1170                 # Turn off output buffering again, it might have been turned on in the settings files
1171                 if ( ob_get_level() ) {
1172                         ob_end_flush();
1173                 }
1174                 # Same with these
1175                 $wgCommandLineMode = true;
1176
1177                 # Override $wgServer
1178                 if ( $this->hasOption( 'server' ) ) {
1179                         $wgServer = $this->getOption( 'server', $wgServer );
1180                 }
1181
1182                 # If these were passed, use them
1183                 if ( $this->mDbUser ) {
1184                         $wgDBadminuser = $this->mDbUser;
1185                 }
1186                 if ( $this->mDbPass ) {
1187                         $wgDBadminpassword = $this->mDbPass;
1188                 }
1189                 if ( $this->hasOption( 'dbgroupdefault' ) ) {
1190                         $wgDBDefaultGroup = $this->getOption( 'dbgroupdefault', null );
1191
1192                         MediaWikiServices::getInstance()->getDBLoadBalancerFactory()->destroy();
1193                 }
1194
1195                 if ( $this->getDbType() == self::DB_ADMIN && isset( $wgDBadminuser ) ) {
1196                         $wgDBuser = $wgDBadminuser;
1197                         $wgDBpassword = $wgDBadminpassword;
1198
1199                         if ( $wgDBservers ) {
1200                                 /**
1201                                  * @var array $wgDBservers
1202                                  */
1203                                 foreach ( $wgDBservers as $i => $server ) {
1204                                         $wgDBservers[$i]['user'] = $wgDBuser;
1205                                         $wgDBservers[$i]['password'] = $wgDBpassword;
1206                                 }
1207                         }
1208                         if ( isset( $wgLBFactoryConf['serverTemplate'] ) ) {
1209                                 $wgLBFactoryConf['serverTemplate']['user'] = $wgDBuser;
1210                                 $wgLBFactoryConf['serverTemplate']['password'] = $wgDBpassword;
1211                         }
1212                         MediaWikiServices::getInstance()->getDBLoadBalancerFactory()->destroy();
1213                 }
1214
1215                 # Apply debug settings
1216                 if ( $this->hasOption( 'mwdebug' ) ) {
1217                         require __DIR__ . '/../includes/DevelopmentSettings.php';
1218                 }
1219
1220                 // Per-script profiling; useful for debugging
1221                 $this->activateProfiler();
1222
1223                 $this->afterFinalSetup();
1224
1225                 $wgShowExceptionDetails = true;
1226                 $wgShowHostnames = true;
1227
1228                 Wikimedia\suppressWarnings();
1229                 set_time_limit( 0 );
1230                 Wikimedia\restoreWarnings();
1231
1232                 $this->adjustMemoryLimit();
1233         }
1234
1235         /**
1236          * Execute a callback function at the end of initialisation
1237          */
1238         protected function afterFinalSetup() {
1239                 if ( defined( 'MW_CMDLINE_CALLBACK' ) ) {
1240                         call_user_func( MW_CMDLINE_CALLBACK );
1241                 }
1242         }
1243
1244         /**
1245          * Potentially debug globals. Originally a feature only
1246          * for refreshLinks
1247          */
1248         public function globals() {
1249                 if ( $this->hasOption( 'globals' ) ) {
1250                         print_r( $GLOBALS );
1251                 }
1252         }
1253
1254         /**
1255          * Generic setup for most installs. Returns the location of LocalSettings
1256          * @return string
1257          */
1258         public function loadSettings() {
1259                 global $wgCommandLineMode, $IP;
1260
1261                 if ( isset( $this->mOptions['conf'] ) ) {
1262                         $settingsFile = $this->mOptions['conf'];
1263                 } elseif ( defined( "MW_CONFIG_FILE" ) ) {
1264                         $settingsFile = MW_CONFIG_FILE;
1265                 } else {
1266                         $settingsFile = "$IP/LocalSettings.php";
1267                 }
1268                 if ( isset( $this->mOptions['wiki'] ) ) {
1269                         $bits = explode( '-', $this->mOptions['wiki'], 2 );
1270                         define( 'MW_DB', $bits[0] );
1271                         define( 'MW_PREFIX', $bits[1] ?? '' );
1272                 } elseif ( isset( $this->mOptions['server'] ) ) {
1273                         // Provide the option for site admins to detect and configure
1274                         // multiple wikis based on server names. This offers --server
1275                         // as alternative to --wiki.
1276                         // See https://www.mediawiki.org/wiki/Manual:Wiki_family
1277                         $_SERVER['SERVER_NAME'] = $this->mOptions['server'];
1278                 }
1279
1280                 if ( !is_readable( $settingsFile ) ) {
1281                         $this->fatalError( "A copy of your installation's LocalSettings.php\n" .
1282                                 "must exist and be readable in the source directory.\n" .
1283                                 "Use --conf to specify it." );
1284                 }
1285                 $wgCommandLineMode = true;
1286
1287                 return $settingsFile;
1288         }
1289
1290         /**
1291          * Support function for cleaning up redundant text records
1292          * @param bool $delete Whether or not to actually delete the records
1293          * @author Rob Church <robchur@gmail.com>
1294          */
1295         public function purgeRedundantText( $delete = true ) {
1296                 global $wgMultiContentRevisionSchemaMigrationStage;
1297
1298                 # Data should come off the master, wrapped in a transaction
1299                 $dbw = $this->getDB( DB_MASTER );
1300                 $this->beginTransaction( $dbw, __METHOD__ );
1301
1302                 if ( $wgMultiContentRevisionSchemaMigrationStage & SCHEMA_COMPAT_READ_OLD ) {
1303                         # Get "active" text records from the revisions table
1304                         $cur = [];
1305                         $this->output( 'Searching for active text records in revisions table...' );
1306                         $res = $dbw->select( 'revision', 'rev_text_id', [], __METHOD__, [ 'DISTINCT' ] );
1307                         foreach ( $res as $row ) {
1308                                 $cur[] = $row->rev_text_id;
1309                         }
1310                         $this->output( "done.\n" );
1311
1312                         # Get "active" text records from the archive table
1313                         $this->output( 'Searching for active text records in archive table...' );
1314                         $res = $dbw->select( 'archive', 'ar_text_id', [], __METHOD__, [ 'DISTINCT' ] );
1315                         foreach ( $res as $row ) {
1316                                 # old pre-MW 1.5 records can have null ar_text_id's.
1317                                 if ( $row->ar_text_id !== null ) {
1318                                         $cur[] = $row->ar_text_id;
1319                                 }
1320                         }
1321                         $this->output( "done.\n" );
1322                 } else {
1323                         # Get "active" text records via the content table
1324                         $cur = [];
1325                         $this->output( 'Searching for active text records via contents table...' );
1326                         $res = $dbw->select( 'content', 'content_address', [], __METHOD__, [ 'DISTINCT' ] );
1327                         $blobStore = MediaWikiServices::getInstance()->getBlobStore();
1328                         foreach ( $res as $row ) {
1329                                 $textId = $blobStore->getTextIdFromAddress( $row->content_address );
1330                                 if ( $textId ) {
1331                                         $cur[] = $textId;
1332                                 }
1333                         }
1334                         $this->output( "done.\n" );
1335                 }
1336                 $this->output( "done.\n" );
1337
1338                 # Get the IDs of all text records not in these sets
1339                 $this->output( 'Searching for inactive text records...' );
1340                 $cond = 'old_id NOT IN ( ' . $dbw->makeList( $cur ) . ' )';
1341                 $res = $dbw->select( 'text', 'old_id', [ $cond ], __METHOD__, [ 'DISTINCT' ] );
1342                 $old = [];
1343                 foreach ( $res as $row ) {
1344                         $old[] = $row->old_id;
1345                 }
1346                 $this->output( "done.\n" );
1347
1348                 # Inform the user of what we're going to do
1349                 $count = count( $old );
1350                 $this->output( "$count inactive items found.\n" );
1351
1352                 # Delete as appropriate
1353                 if ( $delete && $count ) {
1354                         $this->output( 'Deleting...' );
1355                         $dbw->delete( 'text', [ 'old_id' => $old ], __METHOD__ );
1356                         $this->output( "done.\n" );
1357                 }
1358
1359                 $this->commitTransaction( $dbw, __METHOD__ );
1360         }
1361
1362         /**
1363          * Get the maintenance directory.
1364          * @return string
1365          */
1366         protected function getDir() {
1367                 return __DIR__;
1368         }
1369
1370         /**
1371          * Returns a database to be used by current maintenance script.
1372          *
1373          * This uses the main LBFactory instance by default unless overriden via setDB().
1374          *
1375          * This function has the same parameters as LoadBalancer::getConnection().
1376          *
1377          * @param int $db DB index (DB_REPLICA/DB_MASTER)
1378          * @param string|string[] $groups default: empty array
1379          * @param string|bool $dbDomain default: current wiki
1380          * @return IMaintainableDatabase
1381          */
1382         protected function getDB( $db, $groups = [], $dbDomain = false ) {
1383                 if ( $this->mDb === null ) {
1384                         return MediaWikiServices::getInstance()
1385                                 ->getDBLoadBalancerFactory()
1386                                 ->getMainLB( $dbDomain )
1387                                 ->getMaintenanceConnectionRef( $db, $groups, $dbDomain );
1388                 }
1389
1390                 return $this->mDb;
1391         }
1392
1393         /**
1394          * Sets database object to be returned by getDB().
1395          *
1396          * @param IMaintainableDatabase $db
1397          */
1398         public function setDB( IMaintainableDatabase $db ) {
1399                 $this->mDb = $db;
1400         }
1401
1402         /**
1403          * Begin a transcation on a DB
1404          *
1405          * This method makes it clear that begin() is called from a maintenance script,
1406          * which has outermost scope. This is safe, unlike $dbw->begin() called in other places.
1407          *
1408          * @param IDatabase $dbw
1409          * @param string $fname Caller name
1410          * @since 1.27
1411          */
1412         protected function beginTransaction( IDatabase $dbw, $fname ) {
1413                 $dbw->begin( $fname );
1414         }
1415
1416         /**
1417          * Commit the transcation on a DB handle and wait for replica DBs to catch up
1418          *
1419          * This method makes it clear that commit() is called from a maintenance script,
1420          * which has outermost scope. This is safe, unlike $dbw->commit() called in other places.
1421          *
1422          * @param IDatabase $dbw
1423          * @param string $fname Caller name
1424          * @return bool Whether the replica DB wait succeeded
1425          * @since 1.27
1426          */
1427         protected function commitTransaction( IDatabase $dbw, $fname ) {
1428                 $dbw->commit( $fname );
1429                 $lbFactory = MediaWikiServices::getInstance()->getDBLoadBalancerFactory();
1430                 $waitSucceeded = $lbFactory->waitForReplication(
1431                         [ 'timeout' => 30, 'ifWritesSince' => $this->lastReplicationWait ]
1432                 );
1433                 $this->lastReplicationWait = microtime( true );
1434                 return $waitSucceeded;
1435         }
1436
1437         /**
1438          * Rollback the transcation on a DB handle
1439          *
1440          * This method makes it clear that rollback() is called from a maintenance script,
1441          * which has outermost scope. This is safe, unlike $dbw->rollback() called in other places.
1442          *
1443          * @param IDatabase $dbw
1444          * @param string $fname Caller name
1445          * @since 1.27
1446          */
1447         protected function rollbackTransaction( IDatabase $dbw, $fname ) {
1448                 $dbw->rollback( $fname );
1449         }
1450
1451         /**
1452          * Lock the search index
1453          * @param IMaintainableDatabase &$db
1454          */
1455         private function lockSearchindex( $db ) {
1456                 $write = [ 'searchindex' ];
1457                 $read = [
1458                         'page',
1459                         'revision',
1460                         'text',
1461                         'interwiki',
1462                         'l10n_cache',
1463                         'user',
1464                         'page_restrictions'
1465                 ];
1466                 $db->lockTables( $read, $write, __CLASS__ . '-searchIndexLock' );
1467         }
1468
1469         /**
1470          * Unlock the tables
1471          * @param IMaintainableDatabase &$db
1472          */
1473         private function unlockSearchindex( $db ) {
1474                 $db->unlockTables( __CLASS__ . '-searchIndexLock' );
1475         }
1476
1477         /**
1478          * Unlock and lock again
1479          * Since the lock is low-priority, queued reads will be able to complete
1480          * @param IMaintainableDatabase &$db
1481          */
1482         private function relockSearchindex( $db ) {
1483                 $this->unlockSearchindex( $db );
1484                 $this->lockSearchindex( $db );
1485         }
1486
1487         /**
1488          * Perform a search index update with locking
1489          * @param int $maxLockTime The maximum time to keep the search index locked.
1490          * @param callable $callback The function that will update the function.
1491          * @param IMaintainableDatabase $dbw
1492          * @param array|IResultWrapper $results
1493          */
1494         public function updateSearchIndex( $maxLockTime, $callback, $dbw, $results ) {
1495                 $lockTime = time();
1496
1497                 # Lock searchindex
1498                 if ( $maxLockTime ) {
1499                         $this->output( "   --- Waiting for lock ---" );
1500                         $this->lockSearchindex( $dbw );
1501                         $lockTime = time();
1502                         $this->output( "\n" );
1503                 }
1504
1505                 # Loop through the results and do a search update
1506                 foreach ( $results as $row ) {
1507                         # Allow reads to be processed
1508                         if ( $maxLockTime && time() > $lockTime + $maxLockTime ) {
1509                                 $this->output( "    --- Relocking ---" );
1510                                 $this->relockSearchindex( $dbw );
1511                                 $lockTime = time();
1512                                 $this->output( "\n" );
1513                         }
1514                         call_user_func( $callback, $dbw, $row );
1515                 }
1516
1517                 # Unlock searchindex
1518                 if ( $maxLockTime ) {
1519                         $this->output( "    --- Unlocking --" );
1520                         $this->unlockSearchindex( $dbw );
1521                         $this->output( "\n" );
1522                 }
1523         }
1524
1525         /**
1526          * Update the searchindex table for a given pageid
1527          * @param IDatabase $dbw A database write handle
1528          * @param int $pageId The page ID to update.
1529          * @return null|string
1530          */
1531         public function updateSearchIndexForPage( $dbw, $pageId ) {
1532                 // Get current revision
1533                 $rev = Revision::loadFromPageId( $dbw, $pageId );
1534                 $title = null;
1535                 if ( $rev ) {
1536                         $titleObj = $rev->getTitle();
1537                         $title = $titleObj->getPrefixedDBkey();
1538                         $this->output( "$title..." );
1539                         # Update searchindex
1540                         $u = new SearchUpdate( $pageId, $titleObj, $rev->getContent() );
1541                         $u->doUpdate();
1542                         $this->output( "\n" );
1543                 }
1544
1545                 return $title;
1546         }
1547
1548         /**
1549          * Count down from $seconds to zero on the terminal, with a one-second pause
1550          * between showing each number. If the maintenance script is in quiet mode,
1551          * this function does nothing.
1552          *
1553          * @since 1.31
1554          *
1555          * @codeCoverageIgnore
1556          * @param int $seconds
1557          */
1558         protected function countDown( $seconds ) {
1559                 if ( $this->isQuiet() ) {
1560                         return;
1561                 }
1562                 for ( $i = $seconds; $i >= 0; $i-- ) {
1563                         if ( $i != $seconds ) {
1564                                 $this->output( str_repeat( "\x08", strlen( $i + 1 ) ) );
1565                         }
1566                         $this->output( $i );
1567                         if ( $i ) {
1568                                 sleep( 1 );
1569                         }
1570                 }
1571                 $this->output( "\n" );
1572         }
1573
1574         /**
1575          * Wrapper for posix_isatty()
1576          * We default as considering stdin a tty (for nice readline methods)
1577          * but treating stout as not a tty to avoid color codes
1578          *
1579          * @param mixed $fd File descriptor
1580          * @return bool
1581          */
1582         public static function posix_isatty( $fd ) {
1583                 if ( !function_exists( 'posix_isatty' ) ) {
1584                         return !$fd;
1585                 } else {
1586                         return posix_isatty( $fd );
1587                 }
1588         }
1589
1590         /**
1591          * Prompt the console for input
1592          * @param string $prompt What to begin the line with, like '> '
1593          * @return string Response
1594          */
1595         public static function readconsole( $prompt = '> ' ) {
1596                 static $isatty = null;
1597                 if ( is_null( $isatty ) ) {
1598                         $isatty = self::posix_isatty( 0 /*STDIN*/ );
1599                 }
1600
1601                 if ( $isatty && function_exists( 'readline' ) ) {
1602                         return readline( $prompt );
1603                 } else {
1604                         if ( $isatty ) {
1605                                 $st = self::readlineEmulation( $prompt );
1606                         } else {
1607                                 if ( feof( STDIN ) ) {
1608                                         $st = false;
1609                                 } else {
1610                                         $st = fgets( STDIN, 1024 );
1611                                 }
1612                         }
1613                         if ( $st === false ) {
1614                                 return false;
1615                         }
1616                         $resp = trim( $st );
1617
1618                         return $resp;
1619                 }
1620         }
1621
1622         /**
1623          * Emulate readline()
1624          * @param string $prompt What to begin the line with, like '> '
1625          * @return string
1626          */
1627         private static function readlineEmulation( $prompt ) {
1628                 $bash = ExecutableFinder::findInDefaultPaths( 'bash' );
1629                 if ( !wfIsWindows() && $bash ) {
1630                         $retval = false;
1631                         $encPrompt = Shell::escape( $prompt );
1632                         $command = "read -er -p $encPrompt && echo \"\$REPLY\"";
1633                         $encCommand = Shell::escape( $command );
1634                         $line = Shell::escape( "$bash -c $encCommand", $retval, [], [ 'walltime' => 0 ] );
1635
1636                         if ( $retval == 0 ) {
1637                                 return $line;
1638                         } elseif ( $retval == 127 ) {
1639                                 // Couldn't execute bash even though we thought we saw it.
1640                                 // Shell probably spit out an error message, sorry :(
1641                                 // Fall through to fgets()...
1642                         } else {
1643                                 // EOF/ctrl+D
1644                                 return false;
1645                         }
1646                 }
1647
1648                 // Fallback... we'll have no editing controls, EWWW
1649                 if ( feof( STDIN ) ) {
1650                         return false;
1651                 }
1652                 print $prompt;
1653
1654                 return fgets( STDIN, 1024 );
1655         }
1656
1657         /**
1658          * Get the terminal size as a two-element array where the first element
1659          * is the width (number of columns) and the second element is the height
1660          * (number of rows).
1661          *
1662          * @return array
1663          */
1664         public static function getTermSize() {
1665                 $default = [ 80, 50 ];
1666                 if ( wfIsWindows() ) {
1667                         return $default;
1668                 }
1669                 if ( Shell::isDisabled() ) {
1670                         return $default;
1671                 }
1672                 // It's possible to get the screen size with VT-100 terminal escapes,
1673                 // but reading the responses is not possible without setting raw mode
1674                 // (unless you want to require the user to press enter), and that
1675                 // requires an ioctl(), which we can't do. So we have to shell out to
1676                 // something that can do the relevant syscalls. There are a few
1677                 // options. Linux and Mac OS X both have "stty size" which does the
1678                 // job directly.
1679                 $result = Shell::command( 'stty', 'size' )
1680                         ->execute();
1681                 if ( $result->getExitCode() !== 0 ) {
1682                         return $default;
1683                 }
1684                 if ( !preg_match( '/^(\d+) (\d+)$/', $result->getStdout(), $m ) ) {
1685                         return $default;
1686                 }
1687                 return [ intval( $m[2] ), intval( $m[1] ) ];
1688         }
1689
1690         /**
1691          * Call this to set up the autoloader to allow classes to be used from the
1692          * tests directory.
1693          */
1694         public static function requireTestsAutoloader() {
1695                 require_once __DIR__ . '/../tests/common/TestsAutoLoader.php';
1696         }
1697 }
1698
1699 /**
1700  * Fake maintenance wrapper, mostly used for the web installer/updater
1701  */
1702 class FakeMaintenance extends Maintenance {
1703         protected $mSelf = "FakeMaintenanceScript";
1704
1705         public function execute() {
1706         }
1707 }
1708
1709 /**
1710  * Class for scripts that perform database maintenance and want to log the
1711  * update in `updatelog` so we can later skip it
1712  */
1713 abstract class LoggedUpdateMaintenance extends Maintenance {
1714         public function __construct() {
1715                 parent::__construct();
1716                 $this->addOption( 'force', 'Run the update even if it was completed already' );
1717                 $this->setBatchSize( 200 );
1718         }
1719
1720         public function execute() {
1721                 $db = $this->getDB( DB_MASTER );
1722                 $key = $this->getUpdateKey();
1723
1724                 if ( !$this->hasOption( 'force' )
1725                         && $db->selectRow( 'updatelog', '1', [ 'ul_key' => $key ], __METHOD__ )
1726                 ) {
1727                         $this->output( "..." . $this->updateSkippedMessage() . "\n" );
1728
1729                         return true;
1730                 }
1731
1732                 if ( !$this->doDBUpdates() ) {
1733                         return false;
1734                 }
1735
1736                 $db->insert( 'updatelog', [ 'ul_key' => $key ], __METHOD__, [ 'IGNORE' ] );
1737
1738                 return true;
1739         }
1740
1741         /**
1742          * Message to show that the update was done already and was just skipped
1743          * @return string
1744          */
1745         protected function updateSkippedMessage() {
1746                 $key = $this->getUpdateKey();
1747
1748                 return "Update '{$key}' already logged as completed. Use --force to run it again.";
1749         }
1750
1751         /**
1752          * Do the actual work. All child classes will need to implement this.
1753          * Return true to log the update as done or false (usually on failure).
1754          * @return bool
1755          */
1756         abstract protected function doDBUpdates();
1757
1758         /**
1759          * Get the update key name to go in the update log table
1760          * @return string
1761          */
1762         abstract protected function getUpdateKey();
1763 }