Функция _deprecated_function(): использование и примеры кода

## Функция _deprecated_function() │ WP 2.5.0

Функция маркирует другую функцию как устаревшую и уведомляет пользователя о её использовании.

Существует хук deprecated_function_run, который срабатывает при вызове устаревшей функции. Он позволяет отследить, из какого файла и функции была вызвана устаревшая функция.

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

Эта функция используется во всех функциях, которые отмечены как устаревшие.

> **Важно:** Функция предназначена для внутреннего использования в ядре WordPress. Не реком��ндуется использовать её в своём коде.

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

- deprecated_function_run 
- deprecated_function_trigger_error 

### Возврат

Функция ничего не возвращает (null).

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

```php
_deprecated_function( $function_name, $version, $replacement );

Параметры:

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

Пример использования

Вот пример, как использовать эту функцию в ядре WordPress:

function logIO( $io, $msg ) {
    _deprecated_function( __FUNCTION__, '3.4', 'error_log()' );

    if ( ! empty( $GLOBALS['xmlrpc_logging'] ) )
        error_log( $io . ' - ' . $msg );
}

Журнал изменений

• С версии 2.5.0 — функция была введена.
• С версии 5.4.0 — функция больше не помечается как "приватная".
• С версии 5.4.0 — тип ошибки теперь классифицируется как E_USER_DEPRECATED (ранее по умолчанию было E_USER_NOTICE).

Код функции _deprecated_function

Функция расположена в файле wp-includes/functions.php.

function _deprecated_function( $function_name, $version, $replacement = '' ) {
    /**
     * Срабатывает при вызове устаревшей функции.
     *
     * @since 2.5.0
     *
     * @param string $function_name Имя вызываемой функции.
     * @param string $replacement   Имя функции, которую следовало бы вызвать.
     * @param string $version       Версия WordPress, в которой функция была устаревшей.
     */
    do_action( 'deprecated_function_run', $function_name, $replacement, $version );

    /**
     * Фильтрует решение о выдаче ошибки для устаревших функций.
     *
     * @since 2.5.0
     *
     * @param bool $trigger Нужно ли вызвать ошибку для устаревших функций. По умолчанию true.
     */
    if ( WP_DEBUG && apply_filters( 'deprecated_function_trigger_error', true ) ) {
        if ( function_exists('__') ) {
            if ( $replacement ) {
                $message = sprintf(
                    __( 'Функция %1$s устарела с версии %2$s! Используйте %3$s вместо неё.' ),
                    $function_name,
                    $version,
                    $replacement
                );
            } else {
                $message = sprintf(
                    __( 'Функция %1$s устарела с версии %2$s и у неё нет доступной альтернативы.' ),
                    $function_name,
                    $version
                );
            }
        } else {
            if ( $replacement ) {
                $message = sprintf(
                    'Функция %1$s устарела с версии %2$s! Используйте %3$s вместо неё.',
                    $function_name,
                    $version,
                    $replacement
                );
            } else {
                $message = sprintf(
                    'Функция %1$s устарела с версии %2$s и у неё нет доступной альтернативы.',
                    $function_name,
                    $version
                );
            }
        }

        wp_trigger_error( '', $message, E_USER_DEPRECATED );
    }
}

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

• create_initial_post_types()
• wp_nav_menu_post_type_meta_boxes()
• wp_nav_menu_setup()
• wp_nav_menu_taxonomy_meta_boxes()