Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
24.57% covered (danger)
24.57%
72 / 293
16.67% covered (danger)
16.67%
5 / 30
CRAP
0.00% covered (danger)
0.00%
0 / 1
MaintenanceRunner
24.57% covered (danger)
24.57%
72 / 293
16.67% covered (danger)
16.67%
5 / 30
5207.32
0.00% covered (danger)
0.00%
0 / 1
 __construct
100.00% covered (success)
100.00%
2 / 2
100.00% covered (success)
100.00%
1 / 1
1
 getConfig
0.00% covered (danger)
0.00%
0 / 3
0.00% covered (danger)
0.00%
0 / 1
6
 addDefaultParams
100.00% covered (success)
100.00%
16 / 16
100.00% covered (success)
100.00%
1 / 1
1
 showHelpAndExit
0.00% covered (danger)
0.00%
0 / 7
0.00% covered (danger)
0.00%
0 / 1
6
 initFromWrapper
0.00% covered (danger)
0.00%
0 / 27
0.00% covered (danger)
0.00%
0 / 1
30
 initForClass
0.00% covered (danger)
0.00%
0 / 6
0.00% covered (danger)
0.00%
0 / 1
2
 initInternal
0.00% covered (danger)
0.00%
0 / 7
0.00% covered (danger)
0.00%
0 / 1
12
 isAbsolutePath
50.00% covered (danger)
50.00%
4 / 8
0.00% covered (danger)
0.00%
0 / 1
8.12
 getExtensionInfo
0.00% covered (danger)
0.00%
0 / 12
0.00% covered (danger)
0.00%
0 / 1
12
 loadScriptFile
66.67% covered (warning)
66.67%
6 / 9
0.00% covered (danger)
0.00%
0 / 1
3.33
 splitScript
100.00% covered (success)
100.00%
3 / 3
100.00% covered (success)
100.00%
1 / 1
2
 expandScriptFile
100.00% covered (success)
100.00%
8 / 8
100.00% covered (success)
100.00%
1 / 1
5
 expandScriptClass
100.00% covered (success)
100.00%
5 / 5
100.00% covered (success)
100.00%
1 / 1
2
 preloadScriptFile
84.62% covered (warning)
84.62%
11 / 13
0.00% covered (danger)
0.00%
0 / 1
8.23
 getScriptClass
42.86% covered (danger)
42.86%
3 / 7
0.00% covered (danger)
0.00%
0 / 1
6.99
 findScriptClass
93.33% covered (success)
93.33%
14 / 15
0.00% covered (danger)
0.00%
0 / 1
7.01
 setup
0.00% covered (danger)
0.00%
0 / 23
0.00% covered (danger)
0.00%
0 / 1
30
 getName
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
2
 memoryLimit
0.00% covered (danger)
0.00%
0 / 6
0.00% covered (danger)
0.00%
0 / 1
12
 adjustMemoryLimit
0.00% covered (danger)
0.00%
0 / 5
0.00% covered (danger)
0.00%
0 / 1
12
 defineSettings
0.00% covered (danger)
0.00%
0 / 19
0.00% covered (danger)
0.00%
0 / 1
72
 emulateConfig
0.00% covered (danger)
0.00%
0 / 4
0.00% covered (danger)
0.00%
0 / 1
2
 overrideConfig
0.00% covered (danger)
0.00%
0 / 20
0.00% covered (danger)
0.00%
0 / 1
72
 getServiceContainer
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
2
 run
0.00% covered (danger)
0.00%
0 / 31
0.00% covered (danger)
0.00%
0 / 1
72
 fatalError
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
2
 error
0.00% covered (danger)
0.00%
0 / 3
0.00% covered (danger)
0.00%
0 / 1
6
 shouldExecute
0.00% covered (danger)
0.00%
0 / 11
0.00% covered (danger)
0.00%
0 / 1
42
 cleanup
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
6
 shutdown
0.00% covered (danger)
0.00%
0 / 17
0.00% covered (danger)
0.00%
0 / 1
42
1<?php
2
3namespace MediaWiki\Maintenance;
4
5use Exception;
6use LCStoreNull;
7use LogicException;
8use Maintenance;
9use MediaWiki;
10use MediaWiki\Config\Config;
11use MediaWiki\Deferred\DeferredUpdates;
12use MediaWiki\Logger\LoggerFactory;
13use MediaWiki\MainConfigNames;
14use MediaWiki\MediaWikiServices;
15use MediaWiki\Settings\SettingsBuilder;
16use Profiler;
17use ReflectionClass;
18use Throwable;
19
20/**
21 * A runner for maintenance scripts.
22 *
23 * @since 1.39
24 * @unstable
25 */
26class MaintenanceRunner {
27
28    /**
29     * Identifies the script to execute. This may be a class name, the relative or absolute
30     * path of a script file, a plain name with or without an extension prefix, etc.
31     *
32     * @var ?string
33     */
34    private $script = null;
35
36    /**
37     * The class name of the script to execute.
38     *
39     * @var ?class-string<Maintenance>
40     */
41    private $scriptClass = null;
42
43    /** @var string[]|null */
44    private $scriptArgv = null;
45
46    /** @var Maintenance|null */
47    private $scriptObject = null;
48
49    /** @var MaintenanceParameters */
50    private $parameters;
51
52    /** @var bool */
53    private $runFromWrapper = false;
54
55    /** @var bool */
56    private bool $withoutLocalSettings = false;
57
58    /** @var ?Config */
59    private ?Config $config = null;
60
61    /**
62     * Default constructor. Children should call this *first* if implementing
63     * their own constructors
64     *
65     * @stable to call
66     */
67    public function __construct() {
68        $this->parameters = new MaintenanceParameters();
69        $this->addDefaultParams();
70    }
71
72    private function getConfig() {
73        if ( $this->config === null ) {
74            $this->config = $this->getServiceContainer()->getMainConfig();
75        }
76
77        return $this->config;
78    }
79
80    /**
81     * Add the default parameters to the scripts
82     */
83    protected function addDefaultParams() {
84        // Generic (non-script-dependent) options:
85
86        $this->parameters->addOption( 'conf', 'Location of LocalSettings.php, if not default', false, true );
87        $this->parameters->addOption( 'wiki', 'For specifying the wiki ID', false, true );
88        $this->parameters->addOption( 'globals', 'Output globals at the end of processing for debugging' );
89        $this->parameters->addOption(
90            'memory-limit',
91            'Set a specific memory limit for the script, '
92            . '"max" for no limit or "default" to avoid changing it',
93            false,
94            true
95        );
96        $this->parameters->addOption( 'server', "The protocol and server name to use in URLs, e.g. " .
97            "https://en.wikipedia.org. This is sometimes necessary because " .
98            "server name detection may fail in command line scripts.", false, true );
99        $this->parameters->addOption( 'profiler', 'Profiler output format (usually "text")', false, true );
100
101        // Save generic options to display them separately in help
102        $generic = $this->parameters->getOptionNames();
103        $this->parameters->assignGroup( Maintenance::GENERIC_MAINTENANCE_PARAMETERS, $generic );
104    }
105
106    /**
107     * @param int $code
108     *
109     * @return never
110     */
111    private function showHelpAndExit( $code = 0 ) {
112        foreach ( $this->parameters->getErrors() as $error ) {
113            $this->error( "$error\n" );
114            $code = 1;
115        }
116
117        $this->parameters->setDescription( 'Runner for maintenance scripts' );
118
119        $help = $this->parameters->getHelp();
120        echo $help;
121        exit( $code );
122    }
123
124    /**
125     * Initialize the runner from the given command line arguments
126     * as passed to a wrapper script.
127     *
128     * @note Called before Setup.php
129     *
130     * @param string[] $argv The arguments passed from the command line,
131     *        including the wrapper script at index 0, and usually
132     *        the script to run at index 1.
133     */
134    public function initFromWrapper( array $argv ) {
135        $script = null;
136
137        $this->parameters->setName( $argv[0] );
138        $this->parameters->setAllowUnregisteredOptions( true );
139        $this->parameters->addArg(
140            'script',
141            'The name of the maintenance script to run. ' .
142                'Can be given as a class name or file path. The `.php` suffix is optional. ' .
143                'Paths starting with `./` or `../` are interpreted to be relative to the current working directory. ' .
144                'Other relative paths are interpreted relative to the maintenance script directory. ' .
145                'Dots (.) are supported as namespace separators in class names. ' .
146                'An extension name may be provided as a prefix, followed by a colon, e.g. "MyExtension:...", ' .
147                'to indicate that the path or class name should be interpreted relative to the extension.'
148        );
149
150        $this->runFromWrapper = true;
151        $this->parameters->loadWithArgv( $argv, 1 );
152
153        // script params
154        $argv = array_slice( $argv, 2 );
155
156        if ( $this->parameters->validate() ) {
157            $script = $this->parameters->getArg( 0 );
158
159            // Special handling for the 'help' command
160            if ( $script === 'help' ) {
161                if ( $this->parameters->hasArg( 1 ) ) {
162                    $script = $this->parameters->getArg( 1 );
163
164                    // turn <help> <command> into <command> --help
165                    $this->parameters->loadWithArgv( [ $script ] );
166                    $argv = [ '--help' ];
167                } else {
168                    // same as no command
169                    $script = null;
170                }
171            }
172        }
173
174        if ( $script ) {
175            // Strip another argument from $argv!
176            $this->initInternal( $script, $argv );
177        } else {
178            $this->showHelpAndExit();
179        }
180    }
181
182    /**
183     * Initialize the runner for the given class.
184     * This is used when running scripts directly, without a wrapper.
185     *
186     * @note Called before Setup.php
187     *
188     * @param string $scriptClass The script class to run
189     * @param string[] $argv The arguments to passed to the script, including
190     *        the script itself at index 0.
191     */
192    public function initForClass( string $scriptClass, $argv ) {
193        $this->runFromWrapper = false;
194        $this->script = $scriptClass;
195        $this->scriptClass = $scriptClass;
196        $this->parameters->setName( $argv[0] );
197        $this->parameters->loadWithArgv( $argv );
198        $this->initInternal( $scriptClass, array_slice( $argv, 1 ) );
199    }
200
201    /**
202     * Initialize the runner.
203     *
204     * @note Called before Setup.php
205     *
206     * @param string $script The script to run
207     * @param string[] $scriptArgv The arguments to pass to the maintenance script,
208     *        not including the script itself.
209     */
210    private function initInternal( string $script, array $scriptArgv ) {
211        $this->script = $script;
212        $this->scriptArgv = $scriptArgv;
213
214        // Send PHP warnings and errors to stderr instead of stdout.
215        // This aids in diagnosing problems, while keeping messages
216        // out of redirected output.
217        if ( ini_get( 'display_errors' ) ) {
218            ini_set( 'display_errors', 'stderr' );
219        }
220
221        // make sure we clean up after ourselves.
222        register_shutdown_function( [ $this, 'cleanup' ] );
223
224        // Turn off output buffering if it's on
225        while ( ob_get_level() > 0 ) {
226            ob_end_flush();
227        }
228    }
229
230    private static function isAbsolutePath( $path ) {
231        if ( str_starts_with( $path, '/' ) ) {
232            return true;
233        }
234
235        if ( wfIsWindows() ) {
236            if ( str_starts_with( $path, '\\' ) ) {
237                return true;
238            }
239            if ( preg_match( '!^[a-zA-Z]:[/\\\\]!', $path ) ) {
240                return true;
241            }
242        }
243
244        return false;
245    }
246
247    protected function getExtensionInfo( string $extName ): ?array {
248        // NOTE: Don't go by the extension registry, since some extensions
249        //       register under a name different from what is used in wfLoadExtension.
250        //       E.g. AbuseFilter is registered as "Abuse Filter" with a space.
251
252        $config = SettingsBuilder::getInstance()->getConfig();
253        $extDir = $config->get( MainConfigNames::ExtensionDirectory );
254        $skinDir = $config->get( MainConfigNames::StyleDirectory );
255
256        $extension = [];
257        if ( file_exists( "$extDir/$extName/extension.json" ) ) {
258            $extension['path'] = "$extDir/$extName/extension.json";
259            $extension['namespace'] = "MediaWiki\\Extension\\$extName";
260        } elseif ( file_exists( "$skinDir/$extName/skin.json" ) ) {
261            $extension['path'] = "$skinDir/$extName/skin.json";
262            $extension['namespace'] = "MediaWiki\\Skins\\$extName";
263        } else {
264            return null;
265        }
266
267        return $extension;
268    }
269
270    private function loadScriptFile( string $scriptFile ): string {
271        $maintClass = null;
272
273        // It's a file, include it
274        // If it returns something, it should be the name of the maintenance class.
275        $scriptClass = include $scriptFile;
276
277        // Traditional script files set the $maintClass variable
278        // at the end of the file.
279        // @phan-suppress-next-line PhanImpossibleCondition Phan doesn't understand includes.
280        if ( $maintClass ) {
281            $scriptClass = $maintClass;
282        }
283
284        if ( !is_string( $scriptClass ) ) {
285            $this->error( "ERROR: The script file '{$scriptFile}' cannot be executed using MaintenanceRunner.\n" );
286            $this->error( "It does not set \$maintClass and does not return a class name.\n" );
287            $this->fatalError( "Try running it directly as a php script: php $scriptFile\n" );
288        }
289
290        return $scriptClass;
291    }
292
293    private function splitScript( string $script ): array {
294        // Support "$ext:$script" format for extensions
295        if ( preg_match( '!^(\w+):(.*)$!', $script, $m ) ) {
296            return [ $m[1], $m[2] ];
297        }
298
299        return [ null, $script ];
300    }
301
302    private function expandScriptFile( string $scriptName, ?array $extension ): string {
303        // Append ".php" if not present
304        $scriptFile = $scriptName;
305        if ( !str_ends_with( $scriptFile, '.php' ) ) {
306            $scriptFile .= '.php';
307        }
308
309        // If the path is not explicitly relative (starting with "./" or "../") and not absolute,
310        // then look in the maintenance dir.
311        if ( !preg_match( '!^\.\.?[/\\\\]!', $scriptFile ) && !self::isAbsolutePath( $scriptFile ) ) {
312            if ( $extension !== null ) {
313                // Look in the extension's maintenance dir
314                $scriptFile = dirname( $extension['path'] ) . "/maintenance/{$scriptFile}";
315            } else {
316                // It's a core script.
317                $scriptFile = MW_INSTALL_PATH . "/maintenance/{$scriptFile}";
318            }
319        }
320
321        return $scriptFile;
322    }
323
324    private function expandScriptClass( string $scriptName, ?array $extension ): string {
325        $scriptClass = $scriptName;
326
327        // Support "$ext:$script" format
328        if ( $extension ) {
329            $scriptClass = "{$extension['namespace']}\\Maintenance\\$scriptClass";
330        }
331
332        // Accept dot (.) as namespace separators as well.
333        // Backslashes are just annoying on the command line.
334        $scriptClass = strtr( $scriptClass, '.', '\\' );
335
336        return $scriptClass;
337    }
338
339    /**
340     * Preload the script file, so any defines in file level code are executed.
341     * This way, scripts can control what Setup.php does.
342     *
343     * @internal
344     * @param string $script
345     */
346    protected function preloadScriptFile( string $script ): void {
347        if ( $this->scriptClass !== null && class_exists( $this->scriptClass ) ) {
348            // We know the script class, and file-level code was executed because class_exists triggers auto-loading.
349            return;
350        }
351
352        [ $extName, $scriptName ] = $this->splitScript( $script );
353
354        if ( $extName !== null ) {
355            // Preloading is not supported. findScriptClass() will try to find the script later.
356            return;
357        }
358
359        $scriptClass = $this->expandScriptClass( $scriptName, null );
360        $scriptFile = $this->expandScriptFile( $scriptName, null );
361
362        if ( !class_exists( $scriptClass ) && file_exists( $scriptFile ) ) {
363            $scriptFileClass = $this->loadScriptFile( $scriptFile );
364            if ( $scriptFileClass ) {
365                $scriptClass = $scriptFileClass;
366            }
367        }
368
369        // NOTE: class_exists will trigger auto-loading, so file-level code in the script file will run.
370        if ( class_exists( $scriptClass ) ) {
371            // Set the script class name we found, so we don't try to load the file again!
372            $this->scriptClass = $scriptClass;
373        }
374
375        // Preloading failed. Let findScriptClass() try to find the script later.
376    }
377
378    /**
379     * @return class-string<Maintenance>
380     */
381    protected function getScriptClass(): string {
382        if ( $this->scriptClass === null ) {
383            if ( $this->runFromWrapper ) {
384                $this->scriptClass = $this->findScriptClass( $this->script );
385            } else {
386                $this->scriptClass = $this->script;
387            }
388        }
389
390        if ( !class_exists( $this->scriptClass ) ) {
391            $this->fatalError( "Script class {$this->scriptClass} not found.\n" );
392        }
393
394        return $this->scriptClass;
395    }
396
397    /**
398     * @internal
399     * @param string $script
400     *
401     * @return class-string<Maintenance>
402     */
403    protected function findScriptClass( string $script ): string {
404        [ $extName, $scriptName ] = $this->splitScript( $script );
405
406        if ( $extName !== null ) {
407            $extension = $this->getExtensionInfo( $extName );
408
409            if ( !$extension ) {
410                $this->fatalError( "Extension '{$extName}' not found.\n" );
411            }
412        } else {
413            $extension = null;
414        }
415
416        $scriptClass = $this->expandScriptClass( $scriptName, $extension );
417        $scriptFile = $this->expandScriptFile( $scriptName, $extension );
418
419        if ( !class_exists( $scriptClass ) && file_exists( $scriptFile ) ) {
420            $scriptFileClass = $this->loadScriptFile( $scriptFile );
421            if ( $scriptFileClass ) {
422                $scriptClass = $scriptFileClass;
423            }
424        }
425
426        if ( !class_exists( $scriptClass ) ) {
427            $this->fatalError( "Script '{$script}' not found (tried path '$scriptFile' and class '$scriptClass').\n" );
428        }
429
430        return $scriptClass;
431    }
432
433    /**
434     * MW_FINAL_SETUP_CALLBACK handler, for setting up the Maintenance object.
435     *
436     * @param SettingsBuilder $settings
437     */
438    public function setup( SettingsBuilder $settings ) {
439        // NOTE: this has to happen after the autoloader has been initialized.
440        $scriptClass = $this->getScriptClass();
441
442        $cls = new ReflectionClass( $scriptClass );
443        if ( !$cls->isSubclassOf( Maintenance::class ) ) {
444            $this->fatalError( "Class {$this->script} is not a subclass of Maintenance.\n" );
445        }
446
447        // Initialize the actual Maintenance object
448        try {
449            $this->scriptObject = new $scriptClass;
450            $this->scriptObject->setName( $this->getName() );
451        } catch ( Throwable $ex ) {
452            $this->fatalError(
453                "Failed to initialize Maintenance object.\n" .
454                "(Did you forget to call parent::__construct() in your maintenance script?)\n" .
455                "$ex\n"
456            );
457        }
458
459        if ( !$this->scriptObject instanceof Maintenance ) {
460            // This should never happen, we already checked if the class is a subclass of Maintenance!
461            throw new LogicException( 'Incompatible script object' );
462        }
463
464        // Inject runner stuff into the script's parameter definitions.
465        // This is mainly used when printing help.
466        $scriptParameters = $this->scriptObject->getParameters();
467
468        if ( $this->runFromWrapper ) {
469            $scriptParameters->setUsagePrefix( 'php ' . $this->parameters->getName() );
470        }
471
472        $scriptParameters->mergeOptions( $this->parameters );
473        $this->parameters = $scriptParameters;
474
475        // Ingest argv
476        $this->scriptObject->loadWithArgv( $this->scriptArgv );
477
478        // Basic checks and such
479        $this->scriptObject->setup();
480
481        // Set the memory limit
482        $this->adjustMemoryLimit();
483
484        // Override any config settings
485        $this->overrideConfig( $settings );
486    }
487
488    /**
489     * Returns the maintenance script name to show in the help message.
490     *
491     * @return string
492     */
493    public function getName(): string {
494        // Once one of the init methods was called, getArg( 0 ) should always
495        // return something.
496        return $this->parameters->getArg( 0 ) ?? 'UNKNOWN';
497    }
498
499    /**
500     * Normally we disable the memory_limit when running admin scripts.
501     * Some scripts may wish to actually set a limit, however, to avoid
502     * blowing up unexpectedly.
503     * @see Maintenance::memoryLimit()
504     * @return string
505     */
506    private function memoryLimit() {
507        if ( $this->parameters->hasOption( 'memory-limit' ) ) {
508            $limit = $this->parameters->getOption( 'memory-limit', 'max' );
509            $limit = trim( $limit, "\" '" ); // trim quotes in case someone misunderstood
510            return $limit;
511        }
512
513        $limit = $this->scriptObject->memoryLimit();
514        return $limit ?: 'max';
515    }
516
517    /**
518     * Adjusts PHP's memory limit to better suit our needs, if needed.
519     */
520    private function adjustMemoryLimit() {
521        $limit = $this->memoryLimit();
522        if ( $limit == 'max' ) {
523            $limit = -1; // no memory limit
524        }
525        if ( $limit != 'default' ) {
526            ini_set( 'memory_limit', $limit );
527        }
528    }
529
530    /**
531     * Define how settings are loaded (e.g. LocalSettings.php)
532     * @note Called before Setup.php
533     *
534     * @internal
535     * @return void
536     */
537    public function defineSettings() {
538        global $IP;
539
540        if ( $this->parameters->hasOption( 'conf' ) ) {
541            // Define the constant instead of directly setting $settingsFile
542            // to ensure consistency. wfDetectLocalSettingsFile() will return
543            // MW_CONFIG_FILE if it is defined.
544            define( 'MW_CONFIG_FILE', $this->parameters->getOption( 'conf' ) );
545
546            if ( !is_readable( MW_CONFIG_FILE ) ) {
547                $this->fatalError( "\nConfig file " . MW_CONFIG_FILE . " was not found or is not readable.\n\n" );
548            }
549        }
550        $settingsFile = wfDetectLocalSettingsFile( $IP );
551
552        if ( $this->parameters->hasOption( 'wiki' ) ) {
553            $wikiName = $this->parameters->getOption( 'wiki' );
554            $bits = explode( '-', $wikiName, 2 );
555            define( 'MW_DB', $bits[0] );
556            define( 'MW_PREFIX', $bits[1] ?? '' );
557            define( 'MW_WIKI_NAME', $wikiName );
558        } elseif ( $this->parameters->hasOption( 'server' ) ) {
559            // Provide the option for site admins to detect and configure
560            // multiple wikis based on server names. This offers --server
561            // as alternative to --wiki.
562            // See https://www.mediawiki.org/wiki/Manual:Wiki_family
563            $_SERVER['SERVER_NAME'] = $this->parameters->getOption( 'server' );
564        }
565
566        // Try to load the script file before running Setup.php if possible.
567        // This allows the script file to define constants that change the behavior
568        // of Setup.php.
569        // Note that this will only work reliably for core scripts.
570        if ( $this->runFromWrapper ) {
571            $this->preloadScriptFile( $this->script );
572        }
573
574        if ( !is_readable( $settingsFile ) ) {
575            // NOTE: Some maintenance scripts can (and need to) run without LocalSettings.
576            //       But we only know that once we have instantiated the Maintenance object.
577            //       So go into no-settings mode for now, and fail later of the script doesn't support it.
578            if ( !defined( 'MW_CONFIG_CALLBACK' ) ) {
579                define( 'MW_CONFIG_CALLBACK', __CLASS__ . '::emulateConfig' );
580            }
581            $this->withoutLocalSettings = true;
582        }
583    }
584
585    /**
586     * @param SettingsBuilder $settings
587     *
588     * @internal Handler for MW_CONFIG_CALLBACK, used when no LocalSettings.php was found.
589     */
590    public static function emulateConfig( SettingsBuilder $settings ) {
591        // NOTE: The config schema is already loaded at this point, so default values are known.
592
593        $settings->overrideConfigValues( [
594            // Server must be set, but we don't care to what
595            MainConfigNames::Server => 'https://unknown.invalid',
596            // If InvalidateCacheOnLocalSettingsChange is enabled, filemtime( MW_CONFIG_FILE ),
597            // which will produce a warning if there is no settings file.
598            MainConfigNames::InvalidateCacheOnLocalSettingsChange => false,
599        ] );
600    }
601
602    /**
603     * @param SettingsBuilder $settingsBuilder
604     *
605     * @return void
606     */
607    private function overrideConfig( SettingsBuilder $settingsBuilder ) {
608        $config = $settingsBuilder->getConfig();
609
610        if ( $this->scriptObject->getDbType() === Maintenance::DB_NONE ) {
611            $cacheConf = $config->get( MainConfigNames::LocalisationCacheConf );
612            if ( $cacheConf['storeClass'] === false
613                && ( $cacheConf['store'] == 'db'
614                    || ( $cacheConf['store'] == 'detect'
615                        && !$config->get( MainConfigNames::CacheDirectory ) ) )
616            ) {
617                $cacheConf['storeClass'] = LCStoreNull::class;
618                $settingsBuilder->putConfigValue( MainConfigNames::LocalisationCacheConf, $cacheConf );
619            }
620        }
621
622        $output = $this->parameters->getOption( 'profiler' );
623        if ( $output ) {
624            // Per-script profiling; useful for debugging
625            $profilerConf = $config->get( MainConfigNames::Profiler );
626            if ( isset( $profilerConf['class'] ) ) {
627                $profilerConf = [
628                    'sampling' => 1,
629                    'output' => [ $output ],
630                    'cliEnable' => true,
631                ] + $profilerConf;
632                // Override $wgProfiler. This is passed to Profiler::init() by Setup.php.
633                $settingsBuilder->putConfigValue( MainConfigNames::Profiler, $profilerConf );
634            }
635        }
636
637        $this->scriptObject->finalSetup( $settingsBuilder );
638    }
639
640    private function getServiceContainer(): MediaWikiServices {
641        return MediaWikiServices::getInstance();
642    }
643
644    /**
645     * Run the maintenance script.
646     *
647     * @note The process should exit immediately after this method returns.
648     * At that point, MediaWiki will already have been shut down.
649     * It is no longer safe to perform any write operations on the database.
650     *
651     * @note Any exceptions thrown by the maintenance script will cause this
652     * method to terminate the process after reporting the error to the user,
653     * without shutdown and cleanup.
654     *
655     * @return bool true on success, false on failure,
656     *         passed through from Maintenance::execute().
657     */
658    public function run(): bool {
659        $config = $this->getConfig();
660
661        // Apply warning thresholds and output mode to Profiler.
662        // This MUST happen after Setup.php calls MaintenanceRunner::setup,
663        // $wgSettings->apply(), and Profiler::init(). Otherwise, calling
664        // Profiler::instance() would create a ProfilerStub even when $wgProfiler
665        // and --profiler are set.
666        $limits = $config->get( MainConfigNames::TrxProfilerLimits );
667        $trxProfiler = Profiler::instance()->getTransactionProfiler();
668        $trxProfiler->setLogger( LoggerFactory::getInstance( 'rdbms' ) );
669        $trxProfiler->setExpectations( $limits['Maintenance'], __METHOD__ );
670        Profiler::instance()->setAllowOutput();
671
672        // Initialize main config instance
673        $this->scriptObject->setConfig( $config );
674
675        // Double check required extensions are installed
676        $this->scriptObject->checkRequiredExtensions();
677
678        if ( $this->withoutLocalSettings && !$this->scriptObject->canExecuteWithoutLocalSettings() ) {
679            $this->fatalError(
680                "\nThe LocalSettings.php file was not found or is not readable.\n" .
681                "Use --conf to specify an alternative config file.\n\n"
682            );
683        }
684
685        if ( $this->scriptObject->getDbType() == Maintenance::DB_NONE || $this->withoutLocalSettings ) {
686            // Be strict with maintenance tasks that claim to not need a database by
687            // disabling the storage backend.
688            MediaWikiServices::resetGlobalInstance( $config );
689            MediaWikiServices::getInstance()->disableStorage();
690        }
691
692        $this->scriptObject->validateParamsAndArgs();
693
694        // Do the work
695        try {
696            $success = $this->scriptObject->execute() !== false;
697
698            // Potentially debug globals
699            if ( $this->parameters->hasOption( 'globals' ) ) {
700                print_r( $GLOBALS );
701            }
702
703            $this->shutdown();
704
705            return $success;
706        } catch ( Exception $ex ) {
707            $exReportMessage = '';
708            while ( $ex ) {
709                $cls = get_class( $ex );
710                $exReportMessage .= "$cls from line {$ex->getLine()} of {$ex->getFile()}{$ex->getMessage()}\n";
711                $exReportMessage .= $ex->getTraceAsString() . "\n";
712                $ex = $ex->getPrevious();
713            }
714            $this->error( $exReportMessage );
715
716            // Exit now because process is in an unsafe state.
717            // Also to avoid DBTransactionError (T305730).
718            // Do not commit database writes, do not run deferreds, do not pass Go.
719            exit( 1 );
720        }
721    }
722
723    /**
724     * Output a message and terminate the current script.
725     *
726     * @param string $msg Error message
727     * @param int $exitCode PHP exit status. Should be in range 1-254.
728     * @return never
729     */
730    protected function fatalError( $msg, $exitCode = 1 ) {
731        $this->error( $msg );
732        exit( $exitCode );
733    }
734
735    /**
736     * @param string $msg
737     */
738    protected function error( string $msg ) {
739        // Print to stderr if possible, don't mix it in with stdout output.
740        if ( defined( 'STDERR' ) ) {
741            fwrite( STDERR, $msg );
742        } else {
743            echo $msg;
744        }
745    }
746
747    /**
748     * Should we execute the maintenance script, or just allow it to be included
749     * as a standalone class? It checks that the call stack only includes this
750     * function and "requires" (meaning was called from the file scope)
751     *
752     * @return bool
753     */
754    public static function shouldExecute() {
755        if ( !function_exists( 'debug_backtrace' ) ) {
756            // If someone has a better idea...
757            return MW_ENTRY_POINT === 'cli';
758        }
759
760        $bt = debug_backtrace();
761        $count = count( $bt );
762        if ( $bt[0]['class'] !== self::class || $bt[0]['function'] !== 'shouldExecute' ) {
763            return false; // last call should be to this function
764        }
765        $includeFuncs = [ 'require_once', 'require', 'include', 'include_once' ];
766        for ( $i = 1; $i < $count; $i++ ) {
767            if ( !in_array( $bt[$i]['function'], $includeFuncs ) ) {
768                return false; // previous calls should all be "requires"
769            }
770        }
771
772        return true;
773    }
774
775    /**
776     * Handler for register_shutdown_function
777     * @internal
778     * @return void
779     */
780    public function cleanup() {
781        if ( $this->scriptObject ) {
782            $this->scriptObject->cleanupChanneled();
783        }
784    }
785
786    /**
787     * Call before exiting CLI process for the last DB commit, and flush
788     * any remaining buffers and other deferred work.
789     *
790     * Equivalent to MediaWiki::restInPeace which handles shutdown for web requests,
791     * and should perform the same operations and in the same order.
792     *
793     * @since 1.41
794     */
795    private function shutdown() {
796        $lbFactory = null;
797        if (
798            $this->scriptObject->getDbType() !== Maintenance::DB_NONE &&
799            // Service might be disabled, e.g. when running install.php
800            !$this->getServiceContainer()->isServiceDisabled( 'DBLoadBalancerFactory' )
801        ) {
802            $lbFactory = $this->getServiceContainer()->getDBLoadBalancerFactory();
803            if ( $lbFactory->isReadyForRoundOperations() ) {
804                $lbFactory->commitPrimaryChanges( get_class( $this ) );
805            }
806
807            DeferredUpdates::doUpdates();
808        }
809
810        // Handle profiler outputs
811        // NOTE: MaintenanceRunner ensures Profiler::setAllowOutput() during setup
812        $profiler = Profiler::instance();
813        $profiler->logData();
814        $profiler->logDataPageOutputOnly();
815
816        MediaWiki::emitBufferedStatsdData(
817            $this->getServiceContainer()->getStatsdDataFactory(),
818            $this->getConfig()
819        );
820
821        if ( $lbFactory ) {
822            if ( $lbFactory->isReadyForRoundOperations() ) {
823                $lbFactory->shutdown( $lbFactory::SHUTDOWN_NO_CHRONPROT );
824            }
825        }
826    }
827
828}