_deprecated_argument

Mark a function argument as deprecated and inform when it has been used.

Description

_deprecated_argument( (string) $function, (string) $version, (null) $message = null ); 

This function is to be used whenever a deprecated function argument is used. Before this function is called, the argument must be checked for whether it was used by comparing it to its default value or evaluating whether it is empty. For example:

_deprecated_argument( __FUNCTION__, 3.0.0 );

There is a hook deprecated_argument_run that will be called that can be used to get the backtrace up to what file and function used the deprecated argument.

The current behavior is to trigger a user error if WP_DEBUG is true.

Parameters (3)

0. $function (string)
The function that was called.
1. $version (string)
The version of WordPress that deprecated the argument used.
2. $message — Optional. (null) => null
A message regarding the change. Default null.

Usage

  1. if ( !function_exists( '_deprecated_argument' ) ) { 
  2. require_once ABSPATH . WPINC . '/functions.php'; 
  3.  
  4. // The function that was called. 
  5. $function = ''; 
  6.  
  7. // The version of WordPress that deprecated the argument used. 
  8. $version = ''; 
  9.  
  10. // Optional. A message regarding the change. Default null. 
  11. $message = null; 
  12.  
  13. // NOTICE! Understand what this does before running. 
  14. $result = _deprecated_argument($function, $version, $message); 
  15.  

Defined (1)

The function is defined in the following location(s).

/wp-includes/functions.php  
  1. function _deprecated_argument( $function, $version, $message = null ) { 
  2.  
  3. /** 
  4. * Fires when a deprecated argument is called. 
  5. * @since 3.0.0 
  6. * @param string $function The function that was called. 
  7. * @param string $message A message regarding the change. 
  8. * @param string $version The version of WordPress that deprecated the argument used. 
  9. */ 
  10. do_action( 'deprecated_argument_run', $function, $message, $version ); 
  11.  
  12. /** 
  13. * Filters whether to trigger anerrorfor deprecated arguments. 
  14. * @since 3.0.0 
  15. * @param bool $trigger Whether to trigger theerrorfor deprecated arguments. Default true. 
  16. */ 
  17. if ( function_exists( '__' ) ) { 
  18. if ( ! is_null( $message ) ) { 
  19. /** translators: 1: PHP function name, 2: version number, 3: optional message regarding the change */ 
  20. trigger_error( sprintf( __('%1$s was called with an argument that is <strong>deprecated</strong> since version %2$s! %3$s'), $function, $version, $message ) ); 
  21. } else { 
  22. /** translators: 1: PHP function name, 2: version number */ 
  23. trigger_error( sprintf( __('%1$s was called with an argument that is <strong>deprecated</strong> since version %2$s with no alternative available.'), $function, $version ) ); 
  24. } else { 
  25. if ( ! is_null( $message ) ) { 
  26. trigger_error( sprintf( '%1$s was called with an argument that is <strong>deprecated</strong> since version %2$s! %3$s', $function, $version, $message ) ); 
  27. } else { 
  28. trigger_error( sprintf( '%1$s was called with an argument that is <strong>deprecated</strong> since version %2$s with no alternative available.', $function, $version ) );