Как отказаться от функции, используемой в плагине?

Одной из функций, которые я использую в своем плагине, является загрязнение глобальной области видимости именем, которое может конфликтовать с другой функцией (используемой в другом плагине). Итак, я думаю, я должен осудить это. Но как мне это сделать?

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. Это метод, который будет вызываться извне - как другие плагины или разработчики? Если этот метод только когда-либо используется плагином внутри, вы можете безопасно удалить его и заменить его на более подходящую функцию name.

Если нет, я бы создал функцию с лучшим именем, и одна из них с плохим именем вызывала ее __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. Из ссылки на код этих функций:

Доступ к этой функции помечен как частный. Это означает, что он не предназначен для использования разработчиками плагинов или тем, только в других основных функциях. Это перечислено здесь для полноты.