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