The do_action_deprecated() WordPress PHP function is used when an action hook is deprecated. It triggers a deprecation notice and then fires the original hook.
Usage
To use do_action_deprecated(), pass the required parameters as shown in the following example:
do_action_deprecated('old_hook_name', array('param1', 'param2'), '4.9.0', 'new_hook_name', 'This hook is deprecated because...');
Parameters
- $hook_name (string): The name of the action hook.
- $args (array): Array of additional function arguments to be passed to do_action().
- $version (string): The version of WordPress that deprecated the hook.
- $replacement (string – Optional): The hook that should have been used. Default: ”.
- $message (string – Optional): A message regarding the change. Default: ”.
More Information
See WordPress Developer Resources: do_action_deprecated()
This function was introduced in WordPress 4.6.0. It’s not recommended to use deprecated functions as they may be removed in future WordPress releases.
Examples
Firing a Deprecated Hook
This example fires a deprecated action hook named ‘old_hook_name’.
do_action_deprecated('old_hook_name', array('param1', 'param2'), '4.9.0');
This will trigger a notice that ‘old_hook_name’ is deprecated since version 4.9.0 with no alternative available.
Firing a Deprecated Hook with a Replacement
This example shows how to fire a deprecated hook and suggest a new hook as a replacement.
do_action_deprecated('old_hook_name', array('param1', 'param2'), '4.9.0', 'new_hook_name');
This will trigger a notice that ‘old_hook_name’ is deprecated since version 4.9.0 and that ‘new_hook_name’ should be used instead.
Firing a Deprecated Hook with a Replacement and Message
This example shows how to fire a deprecated hook, suggest a new hook as a replacement, and provide a message about the change.
do_action_deprecated('old_hook_name', array('param1', 'param2'), '4.9.0', 'new_hook_name', 'We have replaced old_hook_name with new_hook_name for improved performance.');
This will trigger a notice that ‘old_hook_name’ is deprecated since version 4.9.0, ‘new_hook_name’ should be used instead, and include the custom message about the change.
Firing a Deprecated Hook with Multiple Parameters
This example shows how to fire a deprecated hook with multiple parameters.
do_action_deprecated('old_hook_name', array('param1', 'param2', 'param3'), '4.9.0');
This will trigger a notice that ‘old_hook_name’ is deprecated since version 4.9.0 with no alternative available, and will pass the parameters ‘param1’, ‘param2’, and ‘param3’ to any functions hooked into ‘old_hook_name’.
Firing a Deprecated Hook with No Parameters
This example shows how to fire a deprecated hook with no additional parameters.
do_action_deprecated('old_hook_name', array(), '4.9.0');
This will trigger a notice that ‘old_hook_name’ is deprecated since version 4.9.0 with no alternative available.