Commit 5485720e authored by catch's avatar catch

Issue #2866779 by Mile23, dawehner: Add a way to trigger_error() for deprecated hooks

parent c5fba612
......@@ -411,6 +411,44 @@ 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: ';
$implementations = array_map(function ($module) use ($hook) {
return $module . '_' . $hook . '()';
}, $modules);
@trigger_error($message . implode(', ', $implementations) . '. ' . $description, E_USER_DEPRECATED);
}
}
/**
* {@inheritdoc}
*/
......@@ -502,6 +540,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.
*
......
......@@ -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.
......
......@@ -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];
}
<?php
namespace Drupal\KernelTests\Core\Extension;
use Drupal\KernelTests\KernelTestBase;
/**
* Test whether deprecated hook invocations trigger errors.
*
* @group Extension
* @group legacy
*
* @coversDefaultClass Drupal\Core\Extension\ModuleHandler
*/
class ModuleHandlerDeprecatedHookTest extends KernelTestBase {
protected static $modules = ['deprecation_test'];
/**
* @covers ::invokeDeprecated
* @expectedDeprecation The deprecated hook hook_deprecated_hook() is implemented in these functions: deprecation_test_deprecated_hook(). Use something else.
*/
public function testInvokeDeprecated() {
/* @var $module_handler \Drupal\Core\Extension\ModuleHandlerInterface */
$module_handler = $this->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);
}
}
<?php
namespace Drupal\KernelTests\Core\Extension;
use Drupal\KernelTests\KernelTestBase;
/**
* Test whether unimplemented deprecated hook invocations trigger errors.
*
* @group Extension
*
* @coversDefaultClass Drupal\Core\Extension\ModuleHandler
*/
class ModuleHandlerDeprecatedHookUnimplementedTest extends KernelTestBase {
/**
* @covers ::alterDeprecated
* @covers ::invokeAllDeprecated
* @covers ::invokeDeprecated
*/
public function testUnimplementedHooks() {
$unimplemented_hook_name = 'unimplemented_hook_name';
/* @var $module_handler \Drupal\Core\Extension\ModuleHandlerInterface */
$module_handler = $this->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);
}
}
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment