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                         return $instance;
 101                 }
 102         }
 103
 104         /**
 105          * Get an array of modules in a specific group or all if no group is set.
 106          * @param string $group optional group filter
 107          * @return array list of module names
 108          */
 109         public function getNames( $group = null ) {
 110                 if ( $group === null ) {
 111                         return array_keys( $this->mModules );
 112                 }
 113                 $result = array();
 114                 foreach ( $this->mModules as $name => $grpCls ) {
 115                         if ( $grpCls[0] === $group ) {
 116                                 $result[] = $name;
 117                         }
 118                 }
 119                 return $result;
 120         }
 121
 122         /**
 123          * Create an array of (moduleName => moduleClass) for a specific group or for all.
 124          * @param string $group name of the group to get or null for all
 125          * @return array name=>class map
 126          */
 127         public function getNamesWithClasses( $group = null ) {
 128                 $result = array();
 129                 foreach ( $this->mModules as $name => $grpCls ) {
 130                         if ( $group === null || $grpCls[0] === $group ) {
 131                                 $result[$name] = $grpCls[1];
 132                         }
 133                 }
 134                 return $result;
 135         }
 136
 137         /**
 138          * Returns true if the specific module is defined at all or in a specific group.
 139          * @param string $moduleName module name
 140          * @param string $group group name to check against, or null to check all groups,
 141          * @return boolean true if defined
 142          */
 143         public function isDefined( $moduleName, $group = null ) {
 144                 if ( isset( $this->mModules[$moduleName] ) ) {
 145                         return $group === null || $this->mModules[$moduleName][0] === $group;
 146                 } else {
 147                         return false;
 148                 }
 149         }
 150
 151         /**
 152          * Returns the group name for the given module
 153          * @param string $moduleName
 154          * @return string group name or null if missing
 155          */
 156         public function getModuleGroup( $moduleName ) {
 157                 if ( isset( $this->mModules[$moduleName] ) ) {
 158                         return $this->mModules[$moduleName][0];
 159                 } else {
 160                         return null;
 161                 }
 162         }
 163
 164         /**
 165          * Get a list of groups this manager contains.
 166          * @return array
 167          */
 168         public function getGroups() {
 169                 return array_keys( $this->mGroups );
 170         }
 171 }