Using WordPress ‘apply_filters_deprecated()’ PHP function

by

The apply_filters_deprecated() WordPress PHP function is used when a filter hook is deprecated. It triggers a deprecation notice and then fires the original filter hook. The value and extra arguments that were initially passed to the original apply_filters() call should be passed here to $args as an array.

Usage

Here’s a simple usage example:

return apply_filters_deprecated(
  'wpdocs_filter',
  array( $value, $extra_arg ),
  '4.9.0',
  'wpdocs_new_filter'
);

In this example, 'wpdocs_filter' is the old, deprecated filter, and 'wpdocs_new_filter' is the suggested replacement. '4.9.0' is the version of WordPress that deprecated the old filter.

Parameters

  • $hook_name (string) Required. The name of the deprecated filter hook.
  • $args (array) Required. Array of additional function arguments to be passed to apply_filters().
  • $version (string) Required. 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: apply_filters_deprecated()

This function was implemented in WordPress 4.9.0. You can find the source code in wp-includes/plugin.php.

Examples

Deprecating a Simple Filter

This example shows how to deprecate a simple filter named ‘wpdocs_filter’. The filter is replaced by ‘wpdocs_new_filter’.

$value = 'Hello, World!';
$extra_arg = 'Goodbye, World!';

return apply_filters_deprecated(
  'wpdocs_filter',
  array( $value, $extra_arg ),
  '4.9.0',
  'wpdocs_new_filter'
);

No Replacement Filter

In this example, there is no replacement for the deprecated filter. Only a deprecation message is given.

return apply_filters_deprecated(
  'wpdocs_old_filter',
  array( $some_value, $some_arg ),
  '5.0.0',
  '',
  'wpdocs_old_filter is deprecated without replacement.'
);

Different Version Deprecation

The following code deprecates a filter in a different WordPress version (5.3.0).

return apply_filters_deprecated(
  'wpdocs_another_filter',
  array( $different_value, $different_arg ),
  '5.3.0',
  'wpdocs_yet_another_filter'
);

Adding a Custom Deprecation Message

In this example, a custom deprecation message is added when deprecating a filter.

return apply_filters_deprecated(
  'wpdocs_deprecated_filter',
  array( $value ),
  '5.5.0',
  'wpdocs_replacement_filter',
  'We have replaced wpdocs_deprecated_filter with wpdocs_replacement_filter for better performance.'
);

Deprecating a Filter with Multiple Arguments

Here, a filter with multiple arguments is deprecated.

return apply_filters_deprecated(
  'wpdocs_complex_filter',
  array( $value1, $value2, $value3 ),
  '5.7.0',
  'wpdocs_simple_filter'
);