Rename MagicWordwgVariableIDs hook to GetMagicVariableIDs

This makes the hook name consistent with GetDoubleUnderscoreIDs, and
is part of a set of related documentation changes clarifying the difference
between "magic words" (a localization infrastructure) and the various
functions which use magic words for localization, such as parser functions,
double underscore variables, magic variables, etc.

See also I621c888e3790a145ca9978f6b30ff1a8f685b64c.

Change-Id: Ie2a6df4b179a360fb7cdfb219e915bedff501d1d

RELEASE-NOTES-1.35

@@ -1082,7 +1082,9 @@ because of Phabricator reports.
 * The ParserGetVariableValueVarCache hook has been deprecated.
 * When using the ParserGetVariableValueSwitch hook, the following unusual
   uses have been deprecated: modifying the passed $magicWordId or failing to
-  cache the returned value in $variableCache.
+  cache the returned value in $variableCache.  The related
+  MagicWordwgVariableIDs hook has been deprecated and renamed; use
+  the GetMagicVariableIDs hook instead.
 * The following Parser properties have been deprecated:
   - ::$mTagHooks
   - ::$mFunctionHooks

docs/hooks.txt

@@ -1612,9 +1612,9 @@ $refreshCache: If set, refreshes the diff cache
 $unhide: If set, allow viewing deleted revs
 &$differenceEngine: The difference engine object to be used for the diff
 
-'GetDoubleUnderscoreIDs': Modify the list of behavior switch (double
+'GetDoubleUnderscoreIDs': Modify the list of behavior switches (double
-underscore) magic words. Called by MagicWord.
+underscore). Called by MagicWordFactory.
-&$doubleUnderscoreIDs: array of strings
+&$doubleUnderscoreIDs: array of magic word identifiers
 
 'GetExtendedMetadata': Get extended file metadata for the API
 &$combinedMeta: Array of the form:
@@ -1686,6 +1686,9 @@ $query: query options as string passed to Title::getLocalURL()
 'GetLogTypesOnUser': Add log types where the target is a userpage
 &$types: Array of log types
 
+'GetMagicVariableIDs': Modify the list of magic variables.
+&$variableIDs: array of magic word identifiers
+
 'GetMetadataVersion': Modify the image metadata version currently in use. This
 is used when requesting image metadata from a ForeignApiRepo. Media handlers
 that need to have versioned metadata should add an element to the end of the

includes/Hook/GetDoubleUnderscoreIDsHook.php

@@ -8,12 +8,14 @@ namespace MediaWiki\Hook;
  */
 interface GetDoubleUnderscoreIDsHook {
 	/**
-	 * Use this hook to modify the list of behavior switch (double
+	 * Use this hook to modify the list of behavior switches (double
-	 * underscore) magic words. This hook is called by MagicWord.
+	 * underscore variables in wikitext).  Behavior switches are localized
+	 * with the magic word system, and this hook is called by
+	 * MagicWordFactory.
 	 *
 	 * @since 1.35
 	 *
-	 * @param string[] &$doubleUnderscoreIDs Array of strings
+	 * @param string[] &$doubleUnderscoreIDs Array of magic word identifiers
 	 * @return bool|void True or no return value to continue or false to abort
 	 */
 	public function onGetDoubleUnderscoreIDs( &$doubleUnderscoreIDs );

includes/Hook/GetMagicVariableIDsHook.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace MediaWiki\Hook;
+
+/**
+ * @stable for implementation
+ * @ingroup Hooks
+ */
+interface GetMagicVariableIDsHook {
+	/**
+	 * Use this hook to modify the list of magic variables.
+	 * Magic variables are localized with the magic word system,
+	 * and this hook is called by MagicWordFactory.
+	 *
+	 * @since 1.35
+	 *
+	 * @param string[] &$variableIDs array of magic word identifiers
+	 * @return bool|void True or no return value to continue or false to abort
+	 */
+	public function onGetMagicVariableIDs( &$variableIDs );
+}

includes/Hook/MagicWordwgVariableIDsHook.php

@@ -3,7 +3,7 @@
 namespace MediaWiki\Hook;
 
 /**
- * @stable for implementation
+ * @deprecated since 1.35, use GetMagicVariableIDsHook instead.
  * @ingroup Hooks
  */
 interface MagicWordwgVariableIDsHook {

includes/HookContainer/DeprecatedHooks.php

@@ -49,6 +49,7 @@ class DeprecatedHooks {
 		'InternalParseBeforeSanitize' => [ 'deprecatedVersion' => '1.35' ],
 		'LinkBegin' => [ 'deprecatedVersion' => '1.28' ],
 		'LinkEnd' => [ 'deprecatedVersion' => '1.28' ],
+		'MagicWordwgVariableIDs' => [ 'deprecatedVersion' => '1.35', 'silent' => true ],
 		'NewRevisionFromEditComplete' => [ 'deprecatedVersion' => '1.35' ],
 		'PageContentSave' => [ 'deprecatedVersion' => '1.35', 'silent' => true ],
 		'ParserBeforeTidy' => [ 'deprecatedVersion' => '1.35' ],

includes/HookContainer/HookRunner.php

@@ -182,6 +182,7 @@ class HookRunner implements
 	\MediaWiki\Hook\GetLocalURL__ArticleHook,
 	\MediaWiki\Hook\GetLocalURL__InternalHook,
 	\MediaWiki\Hook\GetLogTypesOnUserHook,
+	\MediaWiki\Hook\GetMagicVariableIDsHook,
 	\MediaWiki\Hook\GetMetadataVersionHook,
 	\MediaWiki\Hook\GetNewMessagesAlertHook,
 	\MediaWiki\Hook\GetRelativeTimestampHook,
@@ -1913,6 +1914,13 @@ class HookRunner implements
 		);
 	}
 
+	public function onGetMagicVariableIDs( &$variableIDs ) {
+		return $this->container->run(
+			'GetMagicVariableIDs',
+			[ &$variableIDs ]
+		);
+	}
+
 	public function onGetMetadataVersion( &$version ) {
 		return $this->container->run(
 			'GetMetadataVersion',

includes/MagicWord.php

@@ -49,7 +49,10 @@ use MediaWiki\MediaWikiServices;
  * ];
  * @endcode
  *
- * For magic words which are also Parser variables, add a MagicWordwgVariableIDs
+ * For magic words which name Parser double underscore names, add a
+ * GetDoubleUnderscoreIDs hook. Use string keys.
+ *
+ * For magic words which name Parser magic variables, add a GetMagicVariableIDs
  * hook. Use string keys.
  *
  * @ingroup Parser

includes/MagicWordFactory.php

@@ -242,6 +242,7 @@ class MagicWordFactory {
 		if ( !$this->mVariableIDsInitialised ) {
 			# Get variable IDs
 			$this->hookRunner->onMagicWordwgVariableIDs( $this->mVariableIDs );
+			$this->hookRunner->onGetMagicVariableIDs( $this->mVariableIDs );
 			$this->mVariableIDsInitialised = true;
 		}
 		return $this->mVariableIDs;