diff options
author | Pierre Schmitz <pierre@archlinux.de> | 2014-12-27 15:41:37 +0100 |
---|---|---|
committer | Pierre Schmitz <pierre@archlinux.de> | 2014-12-31 11:43:28 +0100 |
commit | c1f9b1f7b1b77776192048005dcc66dcf3df2bfb (patch) | |
tree | 2b38796e738dd74cb42ecd9bfd151803108386bc /includes/api/ApiModuleManager.php | |
parent | b88ab0086858470dd1f644e64cb4e4f62bb2be9b (diff) |
Update to MediaWiki 1.24.1
Diffstat (limited to 'includes/api/ApiModuleManager.php')
-rw-r--r-- | includes/api/ApiModuleManager.php | 176 |
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; } /** |