3 namespace Drupal\Core\Extension;
6 * Interface for classes that manage a set of enabled modules.
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.
12 interface ModuleHandlerInterface {
15 * Includes a module's .module file.
17 * This prevents including a module more than once.
20 * The name of the module to load.
23 * TRUE if the item is loaded or has already been loaded.
25 public function load($name);
28 * Loads all enabled modules.
30 public function loadAll();
33 * Returns whether all modules have been loaded.
36 * A Boolean indicating whether all modules have been loaded. This means all
37 * modules; the load status of bootstrap modules cannot be checked.
39 public function isLoaded();
42 * Reloads all enabled modules.
44 public function reload();
47 * Returns the list of currently active modules.
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.
53 public function getModuleList();
56 * Returns a module extension object from the currently active modules list.
59 * The name of the module to return.
61 * @return \Drupal\Core\Extension\Extension
62 * An extension object.
64 * @throws \InvalidArgumentException
65 * Thrown when the requested module does not exist.
67 public function getModule($name);
70 * Sets an explicit list of currently active modules.
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.
76 public function setModuleList(array $module_list = []);
79 * Adds a module to the list of currently active modules.
82 * The module name; e.g., 'node'.
84 * The module path; e.g., 'core/modules/node'.
86 public function addModule($name, $path);
89 * Adds an installation profile to the list of currently active modules.
92 * The profile name; e.g., 'standard'.
94 * The profile path; e.g., 'core/profiles/standard'.
96 public function addProfile($name, $path);
99 * Determines which modules require and are required by each module.
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
107 * The same array with the new keys for each module:
108 * - requires: An array with the keys being the modules that this module
110 * - required_by: An array with the keys being the modules that will not work
111 * without this module.
113 * @see \Drupal\Core\Extension\ExtensionDiscovery
115 public function buildModuleDependencies(array $modules);
118 * Determines whether a given module is enabled.
120 * @param string $module
121 * The name of the module (without the .module extension).
124 * TRUE if the module is both installed and enabled.
126 public function moduleExists($module);
129 * Loads an include file for each enabled module.
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.
137 public function loadAllIncludes($type, $name = NULL);
140 * Loads a module include file.
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');
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.
158 * @return string|false
159 * The name of the included file, if successful; FALSE otherwise.
161 public function loadInclude($module, $type, $name = NULL);
164 * Retrieves a list of hooks that are declared through hook_hook_info().
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().
171 * @see hook_hook_info()
173 public function getHookInfo();
176 * Determines which modules are implementing a hook.
178 * @param string $hook
179 * The name of the hook (e.g. "help" or "menu").
182 * An array with the names of the modules which are implementing this hook.
184 public function getImplementations($hook);
187 * Write the hook implementation info to the cache.
189 public function writeCache();
192 * Resets the cached list of hook implementations.
194 public function resetImplementations();
197 * Returns whether a given module implements a given hook.
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").
205 * TRUE if the module is both installed and enabled, and the hook is
206 * implemented in that module.
208 public function implementsHook($module, $hook);
211 * Invokes a hook in a particular module.
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.
218 * Arguments to pass to the hook implementation.
221 * The return value of the hook implementation.
223 public function invoke($module, $hook, array $args = []);
226 * Invokes a hook in all enabled modules that implement it.
228 * @param string $hook
229 * The name of the hook to invoke.
231 * Arguments to pass to the hook.
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().
239 public function invokeAll($hook, array $args = []);
242 * Passes alterable variables to specific hook_TYPE_alter() implementations.
244 * This dispatch function hands off the passed-in variables to type-specific
245 * hook_TYPE_alter() implementations in modules. It ensures a consistent
246 * interface for all altering operations.
248 * A maximum of 2 alterable arguments is supported. In case more arguments need
249 * to be passed and alterable, modules provide additional variables assigned by
250 * reference in the last $context argument:
253 * 'alterable' => &$alterable,
254 * 'unalterable' => $unalterable,
257 * $this->alter('mymodule_data', $alterable1, $alterable2, $context);
260 * Note that objects are always passed by reference in PHP5. If it is absolutely
261 * required that no implementation alters a passed object in $context, then an
262 * object needs to be cloned:
265 * 'unalterable_object' => clone $object,
267 * $this->alter('mymodule_data', $data, $context);
270 * @param string|array $type
271 * A string describing the type of the alterable $data. 'form', 'links',
272 * 'node_content', and so on are several examples. Alternatively can be an
273 * array, in which case hook_TYPE_alter() is invoked for each value in the
274 * array, ordered first by module, and then for each module, in the order of
275 * values in $type. For example, when Form API is using $this->alter() to
276 * execute both hook_form_alter() and hook_form_FORM_ID_alter()
277 * implementations, it passes array('form', 'form_' . $form_id) for $type.
279 * The variable that will be passed to hook_TYPE_alter() implementations to be
280 * altered. The type of this variable depends on the value of the $type
281 * argument. For example, when altering a 'form', $data will be a structured
282 * array. When altering a 'profile', $data will be an object.
283 * @param mixed $context1
284 * (optional) An additional variable that is passed by reference.
285 * @param mixed $context2
286 * (optional) An additional variable that is passed by reference. If more
287 * context needs to be provided to implementations, then this should be an
288 * associative array as described above.
290 public function alter($type, &$data, &$context1 = NULL, &$context2 = NULL);
293 * Returns an array of directories for all enabled modules. Useful for
294 * tasks such as finding a file that exists in all module directories.
298 public function getModuleDirectories();
301 * Gets the human readable name of a given module.
303 * @param string $module
304 * The machine name of the module which title should be shown.
307 * Returns the human readable name of the module or the machine name passed
308 * in if no matching module is found.
310 public function getName($module);