1 files changed, 149 insertions, 27 deletions
diff --git a/includes/api/ApiModuleManager.php b/includes/api/ApiModuleManager.php
index 100392bf..a0300ab5 100644
--- a/includes/api/ApiModuleManager.php
+++ b/includes/api/ApiModuleManager.php
@@ -33,9 +33,21 @@
  */
 class ApiModuleManager extends ContextSource {
 
+	/**
+	 * @var ApiBase
+	 */
 	private $mParent;
+	/**
+	 * @var ApiBase[]
+	 */
 	private $mInstances = array();
+	/**
+	 * @var null[]
+	 */
 	private $mGroups = array();
+	/**
+	 * @var array[]
+	 */
 	private $mModules = array();
 
 	/**
@@ -47,13 +59,55 @@ class ApiModuleManager extends ContextSource {
 	}
 
 	/**
-	 * Add a list of modules to the manager
-	 * @param array $modules A map of ModuleName => ModuleClass
+	 * Add a list of modules to the manager. Each module is described
+	 * by a module spec.
+	 *
+	 * Each module spec is an associative array containing at least
+	 * the 'class' key for the module's class, and optionally a
+	 * 'factory' key for the factory function to use for the module.
+	 *
+	 * That factory function will be called with two parameters,
+	 * the parent module (an instance of ApiBase, usually ApiMain)
+	 * and the name the module was registered under. The return
+	 * value must be an instance of the class given in the 'class'
+	 * field.
+	 *
+	 * For backward compatibility, the module spec may also be a
+	 * simple string containing the module's class name. In that
+	 * case, the class' constructor will be called with the parent
+	 * module and module name as parameters, as described above.
+	 *
+	 * Examples for defining module specs:
+	 *
+	 * @code
+	 *  $modules['foo'] = 'ApiFoo';
+	 *  $modules['bar'] = array(
+	 *      'class' => 'ApiBar',
+	 *      'factory' => function( $main, $name ) { ... }
+	 *  );
+	 *  $modules['xyzzy'] = array(
+	 *      'class' => 'ApiXyzzy',
+	 *      'factory' => array( 'XyzzyFactory', 'newApiModule' )
+	 *  );
+	 * @endcode
+	 *
+	 * @param array $modules A map of ModuleName => ModuleSpec; The ModuleSpec
+	 *        is either a string containing the module's class name, or an associative
+	 *        array (see above for details).
 	 * @param string $group Which group modules belong to (action,format,...)
 	 */
 	public function addModules( array $modules, $group ) {
-		foreach ( $modules as $name => $class ) {
-			$this->addModule( $name, $group, $class );
+
+		foreach ( $modules as $name => $moduleSpec ) {
+			if ( is_array( $moduleSpec ) ) {
+				$class = $moduleSpec['class'];
+				$factory = ( isset( $moduleSpec['factory'] ) ? $moduleSpec['factory'] : null );
+			} else {
+				$class = $moduleSpec;
+				$factory = null;
+			}
+
+			$this->addModule( $name, $group, $class, $factory );
 		}
 	}
 
@@ -62,49 +116,100 @@ class ApiModuleManager extends ContextSource {
 	 * classes who wish to add their own modules to their lexicon or override the
 	 * behavior of inherent ones.
 	 *
-	 * @param string $group Name of the module group
 	 * @param string $name The identifier for this module.
+	 * @param string $group Name of the module group
 	 * @param string $class The class where this module is implemented.
+	 * @param callable|null $factory Callback for instantiating the module.
+	 *
+	 * @throws InvalidArgumentException
 	 */
-	public function addModule( $name, $group, $class ) {
+	public function addModule( $name, $group, $class, $factory = null ) {
+		if ( !is_string( $name ) ) {
+			throw new InvalidArgumentException( '$name must be a string' );
+		}
+
+		if ( !is_string( $group ) ) {
+			throw new InvalidArgumentException( '$group must be a string' );
+		}
+
+		if ( !is_string( $class ) ) {
+			throw new InvalidArgumentException( '$class must be a string' );
+		}
+
+		if ( $factory !== null && !is_callable( $factory ) ) {
+			throw new InvalidArgumentException( '$factory must be a callable (or null)' );
+		}
+
 		$this->mGroups[$group] = null;
-		$this->mModules[$name] = array( $group, $class );
+		$this->mModules[$name] = array( $group, $class, $factory );
 	}
 
 	/**
 	 * Get module instance by name, or instantiate it if it does not exist
-	 * @param string $moduleName module name
-	 * @param string $group optionally validate that the module is in a specific group
-	 * @param bool $ignoreCache if true, force-creates a new instance and does not cache it
-	 * @return mixed the new module instance, or null if failed
+	 *
+	 * @param string $moduleName Module name
+	 * @param string $group Optionally validate that the module is in a specific group
+	 * @param bool $ignoreCache If true, force-creates a new instance and does not cache it
+	 *
+	 * @return ApiBase|null The new module instance, or null if failed
 	 */
 	public function getModule( $moduleName, $group = null, $ignoreCache = false ) {
 		if ( !isset( $this->mModules[$moduleName] ) ) {
 			return null;
 		}
-		$grpCls = $this->mModules[$moduleName];
-		if ( $group !== null && $grpCls[0] !== $group ) {
+
+		list( $moduleGroup, $moduleClass, $moduleFactory ) = $this->mModules[$moduleName];
+
+		if ( $group !== null && $moduleGroup !== $group ) {
 			return null;
 		}
+
 		if ( !$ignoreCache && isset( $this->mInstances[$moduleName] ) ) {
 			// already exists
 			return $this->mInstances[$moduleName];
 		} else {
 			// new instance
-			$class = $grpCls[1];
-			$instance = new $class ( $this->mParent, $moduleName );
+			$instance = $this->instantiateModule( $moduleName, $moduleClass, $moduleFactory );
+
 			if ( !$ignoreCache ) {
 				// cache this instance in case it is needed later
 				$this->mInstances[$moduleName] = $instance;
 			}
+
 			return $instance;
 		}
 	}
 
 	/**
+	 * Instantiate the module using the given class or factory function.
+	 *
+	 * @param string $name The identifier for this module.
+	 * @param string $class The class where this module is implemented.
+	 * @param callable|null $factory Callback for instantiating the module.
+	 *
+	 * @throws MWException
+	 * @return ApiBase
+	 */
+	private function instantiateModule( $name, $class, $factory = null ) {
+		if ( $factory !== null ) {
+			// create instance from factory
+			$instance = call_user_func( $factory, $this->mParent, $name );
+
+			if ( !$instance instanceof $class ) {
+				throw new MWException( "The factory function for module $name did not return an instance of $class!" );
+			}
+		} else {
+			// create instance from class name
+			$instance = new $class( $this->mParent, $name );
+		}
+
+		return $instance;
+	}
+
+	/**
 	 * Get an array of modules in a specific group or all if no group is set.
-	 * @param string $group optional group filter
-	 * @return array list of module names
+	 * @param string $group Optional group filter
+	 * @return array List of module names
 	 */
 	public function getNames( $group = null ) {
 		if ( $group === null ) {
@@ -116,13 +221,14 @@ class ApiModuleManager extends ContextSource {
 				$result[] = $name;
 			}
 		}
+
 		return $result;
 	}
 
 	/**
 	 * Create an array of (moduleName => moduleClass) for a specific group or for all.
-	 * @param string $group name of the group to get or null for all
-	 * @return array name=>class map
+	 * @param string $group Name of the group to get or null for all
+	 * @return array Name=>class map
 	 */
 	public function getNamesWithClasses( $group = null ) {
 		$result = array();
@@ -131,34 +237,50 @@ class ApiModuleManager extends ContextSource {
 				$result[$name] = $grpCls[1];
 			}
 		}
+
 		return $result;
 	}
 
 	/**
+	 * Returns the class name of the given module
+	 *
+	 * @param string $module Module name
+	 * @return string|bool class name or false if the module does not exist
+	 * @since 1.24
+	 */
+	public function getClassName( $module ) {
+		if ( isset( $this->mModules[$module] ) ) {
+			return $this->mModules[$module][1];
+		}
+
+		return false;
+	}
+
+	/**
 	 * Returns true if the specific module is defined at all or in a specific group.
-	 * @param string $moduleName module name
-	 * @param string $group group name to check against, or null to check all groups,
-	 * @return boolean true if defined
+	 * @param string $moduleName Module name
+	 * @param string $group Group name to check against, or null to check all groups,
+	 * @return bool True if defined
 	 */
 	public function isDefined( $moduleName, $group = null ) {
 		if ( isset( $this->mModules[$moduleName] ) ) {
 			return $group === null || $this->mModules[$moduleName][0] === $group;
-		} else {
-			return false;
 		}
+
+		return false;
 	}
 
 	/**
 	 * Returns the group name for the given module
 	 * @param string $moduleName
-	 * @return string group name or null if missing
+	 * @return string Group name or null if missing
 	 */
 	public function getModuleGroup( $moduleName ) {
 		if ( isset( $this->mModules[$moduleName] ) ) {
 			return $this->mModules[$moduleName][0];
-		} else {
-			return null;
 		}
+
+		return null;
 	}
 
 	/**