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.

Leitfaden

Wir werden ein helloWorld.php-Wartungsskript durchgehen, das einfach "Hello, World" ausgibt. Dieses Programm enthält das Minimum an benötigtem Code (siehe auch Copyright-Kopfzeilen)

Das folgende Beispielprogramm gibt „Hello, World!“ aus.

The way to invoke maintenance scripts changed in 2023 with MediaWiki 1.40, with the new run.php being used to launch all maintenance scripts, rather than directly calling them by filename (although the latter remains supported for now). This tutorial covers both methods, and notes where there are differences between the systems.

MediaWiki Code

Command

$ ./maintenance/run HelloWorld
Hello, World!

Filename

maintenance/HelloWorld.php

Code

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

$maintClass = HelloWorld::class;
require_once RUN_MAINTENANCE_IF_MAIN;

MediaWiki-Erweiterung

Command

$ ./maintenance/run MyExtension:HelloWorld
Hello, World!

Filename

extensions/MyExtension/maintenance/HelloWorld.php

Code

<?php

namespace MediaWiki\Extension\MyExtension\Maintenance;

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

$maintClass = HelloWorld::class;
require_once RUN_MAINTENANCE_IF_MAIN;

Textbausteine erklärt

require_once __DIR__ . "/Maintenance.php";

Wir fügen Maintenance.php ein. Dies definiert class Maintenance, das die Grundlage für alle Wartungsskripte bildet, einschließlich der Möglichkeiten, Befehlszeilenargumente zu analysieren, Eingaben auf der Konsole zu lesen, sich mit einer Datenbank zu verbinden, usw.

class HelloWorld extends Maintenance {
}

Wir deklarieren unsere Unterklasse Maintenance.

$maintClass = HelloWorld::class;
require_once RUN_MAINTENANCE_IF_MAIN;

Weist die Klasse Maintenance an, das Skript mit unserer Klasse HelloWorld auszuführen, aber nur, wenn es von der Kommandozeile aus ausgeführt wird.

Intern lädt RUN_MAINTENANCE_IF_MAIN eine weitere Datei doMaintenance.php, welche die MediaWiki-Klassen und die Konfiguration automatisch lädt und dann unsere Funktion execute() ausführt.

	public function execute() {
	}

Die Funktion execute() ist der Einstiegspunkt für Wartungsskripte und enthält die Hauptlogik Ihres Skripts. Vermeiden Sie die Ausführung von Code aus dem Baukasten.

Wenn unser Programm von der Kommandozeile aus gestartet wird, kümmert sich das Wartung-Framework um die Initialisierung des MediaWiki-Kerns, der Konfiguration usw. und ruft dann diese Funktion auf.

Hilfe aufrufen

Eine der eingebauten Funktionen, über die alle Wartungsskripte verfügen, ist eine --help-Option. Das obige Beispiel Boilerplate würde die folgende Hilfeseite erzeugen:

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

Dies liefert eine nützliche Fehlermeldung, wenn die Erweiterung nicht aktiviert ist. Zum Beispiel könnte während der lokalen Entwicklung eine bestimmte Erweiterung noch nicht in LocalSettings.php aktiviert sein oder beim Betrieb einer Wikifarm könnte eine Erweiterung auf einer Teilmenge von Wikis aktiviert sein.

Beachten Sie, dass kein Code anders als über die Funktion execute() ausgeführt werden darf. Der Versuch, MediaWiki-Kerndienste, -Klassen oder -Funktionen aufzurufen oder Ihren eigenen Erweiterungscode vorher aufzurufen, führt zu Fehlern oder ist unzuverlässig und wird nicht unterstützt (z.B. außerhalb der Klassendeklaration oder im Konstruktor).

Profiling

Maintenance scripts support a --profiler option, which can be used to track code execution during a page action and report back the percentage of total code execution that was spent in any specific function.

See Manual:Profiling .

Tests erstellen

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