aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/Extension/ModuleHandlerInterface.php

   1 <?php
   2
   3 namespace Drupal\Core\Extension;
   4
   5 /**
   6  * Interface for classes that manage a set of enabled modules.
   7  *
   8  * Classes implementing this interface work with a fixed list of modules and are
   9  * responsible for loading module files and maintaining information about module
  10  * dependencies and hook implementations.
  11  */
  12 interface ModuleHandlerInterface {
  13
  14   /**
  15    * Includes a module's .module file.
  16    *
  17    * This prevents including a module more than once.
  18    *
  19    * @param string $name
  20    *   The name of the module to load.
  21    *
  22    * @return bool
  23    *   TRUE if the item is loaded or has already been loaded.
  24    */
  25   public function load($name);
  26
  27   /**
  28    * Loads all enabled modules.
  29    */
  30   public function loadAll();
  31
  32   /**
  33    * Returns whether all modules have been loaded.
  34    *
  35    * @return bool
  36    *   A Boolean indicating whether all modules have been loaded. This means all
  37    *   modules; the load status of bootstrap modules cannot be checked.
  38    */
  39   public function isLoaded();
  40
  41   /**
  42    * Reloads all enabled modules.
  43    */
  44   public function reload();
  45
  46   /**
  47    * Returns the list of currently active modules.
  48    *
  49    * @return \Drupal\Core\Extension\Extension[]
  50    *   An associative array whose keys are the names of the modules and whose
  51    *   values are Extension objects.
  52    */
  53   public function getModuleList();
  54
  55   /**
  56    * Returns a module extension object from the currently active modules list.
  57    *
  58    * @param string $name
  59    *   The name of the module to return.
  60    *
  61    * @return \Drupal\Core\Extension\Extension
  62    *   An extension object.
  63    *
  64    * @throws \Drupal\Core\Extension\Exception\UnknownExtensionException
  65    *   Thrown when the requested module does not exist.
  66    */
  67   public function getModule($name);
  68
  69   /**
  70    * Sets an explicit list of currently active modules.
  71    *
  72    * @param \Drupal\Core\Extension\Extension[] $module_list
  73    *   An associative array whose keys are the names of the modules and whose
  74    *   values are Extension objects.
  75    */
  76   public function setModuleList(array $module_list = []);
  77
  78   /**
  79    * Adds a module to the list of currently active modules.
  80    *
  81    * @param string $name
  82    *   The module name; e.g., 'node'.
  83    * @param string $path
  84    *   The module path; e.g., 'core/modules/node'.
  85    */
  86   public function addModule($name, $path);
  87
  88   /**
  89    * Adds an installation profile to the list of currently active modules.
  90    *
  91    * @param string $name
  92    *   The profile name; e.g., 'standard'.
  93    * @param string $path
  94    *   The profile path; e.g., 'core/profiles/standard'.
  95    */
  96   public function addProfile($name, $path);
  97
  98   /**
  99    * Determines which modules require and are required by each module.
 100    *
 101    * @param array $modules
 102    *   An array of module objects keyed by module name. Each object contains
 103    *   information discovered during a Drupal\Core\Extension\ExtensionDiscovery
 104    *   scan.
 105    *
 106    * @return
 107    *   The same array with the new keys for each module:
 108    *   - requires: An array with the keys being the modules that this module
 109    *     requires.
 110    *   - required_by: An array with the keys being the modules that will not work
 111    *     without this module.
 112    *
 113    * @see \Drupal\Core\Extension\ExtensionDiscovery
 114    */
 115   public function buildModuleDependencies(array $modules);
 116
 117   /**
 118    * Determines whether a given module is enabled.
 119    *
 120    * @param string $module
 121    *   The name of the module (without the .module extension).
 122    *
 123    * @return bool
 124    *   TRUE if the module is both installed and enabled.
 125    */
 126   public function moduleExists($module);
 127
 128   /**
 129    * Loads an include file for each enabled module.
 130    *
 131    * @param string $type
 132    *   The include file's type (file extension).
 133    * @param string $name
 134    *   (optional) The base file name (without the $type extension). If omitted,
 135    *   each module's name is used; i.e., "$module.$type" by default.
 136    */
 137   public function loadAllIncludes($type, $name = NULL);
 138
 139   /**
 140    * Loads a module include file.
 141    *
 142    * Examples:
 143    * @code
 144    *   // Load node.admin.inc from the node module.
 145    *   $this->loadInclude('node', 'inc', 'node.admin');
 146    *   // Load content_types.inc from the node module.
 147    *   $this->loadInclude('node', 'inc', 'content_types');
 148    * @endcode
 149    *
 150    * @param string $module
 151    *   The module to which the include file belongs.
 152    * @param string $type
 153    *   The include file's type (file extension).
 154    * @param string $name
 155    *   (optional) The base file name (without the $type extension). If omitted,
 156    *   $module is used; i.e., resulting in "$module.$type" by default.
 157    *
 158    * @return string|false
 159    *   The name of the included file, if successful; FALSE otherwise.
 160    */
 161   public function loadInclude($module, $type, $name = NULL);
 162
 163   /**
 164    * Retrieves a list of hooks that are declared through hook_hook_info().
 165    *
 166    * @return array
 167    *   An associative array whose keys are hook names and whose values are an
 168    *   associative array containing a group name. The structure of the array
 169    *   is the same as the return value of hook_hook_info().
 170    *
 171    * @see hook_hook_info()
 172    */
 173   public function getHookInfo();
 174
 175   /**
 176    * Determines which modules are implementing a hook.
 177    *
 178    * @param string $hook
 179    *   The name of the hook (e.g. "help" or "menu").
 180    *
 181    * @return array
 182    *   An array with the names of the modules which are implementing this hook.
 183    */
 184   public function getImplementations($hook);
 185
 186   /**
 187    * Write the hook implementation info to the cache.
 188    */
 189   public function writeCache();
 190
 191   /**
 192    * Resets the cached list of hook implementations.
 193    */
 194   public function resetImplementations();
 195
 196   /**
 197    * Returns whether a given module implements a given hook.
 198    *
 199    * @param string $module
 200    *   The name of the module (without the .module extension).
 201    * @param string $hook
 202    *   The name of the hook (e.g. "help" or "menu").
 203    *
 204    * @return bool
 205    *   TRUE if the module is both installed and enabled, and the hook is
 206    *   implemented in that module.
 207    */
 208   public function implementsHook($module, $hook);
 209
 210   /**
 211    * Invokes a hook in a particular module.
 212    *
 213    * @param string $module
 214    *   The name of the module (without the .module extension).
 215    * @param string $hook
 216    *   The name of the hook to invoke.
 217    * @param array $args
 218    *   Arguments to pass to the hook implementation.
 219    *
 220    * @return mixed
 221    *   The return value of the hook implementation.
 222    */
 223   public function invoke($module, $hook, array $args = []);
 224
 225   /**
 226    * Invokes a hook in all enabled modules that implement it.
 227    *
 228    * @param string $hook
 229    *   The name of the hook to invoke.
 230    * @param array $args
 231    *   Arguments to pass to the hook.
 232    *
 233    * @return array
 234    *   An array of return values of the hook implementations. If modules return
 235    *   arrays from their implementations, those are merged into one array
 236    *   recursively. Note: integer keys in arrays will be lost, as the merge is
 237    *   done using array_merge_recursive().
 238    */
 239   public function invokeAll($hook, array $args = []);
 240
 241   /**
 242    * Invokes a deprecated hook in a particular module.
 243    *
 244    * Invoking a deprecated hook adds the behavior of triggering an
 245    * E_USER_DEPRECATED error if any implementations are found.
 246    *
 247    * API maintainers should use this method instead of invoke() when their hook
 248    * is deprecated. This method does not detect when a hook is deprecated.
 249    *
 250    * @param string $description
 251    *   Helpful text describing what to do instead of implementing this hook.
 252    * @param string $module
 253    *   The name of the module (without the .module extension).
 254    * @param string $hook
 255    *   The name of the hook to invoke.
 256    * @param array $args
 257    *   Arguments to pass to the hook implementation.
 258    *
 259    * @return mixed
 260    *   The return value of the hook implementation.
 261    *
 262    * @see \Drupal\Core\Extension\ModuleHandlerInterface::invoke()
 263    * @see https://www.drupal.org/core/deprecation#how-hook
 264    */
 265   public function invokeDeprecated($description, $module, $hook, array $args = []);
 266
 267   /**
 268    * Invokes a deprecated hook in all enabled modules that implement it.
 269    *
 270    * Invoking a deprecated hook adds the behavior of triggering an
 271    * E_USER_DEPRECATED error if any implementations are found.
 272    *
 273    * API maintainers should use this method instead of invokeAll() when their
 274    * hook is deprecated. This method does not detect when a hook is deprecated.
 275    *
 276    * @param string $description
 277    *   Helpful text describing what to do instead of implementing this hook.
 278    * @param string $hook
 279    *   The name of the hook to invoke.
 280    * @param array $args
 281    *   Arguments to pass to the hook.
 282    *
 283    * @return array
 284    *   An array of return values of the hook implementations. If modules return
 285    *   arrays from their implementations, those are merged into one array
 286    *   recursively. Note: integer keys in arrays will be lost, as the merge is
 287    *   done using array_merge_recursive().
 288    *
 289    * @see \Drupal\Core\Extension\ModuleHandlerInterface::invokeAll()
 290    * @see https://www.drupal.org/core/deprecation#how-hook
 291    */
 292   public function invokeAllDeprecated($description, $hook, array $args = []);
 293
 294   /**
 295    * Passes alterable variables to specific hook_TYPE_alter() implementations.
 296    *
 297    * This dispatch function hands off the passed-in variables to type-specific
 298    * hook_TYPE_alter() implementations in modules. It ensures a consistent
 299    * interface for all altering operations.
 300    *
 301    * A maximum of 2 alterable arguments is supported. In case more arguments need
 302    * to be passed and alterable, modules provide additional variables assigned by
 303    * reference in the last $context argument:
 304    * @code
 305    *   $context = array(
 306    *     'alterable' => &$alterable,
 307    *     'unalterable' => $unalterable,
 308    *     'foo' => 'bar',
 309    *   );
 310    *   $this->alter('mymodule_data', $alterable1, $alterable2, $context);
 311    * @endcode
 312    *
 313    * Note that objects are always passed by reference in PHP5. If it is absolutely
 314    * required that no implementation alters a passed object in $context, then an
 315    * object needs to be cloned:
 316    * @code
 317    *   $context = array(
 318    *     'unalterable_object' => clone $object,
 319    *   );
 320    *   $this->alter('mymodule_data', $data, $context);
 321    * @endcode
 322    *
 323    * @param string|array $type
 324    *   A string describing the type of the alterable $data. 'form', 'links',
 325    *   'node_content', and so on are several examples. Alternatively can be an
 326    *   array, in which case hook_TYPE_alter() is invoked for each value in the
 327    *   array, ordered first by module, and then for each module, in the order of
 328    *   values in $type. For example, when Form API is using $this->alter() to
 329    *   execute both hook_form_alter() and hook_form_FORM_ID_alter()
 330    *   implementations, it passes array('form', 'form_' . $form_id) for $type.
 331    * @param mixed $data
 332    *   The variable that will be passed to hook_TYPE_alter() implementations to be
 333    *   altered. The type of this variable depends on the value of the $type
 334    *   argument. For example, when altering a 'form', $data will be a structured
 335    *   array. When altering a 'profile', $data will be an object.
 336    * @param mixed $context1
 337    *   (optional) An additional variable that is passed by reference.
 338    * @param mixed $context2
 339    *   (optional) An additional variable that is passed by reference. If more
 340    *   context needs to be provided to implementations, then this should be an
 341    *   associative array as described above.
 342    */
 343   public function alter($type, &$data, &$context1 = NULL, &$context2 = NULL);
 344
 345   /**
 346    * Passes alterable variables to deprecated hook_TYPE_alter() implementations.
 347    *
 348    * This method triggers an E_USER_DEPRECATED error if any implementations of
 349    * the alter hook are found. It is otherwise identical to alter().
 350    *
 351    * See the documentation for alter() for more details.
 352    *
 353    * @param string $description
 354    *   Helpful text describing what to do instead of implementing this alter
 355    *   hook.
 356    * @param string|array $type
 357    *   A string describing the type of the alterable $data. 'form', 'links',
 358    *   'node_content', and so on are several examples. Alternatively can be an
 359    *   array, in which case hook_TYPE_alter() is invoked for each value in the
 360    *   array, ordered first by module, and then for each module, in the order of
 361    *   values in $type. For example, when Form API is using $this->alter() to
 362    *   execute both hook_form_alter() and hook_form_FORM_ID_alter()
 363    *   implementations, it passes array('form', 'form_' . $form_id) for $type.
 364    * @param mixed $data
 365    *   The variable that will be passed to hook_TYPE_alter() implementations to be
 366    *   altered. The type of this variable depends on the value of the $type
 367    *   argument. For example, when altering a 'form', $data will be a structured
 368    *   array. When altering a 'profile', $data will be an object.
 369    * @param mixed $context1
 370    *   (optional) An additional variable that is passed by reference.
 371    * @param mixed $context2
 372    *   (optional) An additional variable that is passed by reference. If more
 373    *   context needs to be provided to implementations, then this should be an
 374    *   associative array as described above.
 375    *
 376    * @see \Drupal\Core\Extension\ModuleHandlerInterface::alter()
 377    * @see https://www.drupal.org/core/deprecation#how-hook
 378    */
 379   public function alterDeprecated($description, $type, &$data, &$context1 = NULL, &$context2 = NULL);
 380
 381   /**
 382    * Returns an array of directories for all enabled modules. Useful for
 383    * tasks such as finding a file that exists in all module directories.
 384    *
 385    * @return array
 386    */
 387   public function getModuleDirectories();
 388
 389   /**
 390    * Gets the human readable name of a given module.
 391    *
 392    * @param string $module
 393    *   The machine name of the module which title should be shown.
 394    *
 395    * @return string
 396    *   Returns the human readable name of the module or the machine name passed
 397    *   in if no matching module is found.
 398    */
 399   public function getName($module);
 400
 401 }