X-Git-Url: http://git.heureux-cyclage.org/?a=blobdiff_plain;f=includes%2Fapi%2FApiModuleManager.php;h=8d5a82b92eab501d32b421277186d6a4d25d1d08;hb=825d66bfa44c5dae2b78e2fe4f3b16f16aff4a12;hp=fec55aa6cdf18b25896dfe19ae40797d9298f619;hpb=7793c8acc6d21c451cd5737fd6b98b1a7d9a5e00;p=lhc%2Fweb%2Fwiklou.git diff --git a/includes/api/ApiModuleManager.php b/includes/api/ApiModuleManager.php index fec55aa6cd..8d5a82b92e 100644 --- a/includes/api/ApiModuleManager.php +++ b/includes/api/ApiModuleManager.php @@ -21,6 +21,9 @@ * @since 1.21 */ +use MediaWiki\MediaWikiServices; +use Wikimedia\ObjectFactory; + /** * This class holds a list of modules and handles instantiation * @@ -45,64 +48,35 @@ class ApiModuleManager extends ContextSource { * @var array[] */ private $mModules = []; + /** + * @var ObjectFactory + */ + private $objectFactory; /** * Construct new module manager + * * @param ApiBase $parentModule Parent module instance will be used during instantiation + * @param ObjectFactory|null $objectFactory Object factory to use when instantiating modules */ - public function __construct( ApiBase $parentModule ) { + public function __construct( ApiBase $parentModule, ObjectFactory $objectFactory = null ) { $this->mParent = $parentModule; + $this->objectFactory = $objectFactory ?? MediaWikiServices::getInstance()->getObjectFactory(); } /** * 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. + * by an ObjectFactory spec. * - * 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. + * This simply calls `addModule()` for each module in `$modules`. * - * 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'] = [ - * 'class' => ApiBar::class, - * 'factory' => function( $main, $name ) { ... } - * ]; - * $modules['xyzzy'] = [ - * 'class' => ApiXyzzy::class, - * 'factory' => [ XyzzyFactory::class, '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). + * @see ApiModuleManager::addModule() + * @param array $modules A map of ModuleName => ModuleSpec * @param string $group Which group modules belong to (action,format,...) */ public function addModules( array $modules, $group ) { foreach ( $modules as $name => $moduleSpec ) { - if ( is_array( $moduleSpec ) ) { - $class = $moduleSpec['class']; - $factory = ( $moduleSpec['factory'] ?? null ); - } else { - $class = $moduleSpec; - $factory = null; - } - - $this->addModule( $name, $group, $class, $factory ); + $this->addModule( $name, $group, $moduleSpec ); } } @@ -111,14 +85,21 @@ class ApiModuleManager extends ContextSource { * classes who wish to add their own modules to their lexicon or override the * behavior of inherent ones. * + * ObjectFactory is used to instantiate the module when needed. The parent module + * (`$parentModule` from `__construct()`) and the `$name` are passed as extraArgs. + * + * @since 1.34, accepts an ObjectFactory spec as the third parameter. The old calling convention, + * passing a class name as parameter #3 and an optional factory callable as parameter #4, is + * deprecated. * @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. + * @param string|array $spec The ObjectFactory spec for instantiating the module, + * or a class name to instantiate. + * @param callable|null $factory Callback for instantiating the module (deprecated). * * @throws InvalidArgumentException */ - public function addModule( $name, $group, $class, $factory = null ) { + public function addModule( $name, $group, $spec, $factory = null ) { if ( !is_string( $name ) ) { throw new InvalidArgumentException( '$name must be a string' ); } @@ -127,23 +108,30 @@ class ApiModuleManager extends ContextSource { throw new InvalidArgumentException( '$group must be a string' ); } - if ( !is_string( $class ) ) { - throw new InvalidArgumentException( '$class must be a string' ); - } + if ( is_string( $spec ) ) { + $spec = [ + 'class' => $spec + ]; - if ( $factory !== null && !is_callable( $factory ) ) { - throw new InvalidArgumentException( '$factory must be a callable (or null)' ); + if ( is_callable( $factory ) ) { + wfDeprecated( __METHOD__ . ' with $class and $factory', '1.34' ); + $spec['factory'] = $factory; + } + } elseif ( !is_array( $spec ) ) { + throw new InvalidArgumentException( '$spec must be a string or an array' ); + } elseif ( !isset( $spec['class'] ) ) { + throw new InvalidArgumentException( '$spec must define a class name' ); } $this->mGroups[$group] = null; - $this->mModules[$name] = [ $group, $class, $factory ]; + $this->mModules[$name] = [ $group, $spec ]; } /** * 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 string|null $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 @@ -153,7 +141,7 @@ class ApiModuleManager extends ContextSource { return null; } - list( $moduleGroup, $moduleClass, $moduleFactory ) = $this->mModules[$moduleName]; + list( $moduleGroup, $spec ) = $this->mModules[$moduleName]; if ( $group !== null && $moduleGroup !== $group ) { return null; @@ -164,7 +152,7 @@ class ApiModuleManager extends ContextSource { return $this->mInstances[$moduleName]; } else { // new instance - $instance = $this->instantiateModule( $moduleName, $moduleClass, $moduleFactory ); + $instance = $this->instantiateModule( $moduleName, $spec ); if ( !$ignoreCache ) { // cache this instance in case it is needed later @@ -179,33 +167,27 @@ class ApiModuleManager extends ContextSource { * 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. + * @param array $spec The ObjectFactory spec for instantiating the module. * - * @throws MWException + * @throws UnexpectedValueException * @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; + private function instantiateModule( $name, $spec ) { + return $this->objectFactory->createObject( + $spec, + [ + 'extraArgs' => [ + $this->mParent, + $name + ], + 'assertClass' => $spec['class'] + ] + ); } /** * Get an array of modules in a specific group or all if no group is set. - * @param string $group Optional group filter + * @param string|null $group Optional group filter * @return array List of module names */ public function getNames( $group = null ) { @@ -213,8 +195,8 @@ class ApiModuleManager extends ContextSource { return array_keys( $this->mModules ); } $result = []; - foreach ( $this->mModules as $name => $grpCls ) { - if ( $grpCls[0] === $group ) { + foreach ( $this->mModules as $name => $groupAndSpec ) { + if ( $groupAndSpec[0] === $group ) { $result[] = $name; } } @@ -224,14 +206,14 @@ class ApiModuleManager extends ContextSource { /** * 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 + * @param string|null $group Name of the group to get or null for all * @return array Name=>class map */ public function getNamesWithClasses( $group = null ) { $result = []; - foreach ( $this->mModules as $name => $grpCls ) { - if ( $group === null || $grpCls[0] === $group ) { - $result[$name] = $grpCls[1]; + foreach ( $this->mModules as $name => $groupAndSpec ) { + if ( $group === null || $groupAndSpec[0] === $group ) { + $result[$name] = $groupAndSpec[1]['class']; } } @@ -247,7 +229,7 @@ class ApiModuleManager extends ContextSource { */ public function getClassName( $module ) { if ( isset( $this->mModules[$module] ) ) { - return $this->mModules[$module][1]; + return $this->mModules[$module][1]['class']; } return false; @@ -256,7 +238,7 @@ class ApiModuleManager extends ContextSource { /** * 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, + * @param string|null $group Group name to check against, or null to check all groups, * @return bool True if defined */ public function isDefined( $moduleName, $group = null ) {