_deprecated_file

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

Description

_deprecated_file( (string) $file, (string) $version, (constant) $replacement = null, (string) $message = '' ); 

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

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

This function is to be used in every file that is deprecated.

Parameters (4)

0. $file (string)
The file that was included.
1. $version (string)
The version of WordPress that deprecated the file.
2. $replacement — Optional. (constant) => null
The file that should have been included based on ABSPATH. Default null.
3. $message — Optional. (string) => ''
A message regarding the change. Default empty.

Usage

  1. if ( !function_exists( '_deprecated_file' ) ) { 
  2. require_once ABSPATH . WPINC . '/functions.php'; 
  3.  
  4. // The file that was included. 
  5. $file = ''; 
  6.  
  7. // The version of WordPress that deprecated the file. 
  8. $version = ''; 
  9.  
  10. // Optional. The file that should have been included based on ABSPATH. 
  11. // Default null. 
  12. $replacement = null; 
  13.  
  14. // Optional. A message regarding the change. Default empty. 
  15. $message = ''; 
  16.  
  17. // NOTICE! Understand what this does before running. 
  18. $result = _deprecated_file($file, $version, $replacement, $message); 
  19.  

Defined (1)

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

/wp-includes/functions.php  
  1. function _deprecated_file( $file, $version, $replacement = null, $message = '' ) { 
  2.  
  3. /** 
  4. * Fires when a deprecated file is called. 
  5. * @since 2.5.0 
  6. * @param string $file The file that was called. 
  7. * @param string $replacement The file that should have been included based on ABSPATH
  8. * @param string $version The version of WordPress that deprecated the file. 
  9. * @param string $message A message regarding the change. 
  10. */ 
  11. do_action( 'deprecated_file_included', $file, $replacement, $version, $message ); 
  12.  
  13. /** 
  14. * Filters whether to trigger anerrorfor deprecated files. 
  15. * @since 2.5.0 
  16. * @param bool $trigger Whether to trigger theerrorfor deprecated files. Default true. 
  17. */ 
  18. $message = empty( $message ) ? '' : ' ' . $message; 
  19. if ( function_exists( '__' ) ) { 
  20. if ( ! is_null( $replacement ) ) { 
  21. /** translators: 1: PHP file name, 2: version number, 3: alternative file name */ 
  22. trigger_error( sprintf( __('%1$s is <strong>deprecated</strong> since version %2$s! Use %3$s instead.'), $file, $version, $replacement ) . $message ); 
  23. } else { 
  24. /** translators: 1: PHP file name, 2: version number */ 
  25. trigger_error( sprintf( __('%1$s is <strong>deprecated</strong> since version %2$s with no alternative available.'), $file, $version ) . $message ); 
  26. } else { 
  27. if ( ! is_null( $replacement ) ) { 
  28. trigger_error( sprintf( '%1$s is <strong>deprecated</strong> since version %2$s! Use %3$s instead.', $file, $version, $replacement ) . $message ); 
  29. } else { 
  30. trigger_error( sprintf( '%1$s is <strong>deprecated</strong> since version %2$s with no alternative available.', $file, $version ) . $message );