Manual:Writing maintenance scripts

Version 1.16 of MediaWiki introduced the maintenance class (Maintenance.php) to make it easier to write command-line MediaWiki maintenance scripts.

This is written as a step-by-step tutorial.

Example Script

To describe writing these maintenance scripts, we'll walk through an helloWorld.php, a script that simply prints “Hello, World”. This program contains the minimum amount of code needed to run as well as the expected copyright header:

1. <?php
   

3. /**
   

4.  * To the extent possible under law,  I, Mark Hershberger, have waived all copyright and
   

5.  * related or neighboring rights to Hello World. This work is published from United States.
   

6.  *
   

7.  * @copyright CC0 http://creativecommons.org/publicdomain/zero/1.0/
   

8.  * @author Mark A. Hershberger <mah@everybody.org>
   

9.  * @ingroup Maintenance
   

10.  */
    

12. require_once( dirname( __FILE__ ) . "/Maintenance.php" );
    

14. class HelloWorld extends Maintenance {
    

15.         public function execute() {
    

16.                 echo "Hello, World!\n";
    

17.         }
    

18. }
    

20. $maintClass = 'HelloWorld';
    

21. if( defined('RUN_MAINTENANCE_IF_MAIN') ) {
    

22.   require_once( RUN_MAINTENANCE_IF_MAIN );
    

23. } else {
    

24.   require_once( DO_MAINTENANCE ); # Make this work on versions before 1.17
    

25. }
    

The program will just print out “Hello, World!” but already has a --help (and other command line options). Sample output:

$ php helloWorld.php
Hello, World!
$ php helloWorld.php --help

Usage: php helloWorld.php [--conf|--dbpass|--dbuser|--globals|--help|--quiet|--wiki]
    conf : Location of LocalSettings.php, if not default
    dbpass : The password to use for this script
    dbuser : The DB user to use for this script
    globals : Output globals at the end of processing for debugging
    help : Display this help message
    quiet : Whether to supress non-error output
    wiki : For specifying the wiki ID

An overview:

Line 12

require_once( dirname( __FILE__ ) . "/Maintenance.php" );

Of course, if we're going to write a maintenance script, we have to include Maintenance.php. This takes care of setting up Autoloading and the like. It is best to use the full path to Maintenance.php.

Line 14

class HelloWorld extends Maintenance {

We override Maintenance class and then, in

Line 20 & 21

$maintClass = 'HelloWorld'; require_once( RUN_MAINTENANCE_IF_MAIN );

tell the Maintenance class to run the script using the HelloWorld class, only if being executed from the command line.

Line 15

The execute() function that we've provided is executed.

Option and Argument Parsing

Greeting the world is all well and good, but we want to be able to greet individuals, too.

To add an option, add a constructor with a call addOption() and update the execute() method to use the new option:

15.         public function __construct() {
    

16.                 parent::__construct();
    

18.                 $this->addOption( 'name', 'Who to say Hello to', false, true);
    

19.         }
    

21.         public function execute() {
    

22.                 $name = $this->getOption( 'name', 'World' );
    

23.                 echo "Hello, $name!\n";
    

24.         }
    

This time, when executed, the output of the helloWorld.php script changes depending on the argument provided:

$ php helloWorld.php
Hello, World!
$ php helloWorld.php --name=Mark
Hello, Mark!
$ php helloWorld.php --help
Usage: php helloWorld.php [--conf|--dbpass|--dbuser|--globals|--help|--name|--quiet|--wiki]
…
    name : Who to say Hello to

I18N

In order for the maintenance script to use the i18n file, it needs to be set in the appropriate place. Generally, this should be after the constructor. It is probably best to put it in the execute() function.

 function execute() {
   // Load the installer's i18n file
   global $wgExtensionMessagesFiles;
   $wgExtensionMessagesFiles['MediawikiInstaller'] =
     './includes/installer/Installer.i18n.php';
   // Body of execute function ...
 }

Language:	English