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

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

スクリプトの例

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

<?php

/**
 * To the extent possible under law,  I, Mark Hershberger, have waived all copyright and
 * related or neighboring rights to Hello World. This work is published from the
 * United States.
 *
 * @copyright CC0 http://creativecommons.org/publicdomain/zero/1.0/
 * @author Mark A. Hershberger <mah@everybody.org>
 * @ingroup Maintenance
 */

require_once __DIR__ . '/Maintenance.php';

class HelloWorld extends Maintenance {
	public function execute() {
		$this->output( "Hello, World!" );
	}
}

$maintClass = HelloWorld::class;

require_once RUN_MAINTENANCE_IF_MAIN;

このプログラムは「Hello, World!」と出力するだけですが、既にオプション --help があります (その他のコマンドラインのオプションも)。出力の例:

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

Usage: php helloWorld.php [--conf|--dbgroupdefault|--dbpass|--dbuser|--globals|--help|--memory-limit|--mwdebug|--profiler|--quiet|--server|--wiki]

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
    --globals: Output globals at the end of processing for debugging
    --memory-limit: Set a specific memory limit for the script, "max"
        for no limit or "default" to avoid changing it
    --server: The protocol and server name to use in URLs, e.g.
        https://en.wikipedia.org. This is sometimes necessary because server name
        detection may fail in command line scripts.
    --profiler: Profiler output format (usually "text")
    --mwdebug: Enable built-in MediaWiki development settings

Script dependent parameters:
    --dbuser: The DB user to use for this script
    --dbpass: The password to use for this script
    --dbgroupdefault: The default DB group to use.

$

概要:

require_once __DIR__ . "/Maintenance.php";

Maintenance.php をインクルードしました。これにより、引数の解析、コンソール読み出し、データベース取得のメソッドを備えた abstract class Maintenance を定義します。Maintenance.php へのフルパスを使うと最善です。

class HelloWorld extends Maintenance {

Maintenance クラスを拡張し、さらに

$maintClass = HelloWorld::class;

require_once RUN_MAINTENANCE_IF_MAIN;

コマンドラインから実行した場合のみ、Maintenance クラスに HelloWorld クラスを使用してスクリプトを実行するように指示します。 内部的には、RUN_MAINTENANCE_IF_MAIN が別ファイルの doMaintenance.php を読み込み MediaWiki クラスと設定を自動的に読み込むと次に

	public function execute() {

定義した execute() 関数が実行され、スクリプトが動作します。

説明の追加

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

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

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

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

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

$ php helloWorld.php --help

Say hello.

Usage: php helloWorld.php [--conf|--dbgroupdefault|--dbpass|--dbuser|--globals|--help|--memory-limit|--mwdebug|--profiler|--quiet|--server|--wiki]
…

オプションと引数の解析

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

コマンドライン オプションを追加するには、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 [--conf|--dbgroupdefault|--dbpass|--dbuser|--globals|--help|--memory-limit|--mwdebug|--name|--profiler|--quiet|--server|--wiki]
…
Script specific parameters:
    --name: Who to say Hello to

拡張機能

MediaWiki バージョン:

≧ 1.28 Gerrit change 301709

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

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

たいていの場合、これは拡張機能がそのウィキで (おそらくウィキファームで) 有効になっていない場合に、親切なエラー メッセージを提供します。 これは、extension.json を使用する拡張機能に対してのみ機能します。

拡張機能で定義されたクラスは、execute() 関数を叩くまで利用できないため注意が必要です。 これより前に (例えばコンストラクターの中で)、インスタンスを作成しようとすると、クラスが見つからないという例外が発生します。

テストを書く

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