diff --git a/core/lib/Drupal/Core/Extension/ModuleHandler.php b/core/lib/Drupal/Core/Extension/ModuleHandler.php index d8d36088ac..bf222226c2 100644 --- a/core/lib/Drupal/Core/Extension/ModuleHandler.php +++ b/core/lib/Drupal/Core/Extension/ModuleHandler.php @@ -411,6 +411,45 @@ public function invokeAll($hook, array $args = []) { return $return; } + /** + * {@inheritdoc} + */ + public function invokeDeprecated($description, $module, $hook, array $args = array()) { + $result = $this->invoke($module, $hook, $args); + $this->triggerDeprecationError($description, $hook); + return $result; + } + + /** + * {@inheritdoc} + */ + public function invokeAllDeprecated($description, $hook, array $args = array()) { + $result = $this->invokeAll($hook, $args); + $this->triggerDeprecationError($description, $hook); + return $result; + } + + + /** + * Triggers an E_USER_DEPRECATED error if any module implements the hook. + * + * @param string $description + * Helpful text describing what to do instead of implementing this hook. + * @param string $hook + * The name of the hook. + */ + private function triggerDeprecationError($description, $hook) { + $modules = array_keys($this->getImplementationInfo($hook)); + if (!empty($modules)) { + $message = 'The deprecated hook hook_' . $hook . '() is implemented in these functions: '; + $hooks = []; + foreach ($modules as $module) { + $hooks[] = $module . '_' . $hook . '()'; + } + @trigger_error($message . implode(', ', $hooks) . '. ' . $description, E_USER_DEPRECATED); + } + } + /** * {@inheritdoc} */ @@ -502,6 +541,28 @@ public function alter($type, &$data, &$context1 = NULL, &$context2 = NULL) { } } + /** + * {@inheritdoc} + */ + public function alterDeprecated($description, $type, &$data, &$context1 = NULL, &$context2 = NULL) { + // Invoke the alter hook. This has the side effect of populating + // $this->alterFunctions. + $this->alter($type, $data, $context1, $context2); + // The $type parameter can be an array. alter() will deal with this + // internally, but we have to extract the proper $cid in order to discover + // implementations. + $cid = $type; + if (is_array($type)) { + $cid = implode(',', $type); + $extra_types = $type; + $type = array_shift($extra_types); + } + if (!empty($this->alterFunctions[$cid])) { + $message = 'The deprecated alter hook hook_' . $type . '_alter() is implemented in these functions: ' . implode(', ', $this->alterFunctions[$cid]) . '.'; + @trigger_error($message . ' ' . $description, E_USER_DEPRECATED); + } + } + /** * Provides information about modules' implementations of a hook. * diff --git a/core/lib/Drupal/Core/Extension/ModuleHandlerInterface.php b/core/lib/Drupal/Core/Extension/ModuleHandlerInterface.php index 03d3f66c7b..f1097e3881 100644 --- a/core/lib/Drupal/Core/Extension/ModuleHandlerInterface.php +++ b/core/lib/Drupal/Core/Extension/ModuleHandlerInterface.php @@ -238,6 +238,59 @@ public function invoke($module, $hook, array $args = []); */ public function invokeAll($hook, array $args = []); + /** + * Invokes a deprecated hook in a particular module. + * + * Invoking a deprecated hook adds the behavior of triggering an + * E_USER_DEPRECATED error if any implementations are found. + * + * API maintainers should use this method instead of invoke() when their hook + * is deprecated. This method does not detect when a hook is deprecated. + * + * @param string $description + * Helpful text describing what to do instead of implementing this hook. + * @param string $module + * The name of the module (without the .module extension). + * @param string $hook + * The name of the hook to invoke. + * @param array $args + * Arguments to pass to the hook implementation. + * + * @return mixed + * The return value of the hook implementation. + * + * @see \Drupal\Core\Extension\ModuleHandlerInterface::invoke() + * @see https://www.drupal.org/core/deprecation#how-hook + */ + public function invokeDeprecated($description, $module, $hook, array $args = []); + + /** + * Invokes a deprecated hook in all enabled modules that implement it. + * + * Invoking a deprecated hook adds the behavior of triggering an + * E_USER_DEPRECATED error if any implementations are found. + * + * API maintainers should use this method instead of invokeAll() when their + * hook is deprecated. This method does not detect when a hook is deprecated. + * + * @param string $description + * Helpful text describing what to do instead of implementing this hook. + * @param string $hook + * The name of the hook to invoke. + * @param array $args + * Arguments to pass to the hook. + * + * @return array + * An array of return values of the hook implementations. If modules return + * arrays from their implementations, those are merged into one array + * recursively. Note: integer keys in arrays will be lost, as the merge is + * done using array_merge_recursive(). + * + * @see \Drupal\Core\Extension\ModuleHandlerInterface::invokeAll() + * @see https://www.drupal.org/core/deprecation#how-hook + */ + public function invokeAllDeprecated($description, $hook, array $args = []); + /** * Passes alterable variables to specific hook_TYPE_alter() implementations. * @@ -289,6 +342,42 @@ public function invokeAll($hook, array $args = []); */ public function alter($type, &$data, &$context1 = NULL, &$context2 = NULL); + /** + * Passes alterable variables to deprecated hook_TYPE_alter() implementations. + * + * This method triggers an E_USER_DEPRECATED error if any implementations of + * the alter hook are found. It is otherwise identical to alter(). + * + * See the documentation for alter() for more details. + * + * @param string $description + * Helpful text describing what to do instead of implementing this alter + * hook. + * @param string|array $type + * A string describing the type of the alterable $data. 'form', 'links', + * 'node_content', and so on are several examples. Alternatively can be an + * array, in which case hook_TYPE_alter() is invoked for each value in the + * array, ordered first by module, and then for each module, in the order of + * values in $type. For example, when Form API is using $this->alter() to + * execute both hook_form_alter() and hook_form_FORM_ID_alter() + * implementations, it passes array('form', 'form_' . $form_id) for $type. + * @param mixed $data + * The variable that will be passed to hook_TYPE_alter() implementations to be + * altered. The type of this variable depends on the value of the $type + * argument. For example, when altering a 'form', $data will be a structured + * array. When altering a 'profile', $data will be an object. + * @param mixed $context1 + * (optional) An additional variable that is passed by reference. + * @param mixed $context2 + * (optional) An additional variable that is passed by reference. If more + * context needs to be provided to implementations, then this should be an + * associative array as described above. + * + * @see \Drupal\Core\Extension\ModuleHandlerInterface::alter() + * @see https://www.drupal.org/core/deprecation#how-hook + */ + public function alterDeprecated($description, $type, &$data, &$context1 = NULL, &$context2 = NULL); + /** * Returns an array of directories for all enabled modules. Useful for * tasks such as finding a file that exists in all module directories. diff --git a/core/modules/system/tests/modules/deprecation_test/deprecation_test.module b/core/modules/system/tests/modules/deprecation_test/deprecation_test.module index e255021d65..69217db45e 100644 --- a/core/modules/system/tests/modules/deprecation_test/deprecation_test.module +++ b/core/modules/system/tests/modules/deprecation_test/deprecation_test.module @@ -18,3 +18,17 @@ function deprecation_test_function() { @trigger_error('This is the deprecation message for deprecation_test_function().', E_USER_DEPRECATED); return 'known_return_value'; } + +/** + * Implements hook_deprecated_hook(). + */ +function deprecation_test_deprecated_hook($arg) { + return $arg; +} + +/** + * Implements hook_deprecated_alter_alter(). + */ +function deprecation_test_deprecated_alter_alter(&$data, $context1, $context2) { + $data = [$context1, $context2]; +} diff --git a/core/tests/Drupal/KernelTests/Core/Extension/ModuleHandlerDeprecatedHookTest.php b/core/tests/Drupal/KernelTests/Core/Extension/ModuleHandlerDeprecatedHookTest.php new file mode 100644 index 0000000000..18245634ac --- /dev/null +++ b/core/tests/Drupal/KernelTests/Core/Extension/ModuleHandlerDeprecatedHookTest.php @@ -0,0 +1,61 @@ +container->get('module_handler'); + $arg = 'an_arg'; + $this->assertEqual( + $arg, + $module_handler->invokeDeprecated('Use something else.', 'deprecation_test', 'deprecated_hook', [$arg]) + ); + } + + /** + * @covers ::invokeAllDeprecated + * @expectedDeprecation The deprecated hook hook_deprecated_hook() is implemented in these functions: deprecation_test_deprecated_hook(). Use something else. + */ + public function testInvokeAllDeprecated() { + /* @var $module_handler \Drupal\Core\Extension\ModuleHandlerInterface */ + $module_handler = $this->container->get('module_handler'); + $arg = 'an_arg'; + $this->assertEqual( + [$arg], + $module_handler->invokeAllDeprecated('Use something else.', 'deprecated_hook', [$arg]) + ); + } + + /** + * @covers ::alterDeprecated + * @expectedDeprecation The deprecated alter hook hook_deprecated_alter_alter() is implemented in these functions: deprecation_test_deprecated_alter_alter. Alter something else. + */ + public function testAlterDeprecated() { + /* @var $module_handler \Drupal\Core\Extension\ModuleHandlerInterface */ + $module_handler = $this->container->get('module_handler'); + $data = []; + $context1 = 'test1'; + $context2 = 'test2'; + $module_handler->alterDeprecated('Alter something else.', 'deprecated_alter', $data, $context1, $context2); + $this->assertEqual([$context1, $context2], $data); + } + +} diff --git a/core/tests/Drupal/KernelTests/Core/Extension/ModuleHandlerDeprecatedHookUnimplementedTest.php b/core/tests/Drupal/KernelTests/Core/Extension/ModuleHandlerDeprecatedHookUnimplementedTest.php new file mode 100644 index 0000000000..1d4e833e82 --- /dev/null +++ b/core/tests/Drupal/KernelTests/Core/Extension/ModuleHandlerDeprecatedHookUnimplementedTest.php @@ -0,0 +1,33 @@ +container->get('module_handler'); + + $module_handler->invokeDeprecated('Use something else.', 'deprecation_test', $unimplemented_hook_name); + $module_handler->invokeAllDeprecated('Use something else.', $unimplemented_hook_name); + $data = []; + $module_handler->alterDeprecated('Alter something else.', $unimplemented_hook_name, $data); + } + +}