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 wfDeprecated( __METHOD__
. ' with $class and $factory', '1.34' );
118 $spec['factory'] = $factory;
120 } elseif ( !is_array( $spec ) ) {
121 throw new InvalidArgumentException( '$spec must be a string or an array' );
122 } elseif ( !isset( $spec['class'] ) ) {
123 throw new InvalidArgumentException( '$spec must define a class name' );
126 $this->mGroups
[$group] = null;
127 $this->mModules
[$name] = [ $group, $spec ];
131 * Get module instance by name, or instantiate it if it does not exist
133 * @param string $moduleName Module name
134 * @param string|null $group Optionally validate that the module is in a specific group
135 * @param bool $ignoreCache If true, force-creates a new instance and does not cache it
137 * @return ApiBase|null The new module instance, or null if failed
139 public function getModule( $moduleName, $group = null, $ignoreCache = false ) {
140 if ( !isset( $this->mModules
[$moduleName] ) ) {
144 list( $moduleGroup, $spec ) = $this->mModules
[$moduleName];
146 if ( $group !== null && $moduleGroup !== $group ) {
150 if ( !$ignoreCache && isset( $this->mInstances
[$moduleName] ) ) {
152 return $this->mInstances
[$moduleName];
155 $instance = $this->instantiateModule( $moduleName, $spec );
157 if ( !$ignoreCache ) {
158 // cache this instance in case it is needed later
159 $this->mInstances
[$moduleName] = $instance;
167 * Instantiate the module using the given class or factory function.
169 * @param string $name The identifier for this module.
170 * @param array $spec The ObjectFactory spec for instantiating the module.
172 * @throws UnexpectedValueException
175 private function instantiateModule( $name, $spec ) {
176 return $this->objectFactory
->createObject(
183 'assertClass' => $spec['class']
189 * Get an array of modules in a specific group or all if no group is set.
190 * @param string|null $group Optional group filter
191 * @return array List of module names
193 public function getNames( $group = null ) {
194 if ( $group === null ) {
195 return array_keys( $this->mModules
);
198 foreach ( $this->mModules
as $name => $groupAndSpec ) {
199 if ( $groupAndSpec[0] === $group ) {
208 * Create an array of (moduleName => moduleClass) for a specific group or for all.
209 * @param string|null $group Name of the group to get or null for all
210 * @return array Name=>class map
212 public function getNamesWithClasses( $group = null ) {
214 foreach ( $this->mModules
as $name => $groupAndSpec ) {
215 if ( $group === null ||
$groupAndSpec[0] === $group ) {
216 $result[$name] = $groupAndSpec[1]['class'];
224 * Returns the class name of the given module
226 * @param string $module Module name
227 * @return string|bool class name or false if the module does not exist
230 public function getClassName( $module ) {
231 if ( isset( $this->mModules
[$module] ) ) {
232 return $this->mModules
[$module][1]['class'];
239 * Returns true if the specific module is defined at all or in a specific group.
240 * @param string $moduleName Module name
241 * @param string|null $group Group name to check against, or null to check all groups,
242 * @return bool True if defined
244 public function isDefined( $moduleName, $group = null ) {
245 if ( isset( $this->mModules
[$moduleName] ) ) {
246 return $group === null ||
$this->mModules
[$moduleName][0] === $group;
253 * Returns the group name for the given module
254 * @param string $moduleName
255 * @return string|null Group name or null if missing
257 public function getModuleGroup( $moduleName ) {
258 if ( isset( $this->mModules
[$moduleName] ) ) {
259 return $this->mModules
[$moduleName][0];
266 * Get a list of groups this manager contains.
269 public function getGroups() {
270 return array_keys( $this->mGroups
);