_doing_it_wrong() │ WP 3.1.0

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

0

#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();
}
-1

#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".

_doing_it_wrong() code WP 6.8.1

wp-includes/functions.php 
function _doing_it_wrong( $function_name, $message, $version ) {

	/**
	 * Fires when the given function is being used incorrectly.
	 *
	 * @since 3.1.0
	 *
	 * @param string $function_name The function that was called.
	 * @param string $message       A message explaining what has been done incorrectly.
	 * @param string $version       The version of WordPress where the message was added.
	 */
	do_action( 'doing_it_wrong_run', $function_name, $message, $version );

	/**
	 * Filters whether to trigger an error for _doing_it_wrong() calls.
	 *
	 * @since 3.1.0
	 * @since 5.1.0 Added the $function_name, $message and $version parameters.
	 *
	 * @param bool   $trigger       Whether to trigger the error for _doing_it_wrong() calls. Default true.
	 * @param string $function_name The function that was called.
	 * @param string $message       A message explaining what has been done incorrectly.
	 * @param string $version       The version of WordPress where the message was added.
	 */
	if ( WP_DEBUG && apply_filters( 'doing_it_wrong_trigger_error', true, $function_name, $message, $version ) ) {
		if ( function_exists( '__' ) ) {
			if ( $version ) {
				/* translators: %s: Version number. */
				$version = sprintf( __( '(This message was added in version %s.)' ), $version );
			}

			$message .= ' ' . sprintf(
				/* translators: %s: Documentation URL. */
				__( 'Please see <a href="%s">Debugging in WordPress</a> for more information.' ),
				__( 'https://developer.wordpress.org/advanced-administration/debug/debug-wordpress/' )
			);

			$message = sprintf(
				/* translators: Developer debugging message. 1: PHP function name, 2: Explanatory message, 3: WordPress version number. */
				__( 'Function %1$s was called <strong>incorrectly</strong>. %2$s %3$s' ),
				$function_name,
				$message,
				$version
			);
		} else {
			if ( $version ) {
				$version = sprintf( '(This message was added in version %s.)', $version );
			}

			$message .= sprintf(
				' Please see <a href="%s">Debugging in WordPress</a> for more information.',
				'https://developer.wordpress.org/advanced-administration/debug/debug-wordpress/'
			);

			$message = sprintf(
				'Function %1$s was called <strong>incorrectly</strong>. %2$s %3$s',
				$function_name,
				$message,
				$version
			);
		}

		wp_trigger_error( '', $message );
	}
}

debug

Uncategorized