_doing_it_wrong() │ WP 3.1.0

Mark something as being incorrectly called.

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

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

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

Return

null. Nothing (null).

Usage

_doing_it_wrong( $function_name, $message, $version );
$function_name(string) (required)
The function that was called.
$message(string) (required)
A message explaining what has been done incorrectly.
$version(string) (required)
The version of WordPress where the message was added.

Examples

0

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

0

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

Changelog

Since 3.1.0 Introduced.
Since 5.4.0 This function is no longer marked as "private".

_doing_it_wrong() code WP 6.5.2

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://wordpress.org/documentation/article/debugging-in-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://wordpress.org/documentation/article/debugging-in-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