includes/api/ApiModuleManager.php

   1 <?php
   2 /**
   3  *
   4  *
   5  * Created on Dec 27, 2012
   6  *
   7  * Copyright © 2012 Yuri Astrakhan "<Firstname><Lastname>@gmail.com"
   8  *
   9  * This program is free software; you can redistribute it and/or modify
  10  * it under the terms of the GNU General Public License as published by
  11  * the Free Software Foundation; either version 2 of the License, or
  12  * (at your option) any later version.
  13  *
  14  * This program is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  17  * GNU General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU General Public License along
  20  * with this program; if not, write to the Free Software Foundation, Inc.,
  21  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  22  * http://www.gnu.org/copyleft/gpl.html
  23  *
  24  * @file
  25  * @since 1.21
  26  */
  27
  28 /**
  29  * This class holds a list of modules and handles instantiation
  30  *
  31  * @since 1.21
  32  * @ingroup API
  33  */
  34 class ApiModuleManager extends ContextSource {
  35
  36         /**
  37          * @var ApiBase
  38          */
  39         private $mParent;
  40         /**
  41          * @var ApiBase[]
  42          */
  43         private $mInstances = array();
  44         /**
  45          * @var null[]
  46          */
  47         private $mGroups = array();
  48         /**
  49          * @var array[]
  50          */
  51         private $mModules = array();
  52
  53         /**
  54          * Construct new module manager
  55          * @param ApiBase $parentModule Parent module instance will be used during instantiation
  56          */
  57         public function __construct( ApiBase $parentModule ) {
  58                 $this->mParent = $parentModule;
  59         }
  60
  61         /**
  62          * Add a list of modules to the manager
  63          * @param array $modules A map of ModuleName => ModuleClass
  64          * @param string $group Which group modules belong to (action,format,...)
  65          */
  66         public function addModules( array $modules, $group ) {
  67                 foreach ( $modules as $name => $class ) {
  68                         $this->addModule( $name, $group, $class );
  69                 }
  70         }
  71
  72         /**
  73          * Add or overwrite a module in this ApiMain instance. Intended for use by extending
  74          * classes who wish to add their own modules to their lexicon or override the
  75          * behavior of inherent ones.
  76          *
  77          * @param string $group Name of the module group
  78          * @param string $name The identifier for this module.
  79          * @param string $class The class where this module is implemented.
  80          */
  81         public function addModule( $name, $group, $class ) {
  82                 $this->mGroups[$group] = null;
  83                 $this->mModules[$name] = array( $group, $class );
  84         }
  85
  86         /**
  87          * Get module instance by name, or instantiate it if it does not exist
  88          * @param string $moduleName Module name
  89          * @param string $group Optionally validate that the module is in a specific group
  90          * @param bool $ignoreCache If true, force-creates a new instance and does not cache it
  91          * @return mixed The new module instance, or null if failed
  92          */
  93         public function getModule( $moduleName, $group = null, $ignoreCache = false ) {
  94                 if ( !isset( $this->mModules[$moduleName] ) ) {
  95                         return null;
  96                 }
  97                 $grpCls = $this->mModules[$moduleName];
  98                 if ( $group !== null && $grpCls[0] !== $group ) {
  99                         return null;
 100                 }
 101                 if ( !$ignoreCache && isset( $this->mInstances[$moduleName] ) ) {
 102                         // already exists
 103                         return $this->mInstances[$moduleName];
 104                 } else {
 105                         // new instance
 106                         $class = $grpCls[1];
 107                         $instance = new $class ( $this->mParent, $moduleName );
 108                         if ( !$ignoreCache ) {
 109                                 // cache this instance in case it is needed later
 110                                 $this->mInstances[$moduleName] = $instance;
 111                         }
 112
 113                         return $instance;
 114                 }
 115         }
 116
 117         /**
 118          * Get an array of modules in a specific group or all if no group is set.
 119          * @param string $group Optional group filter
 120          * @return array List of module names
 121          */
 122         public function getNames( $group = null ) {
 123                 if ( $group === null ) {
 124                         return array_keys( $this->mModules );
 125                 }
 126                 $result = array();
 127                 foreach ( $this->mModules as $name => $grpCls ) {
 128                         if ( $grpCls[0] === $group ) {
 129                                 $result[] = $name;
 130                         }
 131                 }
 132
 133                 return $result;
 134         }
 135
 136         /**
 137          * Create an array of (moduleName => moduleClass) for a specific group or for all.
 138          * @param string $group Name of the group to get or null for all
 139          * @return array Name=>class map
 140          */
 141         public function getNamesWithClasses( $group = null ) {
 142                 $result = array();
 143                 foreach ( $this->mModules as $name => $grpCls ) {
 144                         if ( $group === null || $grpCls[0] === $group ) {
 145                                 $result[$name] = $grpCls[1];
 146                         }
 147                 }
 148
 149                 return $result;
 150         }
 151
 152         /**
 153          * Returns true if the specific module is defined at all or in a specific group.
 154          * @param string $moduleName Module name
 155          * @param string $group Group name to check against, or null to check all groups,
 156          * @return bool True if defined
 157          */
 158         public function isDefined( $moduleName, $group = null ) {
 159                 if ( isset( $this->mModules[$moduleName] ) ) {
 160                         return $group === null || $this->mModules[$moduleName][0] === $group;
 161                 }
 162
 163                 return false;
 164         }
 165
 166         /**
 167          * Returns the group name for the given module
 168          * @param string $moduleName
 169          * @return string Group name or null if missing
 170          */
 171         public function getModuleGroup( $moduleName ) {
 172                 if ( isset( $this->mModules[$moduleName] ) ) {
 173                         return $this->mModules[$moduleName][0];
 174                 }
 175
 176                 return null;
 177         }
 178
 179         /**
 180          * Get a list of groups this manager contains.
 181          * @return array
 182          */
 183         public function getGroups() {
 184                 return array_keys( $this->mGroups );
 185         }
 186 }