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                                 wfDeprecated( __METHOD__ . ' with $class and $factory', '1.34' );
 118                                 $spec['factory'] = $factory;
 119                         }
 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' );
 124                 }
 125
 126                 $this->mGroups[$group] = null;
 127                 $this->mModules[$name] = [ $group, $spec ];
 128         }
 129
 130         /**
 131          * Get module instance by name, or instantiate it if it does not exist
 132          *
 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
 136          *
 137          * @return ApiBase|null The new module instance, or null if failed
 138          */
 139         public function getModule( $moduleName, $group = null, $ignoreCache = false ) {
 140                 if ( !isset( $this->mModules[$moduleName] ) ) {
 141                         return null;
 142                 }
 143
 144                 list( $moduleGroup, $spec ) = $this->mModules[$moduleName];
 145
 146                 if ( $group !== null && $moduleGroup !== $group ) {
 147                         return null;
 148                 }
 149
 150                 if ( !$ignoreCache && isset( $this->mInstances[$moduleName] ) ) {
 151                         // already exists
 152                         return $this->mInstances[$moduleName];
 153                 } else {
 154                         // new instance
 155                         $instance = $this->instantiateModule( $moduleName, $spec );
 156
 157                         if ( !$ignoreCache ) {
 158                                 // cache this instance in case it is needed later
 159                                 $this->mInstances[$moduleName] = $instance;
 160                         }
 161
 162                         return $instance;
 163                 }
 164         }
 165
 166         /**
 167          * Instantiate the module using the given class or factory function.
 168          *
 169          * @param string $name The identifier for this module.
 170          * @param array $spec The ObjectFactory spec for instantiating the module.
 171          *
 172          * @throws UnexpectedValueException
 173          * @return ApiBase
 174          */
 175         private function instantiateModule( $name, $spec ) {
 176                 return $this->objectFactory->createObject(
 177                         $spec,
 178                         [
 179                                 'extraArgs' => [
 180                                         $this->mParent,
 181                                         $name
 182                                 ],
 183                                 'assertClass' => $spec['class']
 184                         ]
 185                 );
 186         }
 187
 188         /**
 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
 192          */
 193         public function getNames( $group = null ) {
 194                 if ( $group === null ) {
 195                         return array_keys( $this->mModules );
 196                 }
 197                 $result = [];
 198                 foreach ( $this->mModules as $name => $groupAndSpec ) {
 199                         if ( $groupAndSpec[0] === $group ) {
 200                                 $result[] = $name;
 201                         }
 202                 }
 203
 204                 return $result;
 205         }
 206
 207         /**
 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
 211          */
 212         public function getNamesWithClasses( $group = null ) {
 213                 $result = [];
 214                 foreach ( $this->mModules as $name => $groupAndSpec ) {
 215                         if ( $group === null || $groupAndSpec[0] === $group ) {
 216                                 $result[$name] = $groupAndSpec[1]['class'];
 217                         }
 218                 }
 219
 220                 return $result;
 221         }
 222
 223         /**
 224          * Returns the class name of the given module
 225          *
 226          * @param string $module Module name
 227          * @return string|bool class name or false if the module does not exist
 228          * @since 1.24
 229          */
 230         public function getClassName( $module ) {
 231                 if ( isset( $this->mModules[$module] ) ) {
 232                         return $this->mModules[$module][1]['class'];
 233                 }
 234
 235                 return false;
 236         }
 237
 238         /**
 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
 243          */
 244         public function isDefined( $moduleName, $group = null ) {
 245                 if ( isset( $this->mModules[$moduleName] ) ) {
 246                         return $group === null || $this->mModules[$moduleName][0] === $group;
 247                 }
 248
 249                 return false;
 250         }
 251
 252         /**
 253          * Returns the group name for the given module
 254          * @param string $moduleName
 255          * @return string|null Group name or null if missing
 256          */
 257         public function getModuleGroup( $moduleName ) {
 258                 if ( isset( $this->mModules[$moduleName] ) ) {
 259                         return $this->mModules[$moduleName][0];
 260                 }
 261
 262                 return null;
 263         }
 264
 265         /**
 266          * Get a list of groups this manager contains.
 267          * @return array
 268          */
 269         public function getGroups() {
 270                 return array_keys( $this->mGroups );
 271         }
 272 }