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 }
|