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         private $mParent;
  37         private $mInstances = array();
  38         private $mGroups = array();
  39         private $mModules = array();
  40
  41         /**
  42          * Construct new module manager
  43          * @param ApiBase $parentModule Parent module instance will be used during instantiation
  44          */
  45         public function __construct( ApiBase $parentModule ) {
  46                 $this->mParent = $parentModule;
  47         }
  48
  49         /**
  50          * Add a list of modules to the manager
  51          * @param array $modules A map of ModuleName => ModuleClass
  52          * @param string $group Which group modules belong to (action,format,...)
  53          */
  54         public function addModules( array $modules, $group ) {
  55                 foreach ( $modules as $name => $class ) {
  56                         $this->addModule( $name, $group, $class );
  57                 }
  58         }
  59
  60         /**
  61          * Add or overwrite a module in this ApiMain instance. Intended for use by extending
  62          * classes who wish to add their own modules to their lexicon or override the
  63          * behavior of inherent ones.
  64          *
  65          * @param string $group Name of the module group
  66          * @param string $name The identifier for this module.
  67          * @param string $class The class where this module is implemented.
  68          */
  69         public function addModule( $name, $group, $class ) {
  70                 $this->mGroups[$group] = null;
  71                 $this->mModules[$name] = array( $group, $class );
  72         }
  73
  74         /**
  75          * Get module instance by name, or instantiate it if it does not exist
  76          * @param string $moduleName module name
  77          * @param string $group optionally validate that the module is in a specific group
  78          * @param bool $ignoreCache if true, force-creates a new instance and does not cache it
  79          * @return mixed the new module instance, or null if failed
  80          */
  81         public function getModule( $moduleName, $group = null, $ignoreCache = false ) {
  82                 if ( !isset( $this->mModules[$moduleName] ) ) {
  83                         return null;
  84                 }
  85                 $grpCls = $this->mModules[$moduleName];
  86                 if ( $group !== null && $grpCls[0] !== $group ) {
  87                         return null;
  88                 }
  89                 if ( !$ignoreCache && isset( $this->mInstances[$moduleName] ) ) {
  90                         // already exists
  91                         return $this->mInstances[$moduleName];
  92                 } else {
  93                         // new instance
  94                         $class = $grpCls[1];
  95                         $instance = new $class ( $this->mParent, $moduleName );
  96                         if ( !$ignoreCache ) {
  97                                 // cache this instance in case it is needed later
  98                                 $this->mInstances[$moduleName] = $instance;
  99                         }
 100
 101                         return $instance;
 102                 }
 103         }
 104
 105         /**
 106          * Get an array of modules in a specific group or all if no group is set.
 107          * @param string $group optional group filter
 108          * @return array list of module names
 109          */
 110         public function getNames( $group = null ) {
 111                 if ( $group === null ) {
 112                         return array_keys( $this->mModules );
 113                 }
 114                 $result = array();
 115                 foreach ( $this->mModules as $name => $grpCls ) {
 116                         if ( $grpCls[0] === $group ) {
 117                                 $result[] = $name;
 118                         }
 119                 }
 120
 121                 return $result;
 122         }
 123
 124         /**
 125          * Create an array of (moduleName => moduleClass) for a specific group or for all.
 126          * @param string $group name of the group to get or null for all
 127          * @return array name=>class map
 128          */
 129         public function getNamesWithClasses( $group = null ) {
 130                 $result = array();
 131                 foreach ( $this->mModules as $name => $grpCls ) {
 132                         if ( $group === null || $grpCls[0] === $group ) {
 133                                 $result[$name] = $grpCls[1];
 134                         }
 135                 }
 136
 137                 return $result;
 138         }
 139
 140         /**
 141          * Returns true if the specific module is defined at all or in a specific group.
 142          * @param string $moduleName module name
 143          * @param string $group group name to check against, or null to check all groups,
 144          * @return boolean true if defined
 145          */
 146         public function isDefined( $moduleName, $group = null ) {
 147                 if ( isset( $this->mModules[$moduleName] ) ) {
 148                         return $group === null || $this->mModules[$moduleName][0] === $group;
 149                 }
 150
 151                 return false;
 152         }
 153
 154         /**
 155          * Returns the group name for the given module
 156          * @param string $moduleName
 157          * @return string group name or null if missing
 158          */
 159         public function getModuleGroup( $moduleName ) {
 160                 if ( isset( $this->mModules[$moduleName] ) ) {
 161                         return $this->mModules[$moduleName][0];
 162                 }
 163
 164                 return null;
 165         }
 166
 167         /**
 168          * Get a list of groups this manager contains.
 169          * @return array
 170          */
 171         public function getGroups() {
 172                 return array_keys( $this->mGroups );
 173         }
 174 }