Handbuch:Wartungsskripte schreiben

Dies ist eine Schritt-für-Schritt-Anleitung zum Schreiben eines Wartungsskripts basierend auf der Maintenance-Klasse (siehe Maintenance.php ), die in MediaWiki 1.16 eingeführt wurde, um das Schreiben von MediaWiki-Wartungsskripten für die Befehlszeile zu vereinfachen.

Beispielskript

Wir gehen ein helloWorld.php-Wartungsskript durch, das einfach "Hello, World" ausgibt. Dieses Programm enthält die Mindestmenge an Code, die zum Ausführen benötigt wird, sowie den erwarteten Copyright-Header (für alternative Header siehe Copyright-Header):

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

$ php helloWorld.php
Hello, World!

MediaWiki core

<?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-Erweiterung

<?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";

Wir schließen Maintenance.php ein. Dies definiert class Maintenance, das eine Methode zum Analysieren von Argumenten, zum Lesen der Konsole, zum Abrufen der Datenbank usw. hat. Es ist am besten, den vollständigen Pfad zu $3 zu verwenden.

class HelloWorld extends Maintenance {

Wir erweitern die Maintenance-Klasse und dann mit

$maintClass = HelloWorld::class;
require_once RUN_MAINTENANCE_IF_MAIN;

Sag der Klasse Maintenance, dass sie das Skript mit unserer Klasse HelloWorld nur dann ausführen soll, wenn es von der Kommandozeile aus ausgeführt wird.

Intern lädt RUN_MAINTENANCE_IF_MAIN eine weitere Datei doMaintenance.php, die MediaWiki-Klassen und -Konfigurationen automatisch lädt, und dann

	public function execute() {

Die execute()-Funktion, die wir definiert haben, wird ausgeführt, und unser Skript erledigt seine Arbeit.

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")
…

Eine Beschreibung hinzufügen

"Aber, für was ist dieses Wartungsskript?" Ich kann dich fragen hören.

Wir können eine Beschreibung oben in die Ausgabe von "--help" einfügen, indem wir die Methode addDescription in unserem Konstruktor verwenden:

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

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

Die Ausgabe gibt uns nun die Beschreibung:

$ php helloWorld.php --help

Say hello.

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

Parsing von Optionen und Argumenten

Die Welt zu grüßen ist schön und gut, aber wir wollen auch Einzelpersonen begrüßen können.

Um eine Kommandozeilenoption hinzuzufügen, fügst du einen Konstruktor zu class HelloWorld hinzu, der Maintenance's addOption() aufruft und aktualisierst die Methode execute(), um die neue Option zu verwenden. Die Parameter von addOption() sind $name, $description, $required = false, $withArg = false, $shortName = false, also:

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

Diesmal ändert sich die Ausgabe des helloWorld.php-Skripts bei der Ausführung je nach dem bereitgestellten Argument:

$ 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

Erweiterungen

MediaWiki Version:

≥ 1.28 Gerrit change 301709

Wenn dein Wartungsskript für eine Erweiterung gedacht ist, solltest du eine Anforderung hinzufügen, dass die Erweiterung installiert ist:

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

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

Meistens liefert dies eine nette Fehlermeldung, wenn die Erweiterung auf diesem Wiki nicht aktiviert ist (wahrscheinlich auf Wiki-Farmen). 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.

Beachte, dass die von deiner Erweiterung definierten Klassen erst verfügbar sind, wenn du die Funktion execute() drückst. Versuche, vorher Instanzen zu erstellen, z. im Konstruktor, verursacht Klasse nicht gefunden Ausnahmen.

Schreibtests

Es wird empfohlen, wie bei jeder anderen Klasse, Tests für deine Wartungsskripte zu schreiben. Hilfe und Beispiele findest du im Handbuch Wartungsskripte.