Як знецінити функцію, що використовується в плагіні?

Однією з функцій, які я використовую у своєму плагіні, є забруднення глобальної області застосування іменем, яке могло зіткнутися з іншою функцією (використовується в іншому плагіні). Отже, я думаю, я мав би знестирити це. Але як мені це робити?

function foo() {
    echo 'bar';
}

Я знаю, _deprecate_function()але буду вдячний за приклад, який показує всі кроки, які я повинен зробити, щоб вилучити функцію з ядра мого плагіна.

Посилання: https://developer.wordpress.org/reference/functions/_deprecated_function/

Окрім відповіді від @Welcher:

У ядрі є кілька хороших прикладів " кладовища ", де " функції вмирають ".

Ви можете використовувати їх як керівництво, наприклад, стосовно документації.

Ось один з таких прикладів для permalink_link()підwp-includes/deprecated.php

/**
 * Print the permalink of the current post in the loop.
 *
 * @since 0.71
 * @deprecated 1.2.0 Use the_permalink()
 * @see the_permalink()
 */
function permalink_link() {
        _deprecated_function( __FUNCTION__, '1.2', 'the_permalink()' );
        the_permalink();
}

Ось вбудована документація для _deprecated_functionфункції, яка пояснює вхідні аргументи:

/**
 * Mark a function as deprecated and inform when it has been used.
 *
 * There is a hook deprecated_function_run 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.
 *
 * This function is to be used in every function that is deprecated.
 *
 * @since 2.5.0
 * @access private
 *
 * @param string $function    The function that was called.
 * @param string $version     The version of WordPress that deprecated the function.
 * @param string $replacement Optional. The function that should have been called. 
 *                            Default null.
 */

Видалення не завжди є рівним видаленням, зазвичай це означає, що елемент позначено як ЕКСПЕКТИВНЕ вилучення з API. Це метод, який називатиметься зовні - як у інших плагінах чи розробниках? Якщо цей метод будь-коли використовується внутрішнім плагіном, ви, ймовірно, можете спокійно видалити його, замінивши його на кращу функцію імені.

Якщо ні, то я б створив краще названу функцію і мав би погано назвати її з __doing_it_wrongвикликом - прочитайте про це в кодексі. Це дасть іншим розробникам час на оновлення своїх посилань на метод, і ви можете спокійно видалити метод у пізніша версія.

function badly_named() {

    __doing_it_wrong( 'badly_named', 'This method has been deprecated in favor of better_named_function' );

    /**
     * Call the better named method
     */
     better_named_function();
}

Сподіваюся, це допомагає!

Ви створюєте новий плагін і радите своїм користувачам переходити до нього, оскільки поточний EOL.

Немає нічого більш прикрого, ніж автори плагінів і тем, що змінюють свої публічні API та намагаються трактувати це як "лише чергове оновлення". Немає причин зламати сайти через проблему, на яку насправді не впливають ваші користувачі.

Я б запропонував щось на зразок:

/**
 * @deprecated Please use good_function_name() instead
 * @since x.y.z Marked deprecated in favor of good_function_name()
 * @see good_function_name()
 */
function bad_function_name() {
    trigger_error(
        'The ' . __FUNCTION__ . ' function is deprecated. ' .
        'Please use good_function_name() instead.',
        defined( 'E_USER_DEPRECATED' ) ? E_USER_DEPRECATED : E_USER_WARNING
    );

    return good_function_name();
}

Це призводить до того, що в журналах відображається попередження про припинення роботи разом із слідом стека. Природно, це спрацює лише в тому випадку, якщо ввімкнути журнал в WordPress.

Потрійний оператор є, тому що константа E_USER_DEPRECATED була введена лише в PHP 5.3.0. У старих версіях ми можемо перейти до простого попередження користувача.

З посібника PHP про константи помилок :

E_DEPRECATED Повідомлення про виконання часу. Увімкніть це, щоб отримувати попередження про код, який не працюватиме в наступних версіях.

Причина, що мені не подобається використовувати _doing_it_wrong або __deprecated_function, полягає в тому, що ці функції призначені лише для ядра WordPress. З посилання коду на ці функції:

Доступ до цієї функції позначено приватним. Це означає, що він не призначений для використання розробниками плагінів або тем, лише для інших основних функцій. Він перерахований тут для повноти.