Manual:メンテナンススクリプトの作成

これは、MediaWiki 1.16 で導入されて書きやすくなったコマンドラインの MediaWiki 管理スクリプトを Maintenance クラス (Maintenance.php 参照)に基づいて書く方法を順番に解説したものです。

Boilerplate

ここでは、単に「Hello, World」と出力する helloWorld.php というメンテナンス スクリプトを説明します。このプログラムは、期待される著作権ヘッダーと同様に、実行に必要な最小限のコードを含んでいます (代替ヘッダーについては、著作権ヘッダーを参照してください):

The below example program will print "Hello, World!":

$ php helloWorld.php
Hello, World!

MediaWiki コア

<?php

require_once __DIR__ . '/Maintenance.php';

/**
 * Brief oneline description of Hello world.
 *
 * @since 1.17
 * @ingroup Maintenance
 */
class HelloWorld extends Maintenance {
	public function execute() {
		$this->output( 'Hello, World!' );
	}
}

$maintClass = HelloWorld::class;
require_once RUN_MAINTENANCE_IF_MAIN;

MediaWiki 拡張機能

<?php

namespace MediaWiki\Extension\Example\Maintenance;

$IP = getenv( 'MW_INSTALL_PATH' );
if ( $IP === false ) {
	$IP = __DIR__ . '/../../..';
}
require_once "$IP/maintenance/Maintenance.php";

/**
 * Brief oneline description of Hello world.
 */
class HelloWorld extends Maintenance {
	public function __construct() {
		parent::__construct();
		$this->requireExtension( 'Extension' );
	}

	public function execute() {
		$this->output( 'Hello, World!' );
	}
}

$maintClass = HelloWorld::class;
require_once RUN_MAINTENANCE_IF_MAIN;

Boilerplate explained

require_once __DIR__ . "/Maintenance.php";

We include Maintenance.php. This defines class Maintenance which provides the basis for all maintenance scripts, including facilities to parse command-line arguments, read console input, connect to a database, etc.

class HelloWorld extends Maintenance {

We declare our Maintenance subclass.

$maintClass = HelloWorld::class;
require_once RUN_MAINTENANCE_IF_MAIN;

コマンドラインから実行した場合のみ、Maintenance クラスに HelloWorld クラスを使用してスクリプトを実行するように指示します。

内部的には、RUN_MAINTENANCE_IF_MAIN が別ファイルの doMaintenance.php を読み込み MediaWiki クラスと設定を自動的に読み込むと次に

	public function execute() {

The execute() method is the entrypoint for maintenance scripts, and is where the main logic of your script will be. Avoid running any code from the constructor.

When our program is run from the command-line, the core maintenance framework will take care of initialising MediaWiki core and configuration etc, and then it will invoke this method.

Help command

One of the built-in features that all maintenance scripts enjoy is a --help option. The above example boilerplate would produce the following help page:

$ php helloWorld.php --help

Usage: php helloWorld.php […]

Generic maintenance parameters:
    --help (-h): Display this help message
    --quiet (-q): Whether to suppress non-error output
    --conf: Location of LocalSettings.php, if not default
    --wiki: For specifying the wiki ID
    --server: The protocol and server name to use in URL
    --profiler: Profiler output format (usually "text")
…

説明の追加

「しかし、このメンテナンス スクリプトは何のためにあるのだろう?」 という声が聞こえてきそうです。

コンストラクターの addDescription メソッドを使用することで、「--help」の出力の先頭に説明を配置できます:

	public function __construct() {
		parent::__construct();

		$this->addDescription( 'Say hello.' );
	}

これで説明が出力されるようになりました:

$ php helloWorld.php --help

Say hello.

Usage: php helloWorld.php [--help]
…

オプションと引数の解析

世界に挨拶するのもいいですが、個人にも挨拶できるようにしたいですね。

コマンドライン オプションを追加するには、class HelloWorld に Maintenance の addOption() を呼び出すコンストラクターを追加し、execute() のメソッドを新しいオプションを使用するように更新します。 addOption() のパラメーターは $name, $description, $required = false, $withArg = false, $shortName = false であるため、以下のようにします:

	public function __construct() {
		parent::__construct();

		$this->addDescription( 'Say hello.' );
		$this->addOption( 'name', 'Who to say Hello to', false, true );
	}

	public function execute() {
		$name = $this->getOption( 'name', 'World' );
		$this->output( "Hello, $name!" );
	}

これにより、実行すると、与えられた引数によって helloWorld.php スクリプトの出力が変化するようになりました:

$ php helloWorld.php
Hello, World!
$ php helloWorld.php --name=Mark
Hello, Mark!
$ php helloWorld.php --help

Say hello.

Usage: php helloWorld.php […]
…
Script specific parameters:
    --name: Who to say Hello to

拡張機能

MediaWiki バージョン:

≧ 1.28 Gerrit change 301709

メンテナンス スクリプトが拡張機能向けである場合、拡張機能がインストールされていることを要件に追加する必要があります:

	public function __construct() {
		parent::__construct();
		$this->addOption( 'name', 'Who to say Hello to' );

		$this->requireExtension( 'FooBar' );
	}

これは、拡張機能が有効になっていない場合に、役立つエラー メッセージを提供します。 For example, during local development a particular extension might not yet be enabled in LocalSettings.php, or when operating a wiki farm an extension might be enabled on a subset of wikis.

Be aware that no code may be executed other than through the execute() method. Attempts to call MediaWiki core services, classes, or functions, or calling your own extension code prior to this, will cause errors or is unreliable and unsupported (e.g. ouside the class declaration, or in the constructor).

テストを書く

他のクラスと同じように、メンテナンス スクリプトのテストを書くことをお勧めします。 ヘルプと例は、メンテナンス スクリプトのガイドを参照してください。