3 * Copyright © 2012 Yuri Astrakhan "<Firstname><Lastname>@gmail.com"
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or
8 * (at your option) any later version.
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
15 * You should have received a copy of the GNU General Public License along
16 * with this program; if not, write to the Free Software Foundation, Inc.,
17 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 * http://www.gnu.org/copyleft/gpl.html
24 use MediaWiki\MediaWikiServices
;
25 use Wikimedia\ObjectFactory
;
28 * This class holds a list of modules and handles instantiation
33 class ApiModuleManager
extends ContextSource
{
42 private $mInstances = [];
46 private $mGroups = [];
50 private $mModules = [];
54 private $objectFactory;
57 * Construct new module manager
59 * @param ApiBase $parentModule Parent module instance will be used during instantiation
60 * @param ObjectFactory|null $objectFactory Object factory to use when instantiating modules
62 public function __construct( ApiBase
$parentModule, ObjectFactory
$objectFactory = null ) {
63 $this->mParent
= $parentModule;
64 $this->objectFactory
= $objectFactory ?? MediaWikiServices
::getInstance()->getObjectFactory();
68 * Add a list of modules to the manager. Each module is described
69 * by an ObjectFactory spec.
71 * This simply calls `addModule()` for each module in `$modules`.
73 * @see ApiModuleManager::addModule()
74 * @param array $modules A map of ModuleName => ModuleSpec
75 * @param string $group Which group modules belong to (action,format,...)
77 public function addModules( array $modules, $group ) {
78 foreach ( $modules as $name => $moduleSpec ) {
79 $this->addModule( $name, $group, $moduleSpec );
84 * Add or overwrite a module in this ApiMain instance. Intended for use by extending
85 * classes who wish to add their own modules to their lexicon or override the
86 * behavior of inherent ones.
88 * ObjectFactory is used to instantiate the module when needed. The parent module
89 * (`$parentModule` from `__construct()`) and the `$name` are passed as extraArgs.
91 * @since 1.34, accepts an ObjectFactory spec as the third parameter. The old calling convention,
92 * passing a class name as parameter #3 and an optional factory callable as parameter #4, is
94 * @param string $name The identifier for this module.
95 * @param string $group Name of the module group
96 * @param string|array $spec The ObjectFactory spec for instantiating the module,
97 * or a class name to instantiate.
98 * @param callable|null $factory Callback for instantiating the module (deprecated).
100 * @throws InvalidArgumentException
102 public function addModule( $name, $group, $spec, $factory = null ) {
103 if ( !is_string( $name ) ) {
104 throw new InvalidArgumentException( '$name must be a string' );
107 if ( !is_string( $group ) ) {
108 throw new InvalidArgumentException( '$group must be a string' );
111 if ( is_string( $spec ) ) {
116 if ( is_callable( $factory ) ) {
117 // Uncomment this when callers are cleaned up:
118 // wfDeprecated( __METHOD__ . ' with $class and $factory', '1.34' );
119 $spec['factory'] = $factory;
121 } elseif ( !is_array( $spec ) ) {
122 throw new InvalidArgumentException( '$spec must be a string or an array' );
123 } elseif ( !isset( $spec['class'] ) ) {
124 throw new InvalidArgumentException( '$spec must define a class name' );
127 $this->mGroups
[$group] = null;
128 $this->mModules
[$name] = [ $group, $spec ];
132 * Get module instance by name, or instantiate it if it does not exist
134 * @param string $moduleName Module name
135 * @param string|null $group Optionally validate that the module is in a specific group
136 * @param bool $ignoreCache If true, force-creates a new instance and does not cache it
138 * @return ApiBase|null The new module instance, or null if failed
140 public function getModule( $moduleName, $group = null, $ignoreCache = false ) {
141 if ( !isset( $this->mModules
[$moduleName] ) ) {
145 list( $moduleGroup, $spec ) = $this->mModules
[$moduleName];
147 if ( $group !== null && $moduleGroup !== $group ) {
151 if ( !$ignoreCache && isset( $this->mInstances
[$moduleName] ) ) {
153 return $this->mInstances
[$moduleName];
156 $instance = $this->instantiateModule( $moduleName, $spec );
158 if ( !$ignoreCache ) {
159 // cache this instance in case it is needed later
160 $this->mInstances
[$moduleName] = $instance;
168 * Instantiate the module using the given class or factory function.
170 * @param string $name The identifier for this module.
171 * @param array $spec The ObjectFactory spec for instantiating the module.
173 * @throws UnexpectedValueException
176 private function instantiateModule( $name, $spec ) {
177 return $this->objectFactory
->createObject(
184 'assertClass' => $spec['class']
190 * Get an array of modules in a specific group or all if no group is set.
191 * @param string|null $group Optional group filter
192 * @return array List of module names
194 public function getNames( $group = null ) {
195 if ( $group === null ) {
196 return array_keys( $this->mModules
);
199 foreach ( $this->mModules
as $name => $groupAndSpec ) {
200 if ( $groupAndSpec[0] === $group ) {
209 * Create an array of (moduleName => moduleClass) for a specific group or for all.
210 * @param string|null $group Name of the group to get or null for all
211 * @return array Name=>class map
213 public function getNamesWithClasses( $group = null ) {
215 foreach ( $this->mModules
as $name => $groupAndSpec ) {
216 if ( $group === null ||
$groupAndSpec[0] === $group ) {
217 $result[$name] = $groupAndSpec[1]['class'];
225 * Returns the class name of the given module
227 * @param string $module Module name
228 * @return string|bool class name or false if the module does not exist
231 public function getClassName( $module ) {
232 if ( isset( $this->mModules
[$module] ) ) {
233 return $this->mModules
[$module][1]['class'];
240 * Returns true if the specific module is defined at all or in a specific group.
241 * @param string $moduleName Module name
242 * @param string|null $group Group name to check against, or null to check all groups,
243 * @return bool True if defined
245 public function isDefined( $moduleName, $group = null ) {
246 if ( isset( $this->mModules
[$moduleName] ) ) {
247 return $group === null ||
$this->mModules
[$moduleName][0] === $group;
254 * Returns the group name for the given module
255 * @param string $moduleName
256 * @return string|null Group name or null if missing
258 public function getModuleGroup( $moduleName ) {
259 if ( isset( $this->mModules
[$moduleName] ) ) {
260 return $this->mModules
[$moduleName][0];
267 * Get a list of groups this manager contains.
270 public function getGroups() {
271 return array_keys( $this->mGroups
);