Manual:Escrevendo scripts de manutenção

From MediaWiki.org
Jump to navigation Jump to search
This page is a translated version of the page Manual:Writing maintenance scripts and the translation is 38% complete.

Outdated translations are marked like this.
Other languages:
English • ‎español • ‎français • ‎polski • ‎português do Brasil • ‎čeština • ‎українська • ‎日本語 • ‎ꯃꯤꯇꯩ ꯂꯣꯟ

Na versão 1.16 do MediaWiki, foi introduzida a classe de manutenção (Maintenance.php ) para tornar mais fácil a escrita de scripts de linha de comando de manutenção do software.

Exemplo de script

Para descrever a criação de scripts de manutenção, vamos escrever um arquivo helloWorld.php, um script que simplesmente imprime “Hello, World”. Este programa contém a quantidade mínima de código necessário para ser executado, bem como o cabeçalho de direitos autorais esperado (para cabeçalhos alternativos, consulte cabeçalhos de direitos autorais):

 1 <?php
 2 
 3 /**
 4  * To the extent possible under law,  I, Mark Hershberger, have waived all copyright and
 5  * related or neighboring rights to Hello World. This work is published from the
 6  * United States.
 7  *
 8  * @copyright CC0 http://creativecommons.org/publicdomain/zero/1.0/
 9  * @author Mark A. Hershberger <mah@everybody.org>
10  * @ingroup Maintenance
11  */
12 
13 require_once __DIR__ . '/Maintenance.php';
14 
15 class HelloWorld extends Maintenance {
16 	public function execute() {
17 		echo "Hello, World!\n";
18 	}
19 }
20 
21 $maintClass = HelloWorld::class;
22 
23 require_once RUN_MAINTENANCE_IF_MAIN;

O programa simplesmente imprimirá “Hello, World!” porém já possui um parâmetro --help (e outras opções de linha de comando). Saída de exemplo:

$ 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.

$

Uma visão geral:

13 require_once __DIR__ . "/Maintenance.php";
Logicamente, se vamos escrever um script de manutenção, temos que incluir Maintenance.php. Ele cuida da criação do Autoloading e itens afins. O melhor é usar o caminho completo para Maintenance.php.
15 class HelloWorld extends Maintenance {
Nós substituímos a classe Maintenance e, em seguida, em
21 $maintClass = HelloWorld::class;
22 
23 require_once RUN_MAINTENANCE_IF_MAIN;
dizemos para a classe Maintenance executar o script usando a classe HelloWorld, somente se for executado a partir da linha de comando.

Internally, RUN_MAINTENANCE_IF_MAIN loads another file doMaintenance.php which autoloads MediaWiki classes and configuration, and then

16 	public function execute() {
A função execute() que nós fornecemos é executada.

Adding a description

"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:

16 	public function __construct() {
17 		parent::__construct();
18 
19 		$this->addDescription( 'Say hello.' );
20 	}

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]
…

Análise de opções e argumentos

Cumprimentar o mundo está tudo bem, mas nós queremos ser capazes de cumprimentar as pessoas, também.

Para adicionar uma opção, adicione um construtor com uma chamada addOption() e atualize o método execute() para usar a nova opção. Os parâmetros de addOption()são $name, $description, $required = false, $withArg = false, $shortName = false:

16 	public function __construct() {
17 		parent::__construct();
18 
19 		$this->addDescription( 'Say hello.' );
20 		$this->addOption( 'name', 'Who to say Hello to', false, true );
21 	}
22 
23 	public function execute() {
24 		$name = $this->getOption( 'name', 'World' );
25 		echo "Hello, $name!\n";
26 	}

Desta vez, quando executado, a saída do script helloWorld.php muda, dependendo do argumento fornecido:

$ 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

Extensions

Versão do MediaWiki: 1.28
Gerrit change 301709

If your maintenance script is for an extension, then you should add a requirement that the extension is installed:

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

Mostly this provides a nice error message when the extension is not enabled on that wiki (likely on wiki farms). This will only work for extensions that use extension.json .

Writing tests

It's recommended to write tests for your maintenance scripts, like with any other class. See the Manual:PHP unit testing/Writing unit tests#Maintenance scripts guide for help and examples.