Allow extensions to add params to the update.php maintenance script

T110209 caused maintenance scripts to fail on unknown parameters,
which is normally desirable.  However, some extensions (notably
SemanticMediaWiki) need to support additional params and had no
way to add them to the list of expected parameters.  It will
now be possible them to update.php via a new hook:
MaintenanceUpdateAddParams.

Bug: T213893
Change-Id: Ia40949ccb2f32090f21e0f3f7e5b9c4aef322330

diff --git a/RELEASE-NOTES-1.33 b/RELEASE-NOTES-1.33
index 72a468b..2c4aa81 100644 (file)
--- a/RELEASE-NOTES-1.33
+++ b/RELEASE-NOTES-1.33
@@ -109,6 +109,7 @@ For notes on 1.32.x and older releases, see HISTORY.
   Content::getNativeData() for text-based content models.
 * (T214706) LinksUpdate::getAddedExternalLinks() and
   LinksUpdate::getRemovedExternalLinks() were introduced.
+* (T213893) Added 'MaintenanceUpdateAddParams' hook
 
 === External library changes in 1.33 ===
 ==== New external libraries ====

diff --git a/docs/hooks.txt b/docs/hooks.txt
index 139123d..e9ceb95 100644 (file)
--- a/docs/hooks.txt
+++ b/docs/hooks.txt
@@ -2198,6 +2198,16 @@ Special:LonelyPages.
 'MagicWordwgVariableIDs': When defining new magic words IDs.
 &$variableIDs: array of strings
 
+'MaintenanceUpdateAddParams': allow extensions to add params to the update.php
+maintenance script.
+&$params: array to populate with the params to be added. Array elements are keyed by
+the param name. Each param is an associative array that must include the following keys:
+  - desc The description of the param to show on --help
+  - require Is the param required? Defaults to false if not set.
+  - withArg Is an argument required with this option?  Defaults to false if not set.
+  - shortName Character to use as short name, or false if none.  Defaults to false if not set.
+  - multiOccurrence Can this option be passed multiple times?  Defaults to false if not set.
+
 'MaintenanceRefreshLinksInit': before executing the refreshLinks.php maintenance
 script.
 $refreshLinks: RefreshLinks object

diff --git a/maintenance/Maintenance.php b/maintenance/Maintenance.php
index 3403e82..30ae118 100644 (file)
--- a/maintenance/Maintenance.php
+++ b/maintenance/Maintenance.php
@@ -54,6 +54,18 @@ use Wikimedia\Rdbms\IMaintainableDatabase;
  * is the execute() method. See docs/maintenance.txt for more info
  * and a quick demo of how to use it.
  *
+ * Terminology:
+ *   params: registry of named values that may be passed to the script
+ *   arg list: registry of positional values that may be passed to the script
+ *   options: passed param values
+ *   args: passed positional values
+ *
+ * In the command:
+ *   mwscript somescript.php --foo=bar baz
+ * foo is a param
+ * bar is the option value of the option for param foo
+ * baz is the arg value at index 0 in the arg list
+ *
  * @since 1.16
  * @ingroup Maintenance
  */
@@ -69,13 +81,13 @@ abstract class Maintenance {
        // Const for getStdin()
        const STDIN_ALL = 'all';
 
-       // This is the desired params
+       // Array of desired/allowed params
        protected $mParams = [];
 
        // Array of mapping short parameters to long ones
        protected $mShortParamsMap = [];
 
-       // Array of desired args
+       // Array of desired/allowed args
        protected $mArgList = [];
 
        // This is the list of options that were actually passed
@@ -738,7 +750,6 @@ abstract class Maintenance {
                }
 
                $this->loadParamsAndArgs();
-               $this->maybeHelp();
 
                # Set the memory limit
                # Note we need to set it again later in cache LocalSettings changed it
@@ -758,8 +769,6 @@ abstract class Maintenance {
                while ( ob_get_level() > 0 ) {
                        ob_end_flush();
                }
-
-               $this->validateParamsAndArgs();
        }
 
        /**
@@ -979,7 +988,7 @@ abstract class Maintenance {
        /**
         * Run some validation checks on the params, etc
         */
-       protected function validateParamsAndArgs() {
+       public function validateParamsAndArgs() {
                $die = false;
                # Check to make sure we've got all the required options
                foreach ( $this->mParams as $opt => $info ) {
@@ -1005,9 +1014,7 @@ abstract class Maintenance {
                        }
                }
 
-               if ( $die ) {
-                       $this->maybeHelp( true );
-               }
+               $this->maybeHelp( $die );
        }
 
        /**

diff --git a/maintenance/doMaintenance.php b/maintenance/doMaintenance.php
index 1f1a4c7..1c53fe8 100644 (file)
--- a/maintenance/doMaintenance.php
+++ b/maintenance/doMaintenance.php
@@ -90,6 +90,8 @@ $maintenance->checkRequiredExtensions();
 // This avoids having long running scripts just OOM and lose all the updates.
 $maintenance->setAgentAndTriggers();
 
+$maintenance->validateParamsAndArgs();
+
 // Do the work
 $success = $maintenance->execute();
 

diff --git a/maintenance/getConfiguration.php b/maintenance/getConfiguration.php
index de6e87a..f56729c 100644 (file)
--- a/maintenance/getConfiguration.php
+++ b/maintenance/getConfiguration.php
@@ -56,7 +56,7 @@ class GetConfiguration extends Maintenance {
                $this->addOption( 'format', implode( ', ', self::$outFormats ), false, true );
        }
 
-       protected function validateParamsAndArgs() {
+       public function validateParamsAndArgs() {
                $error_out = false;
 
                # Get the format and make sure it is set to a valid default value

diff --git a/maintenance/update.php b/maintenance/update.php
index 2a1feb4..50fb6dc 100755 (executable)
--- a/maintenance/update.php
+++ b/maintenance/update.php
@@ -242,6 +242,24 @@ class UpdateMediaWiki extends Maintenance {
                        'manualRecache' => false,
                ];
        }
+
+       public function validateParamsAndArgs() {
+               // Allow extensions to add additional params.
+               $params = [];
+               Hooks::run( 'MaintenanceUpdateAddParams', [ &$params ] );
+               foreach ( $params as $name => $param ) {
+                       $this->addOption(
+                               $name,
+                               $param['desc'],
+                               $param['require'] ?? false,
+                               $param['withArg'] ?? false,
+                               $param['shortName'] ?? false,
+                               $param['multiOccurrence'] ?? false
+                       );
+               }
+
+               parent::validateParamsAndArgs();
+       }
 }
 
 $maintClass = UpdateMediaWiki::class;