includes/api/ApiModuleManager.php

   1 <?php
   2 /**
   3  * Copyright © 2012 Yuri Astrakhan "<Firstname><Lastname>@gmail.com"
   4  *
   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.
   9  *
  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.
  14  *
  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
  19  *
  20  * @file
  21  * @since 1.21
  22  */
  23
  24 use MediaWiki\MediaWikiServices;
  25 use Wikimedia\ObjectFactory;
  26
  27 /**
  28  * This class holds a list of modules and handles instantiation
  29  *
  30  * @since 1.21
  31  * @ingroup API
  32  */
  33 class ApiModuleManager extends ContextSource {
  34
  35         /**
  36          * @var ApiBase
  37          */
  38         private $mParent;
  39         /**
  40          * @var ApiBase[]
  41          */
  42         private $mInstances = [];
  43         /**
  44          * @var null[]
  45          */
  46         private $mGroups = [];
  47         /**
  48          * @var array[]
  49          */
  50         private $mModules = [];
  51         /**
  52          * @var ObjectFactory
  53          */
  54         private $objectFactory;
  55
  56         /**
  57          * Construct new module manager
  58          *
  59          * @param ApiBase $parentModule Parent module instance will be used during instantiation
  60          * @param ObjectFactory|null $objectFactory Object factory to use when instantiating modules
  61          */
  62         public function __construct( ApiBase $parentModule, ObjectFactory $objectFactory = null ) {
  63                 $this->mParent = $parentModule;
  64                 $this->objectFactory = $objectFactory ?? MediaWikiServices::getInstance()->getObjectFactory();
  65         }
  66
  67         /**
  68          * Add a list of modules to the manager. Each module is described
  69          * by an ObjectFactory spec.
  70          *
  71          * This simply calls `addModule()` for each module in `$modules`.
  72          *
  73          * @see ApiModuleManager::addModule()
  74          * @param array $modules A map of ModuleName => ModuleSpec
  75          * @param string $group Which group modules belong to (action,format,...)
  76          */
  77         public function addModules( array $modules, $group ) {
  78                 foreach ( $modules as $name => $moduleSpec ) {
  79                         $this->addModule( $name, $group, $moduleSpec );
  80                 }
  81         }
  82
  83         /**
  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.
  87          *
  88          * ObjectFactory is used to instantiate the module when needed. The parent module
  89          * (`$parentModule` from `__construct()`) and the `$name` are passed as extraArgs.
  90          *
  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
  93          *  deprecated.
  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).
  99          *
 100          * @throws InvalidArgumentException
 101          */
 102         public function addModule( $name, $group, $spec, $factory = null ) {
 103                 if ( !is_string( $name ) ) {
 104                         throw new InvalidArgumentException( '$name must be a string' );
 105                 }
 106
 107                 if ( !is_string( $group ) ) {
 108                         throw new InvalidArgumentException( '$group must be a string' );
 109                 }
 110
 111                 if ( is_string( $spec ) ) {
 112                         $spec = [
 113                                 'class' => $spec
 114                         ];
 115
 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;
 120                         }
 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' );
 125                 }
 126
 127                 $this->mGroups[$group] = null;
 128                 $this->mModules[$name] = [ $group, $spec ];
 129         }
 130
 131         /**
 132          * Get module instance by name, or instantiate it if it does not exist
 133          *
 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
 137          *
 138          * @return ApiBase|null The new module instance, or null if failed
 139          */
 140         public function getModule( $moduleName, $group = null, $ignoreCache = false ) {
 141                 if ( !isset( $this->mModules[$moduleName] ) ) {
 142                         return null;
 143                 }
 144
 145                 list( $moduleGroup, $spec ) = $this->mModules[$moduleName];
 146
 147                 if ( $group !== null && $moduleGroup !== $group ) {
 148                         return null;
 149                 }
 150
 151                 if ( !$ignoreCache && isset( $this->mInstances[$moduleName] ) ) {
 152                         // already exists
 153                         return $this->mInstances[$moduleName];
 154                 } else {
 155                         // new instance
 156                         $instance = $this->instantiateModule( $moduleName, $spec );
 157
 158                         if ( !$ignoreCache ) {
 159                                 // cache this instance in case it is needed later
 160                                 $this->mInstances[$moduleName] = $instance;
 161                         }
 162
 163                         return $instance;
 164                 }
 165         }
 166
 167         /**
 168          * Instantiate the module using the given class or factory function.
 169          *
 170          * @param string $name The identifier for this module.
 171          * @param array $spec The ObjectFactory spec for instantiating the module.
 172          *
 173          * @throws UnexpectedValueException
 174          * @return ApiBase
 175          */
 176         private function instantiateModule( $name, $spec ) {
 177                 return $this->objectFactory->createObject(
 178                         $spec,
 179                         [
 180                                 'extraArgs' => [
 181                                         $this->mParent,
 182                                         $name
 183                                 ],
 184                                 'assertClass' => $spec['class']
 185                         ]
 186                 );
 187         }
 188
 189         /**
 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
 193          */
 194         public function getNames( $group = null ) {
 195                 if ( $group === null ) {
 196                         return array_keys( $this->mModules );
 197                 }
 198                 $result = [];
 199                 foreach ( $this->mModules as $name => $groupAndSpec ) {
 200                         if ( $groupAndSpec[0] === $group ) {
 201                                 $result[] = $name;
 202                         }
 203                 }
 204
 205                 return $result;
 206         }
 207
 208         /**
 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
 212          */
 213         public function getNamesWithClasses( $group = null ) {
 214                 $result = [];
 215                 foreach ( $this->mModules as $name => $groupAndSpec ) {
 216                         if ( $group === null || $groupAndSpec[0] === $group ) {
 217                                 $result[$name] = $groupAndSpec[1]['class'];
 218                         }
 219                 }
 220
 221                 return $result;
 222         }
 223
 224         /**
 225          * Returns the class name of the given module
 226          *
 227          * @param string $module Module name
 228          * @return string|bool class name or false if the module does not exist
 229          * @since 1.24
 230          */
 231         public function getClassName( $module ) {
 232                 if ( isset( $this->mModules[$module] ) ) {
 233                         return $this->mModules[$module][1]['class'];
 234                 }
 235
 236                 return false;
 237         }
 238
 239         /**
 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
 244          */
 245         public function isDefined( $moduleName, $group = null ) {
 246                 if ( isset( $this->mModules[$moduleName] ) ) {
 247                         return $group === null || $this->mModules[$moduleName][0] === $group;
 248                 }
 249
 250                 return false;
 251         }
 252
 253         /**
 254          * Returns the group name for the given module
 255          * @param string $moduleName
 256          * @return string|null Group name or null if missing
 257          */
 258         public function getModuleGroup( $moduleName ) {
 259                 if ( isset( $this->mModules[$moduleName] ) ) {
 260                         return $this->mModules[$moduleName][0];
 261                 }
 262
 263                 return null;
 264         }
 265
 266         /**
 267          * Get a list of groups this manager contains.
 268          * @return array
 269          */
 270         public function getGroups() {
 271                 return array_keys( $this->mGroups );
 272         }
 273 }