annotate core/lib/Drupal/Core/Extension/ModuleHandlerInterface.php @ 19:fa3358dc1485 tip

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