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

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

スクリプトの例

まずhelloWorld.php管理スクリプトによって簡単に"Hello, World"と出力します。このプログラムを走らせて予定される著作権ヘッダを得るのに最低必要なコードをふくみます (その他のヘッダは著作権ヘッダで説明します):

<?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 dependant 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を加えました。これにより議論の解析方式とコンソール読み出し、データベース入手の方法をそなえた抽象クラス管理を定義します。Maintenance.phpのフルパスを使うと最善です。

class HelloWorld extends Maintenance {

管理クラスを延長するため

$maintClass = HelloWorld::class;

require_once RUN_MAINTENANCE_IF_MAIN;

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

	public function execute() {

定義した実行() 関数は実行され、スクリプトが働きます。

説明の追加

"But what is this maintenance script for?" I can hear you asking.

We can put a description at the top of the "--help" output by using the addDescription method in our constructor:

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

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

The output now gives us the description:

$ php helloWorld.php --help

Say hello.

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

オプションと引数の解析

世の中に対して広く呼びかけることはすばらしいし、一人ひとりをお迎えできるようになることも目指します。

To add a command-line option, add a constructor to class HelloWorld that calls Maintenance's addOption() and update the execute() method to use the new option. addOption()'s parameters are $name, $description, $required = false, $withArg = false, $shortName = false, so:

	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 );
	}

そのwiki (と同様にwikiファームも)拡張子を有効にしないと、これによりちょっとしたエラーメッセージが供給されます。 extension.json を使う拡張子だけで有効になります。

Be aware that classes defined by your extension will not be available until hitting the execute-function. Attempts to create instances prior to this, e.g. in the constructor, will cause class not found exceptions.

Writing tests

It's recommended to write tests for your maintenance scripts, like with any other class. See the Maintenance scripts guide for help and examples.