TLDR: Invoking maintenance scripts directly will be deprecated in MW 1.40, use maintenance/run.php instead. This affects anyone managing a MediaWiki installation, for development, testing, or production use.

Until now, MediaWiki maintenance scripts have been handled standalone PHP scripts - for instance, to run the script that outputs the MediaWiki version, you would use:

> php maintenance/version.php

Starting with MediaWiki 1.40, this is deprecated. The preferred way to run maintenance scripts is now by name, using the maintenance runner:

> php maintenance/run.php version

Similarly, the preferred way to run the updater is now:

> php maintenance/run.php update

The script to run cal also be specified using the full path of the script file, or the full PHP class name of a subclass of the Maintenance class. For more details, run

> php maintenance/run.php --help

Rationale and History:

Treating maintenance scripts as standalone PHP scripts requires some boilerplate code to be present at the top and at the bottom of every file. This is error prone and makes it difficult to update the maintenance framework. But more importantly,

for this boilerplate to work, the location of the MediaWiki installation has to be known relative to the maintenance script, which is not reliably possible for scripts defined in extensions.

A similar problem arises if the maintenance script needs a base class other than the default Maintenance class: since the class is loaded before MediaWiki is initialized, the autoloader is not yet in place, and the file containing the base class needs to be included explicitly.

These and similar issues can be avoided by creating a wrapper script that loads and executes the actual maintenance class. This way, the maintenance wrapper can initialize MediaWiki before passing control to the script.

I propose creating such a wrapper as an RFC in 2018 (T99268)[^1], which was approved in 2019. However, implementing the proposal proved challenging, and soon stalled. I picked it up again as a side project after working on overhauling the configuration and bootstrapping code in early 2022: With the introduction of SettingsBuilder, it became much simpler to create a MaintenanceRunner class, because it was no longer necessary to juggle global variables.

Several bits and pieces got reviewed and merged over the course of 2022 (shout out to Amir, Tim, Timo, and everyone who contributed). Now the runner is ready, and we should stop calling maintenance scripts directly.

For now, existing maintenance scripts will function both ways[^2] : when called using the runner, or directly. However, newly created maintenance scripts should not be required to be callable as standalone scripts. So it's best to change all callers to use the wrapper.

This should now work for nearly all[^2] cases, though there are still a couple of rough edges to be smoothed out. If you are running MediaWiki 1.40, please try the new mechanism, and report any isses on Phabricator.

Thanks,

Daniel

[^1] https://phabricator.wikimedia.org/T99268

[^2] with the exception over very old-school scripts that do not use the Maintenance base class and rely on CommandLineInc.php instead.