_DOING_IT_WRONG() в WordPress: Как использовать и зачем нужна функция 3.1.0

# _DOING_IT_WRONG() │ WP 3.1.0

Функция, которая указывает, что что-то было вызвано неправильно.

Функция _doing_it_wrong создаёт событие, которое можно использовать для получения информации о том, в каком файле и функции была вызвана устаревшая функция. 

Если включен режим отладки (WP_DEBUG), то произойдёт ошибка.

### Внутренняя функция

Эта функция предназначена для использования только в ядре WordPress. Не рекомендуется использовать её в вашем коде.

## Хуки функции

- doing_it_wrong_run
- doing_it_wrong_trigger_error

## Возврат

- null. Ничего не ��озвращает.

## Использование

```php
_doing_it_wrong( $function_name, $message, $version );

• $function_name (строка, обязательный параметр) — имя функции, которая была вызвана.
• $message (строка, обязательный параметр) — сообщение, объясняющее, что было сделано неправильно.
• $version (строка, обязательный параметр) — версия WordPress, в которой появилось данное сообщение.

Примеры

Пример 1: Ошибка, когда глобальная переменная не доступна

В этом примере функция is_archive() требует глобальную переменную $wp_query. Это значит, что функцию нужно вызывать только после того, как эта переменная объявлена. Если попробовать вызвать её раньше, появится ошибка.

function is_archive() {
    global $wp_query;

    if ( ! isset( $wp_query ) ) {
        _doing_it_wrong( __FUNCTION__, __( 'Условные запросы не работают до выполнения запроса. До этого момента они всегда возвращают false.' ), '3.1.0' );
        return false;
    }

    return $wp_query->is_archive();
}

Пример 2: Ошибка, когда функция вызывается не на том хуке

Этот пример из ядра WordPress. Он сообщает пользователю, что функция регистрации REST маршрутов была вызвана не на хуке rest_api_init, как должно быть.

if ( ! did_action( 'rest_api_init' ) ) {
    _doing_it_wrong(
        'register_rest_route',
        sprintf(
            /* translators: %s: rest_api_init */
            __( 'REST API маршруты должны регистрироваться на хук %s.' ),
            'rest_api_init'
        ),
        '5.1.0'
    );
}

Изменения

• С версии 3.1.0 — функционал был введен.
• С версии 5.4.0 — эта функция больше не считается "приватной".

Код функции _doing_it_wrong

function _doing_it_wrong( $function_name, $message, $version ) {
    // Вызывает событие, когда функция вызывается неправильно.
    do_action( 'doing_it_wrong_run', $function_name, $message, $version );

    // Проверяем, следует ли вызывать ошибку для вызовов _doing_it_wrong().
    if ( WP_DEBUG && apply_filters( 'doing_it_wrong_trigger_error', true, $function_name, $message, $version ) ) {
        if ( function_exists( '__' ) ) {
            if ( $version ) {
                $version = sprintf( __( '(Это сообщение появилось в версии %s.)' ), $version );
            }

            $message .= ' ' . sprintf(
                __( 'Дополнительную информацию смотрите отладка в WordPress.' ),
                __( 'https://developer.wordpress.org/advanced-administration/debug/debug-wordpress/' )
            );

            $message = sprintf(
                __( 'Функция %1$s была вызвана неправильно. %2$s %3$s' ),
                $function_name,
                $message,
                $version
            );
        } else {
            if ( $version ) {
                $version = sprintf( '(Это сообщение появилось в версии %s.)', $version );
            }

            $message .= sprintf(
                ' Дополнительную информацию смотрите отладка в WordPress.',
                'https://developer.wordpress.org/advanced-administration/debug/debug-wordpress/'
            );

            $message = sprintf(
                'Функция %1$s была вызвана неправильно. %2$s %3$s',
                $function_name,
                $message,
                $version
            );
        }

        wp_trigger_error( '', $message );
    }
}

Связанные функции

• get_num_queries()
• wp_debug_backtrace_summary()
• wp_debug_mode()
• wp_get_development_mode()
• wp_get_environment_type()
• wp_is_development_mode()