_doing_it_wrong()
Mark something as "done incorrectly". For example, the function is called incorrectly, the parameter is specified incorrectly, etc.
The message will be displayed only if debug mode is enabled - WP_DEBUG = true
.
The function calls the hook doing_it_wrong_run, which can be used for your purposes to handle the error. For example, this hook will be useful for a live site where debug mode is turned off, but we want to catch "done incorrectly" errors. To do this, we attach our function to this hook and handle the received errors, for example, saving them to a file or sending ourselves an email about the error.
The function works based on the PHP function trigger_error().
Internal function — this function is designed to be used by the kernel itself. It is not recommended to use this function in your code.
Hooks from the function
Returns
null
. Nothing.
Usage
_doing_it_wrong( $function, $message, $version );
- $function(string) (required)
- The name of the function in which something is done incorrectly.
- $message(string) (required)
- A message explaining what was done incorrectly.
- $version(string) (required)
- The version of WordPress with which this action became incorrect (deprecated).
Examples
#1 Show the error when there is no global variable in the function
In this example, the function is_archive() needs the global variable $wp_query, which means that the function must be called after this variable is defined. If it is called before, we will print an error about it.
function is_archive() { global $wp_query; if ( ! isset( $wp_query ) ) { _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' ); return false; } return $wp_query->is_archive(); }
#2 Show the error when the function is called on the wrong hook.
This example is from WP core. It tells the user that he called the REST route registration function not on the rest_api_init hook, as it should be done.
if ( ! did_action( 'rest_api_init' ) ) { _doing_it_wrong( 'register_rest_route', sprintf( /* translators: %s: rest_api_init */ __( 'REST API routes must be registered on the %s action.' ), '<code>rest_api_init</code>' ), '5.1.0' ); }
See code register_rest_route().
Changelog
Since 3.1.0 | Introduced. |
Since 5.4.0 | This function is no longer marked as "private". |