Como descontinuar uma função usada em um plugin?

Uma das funções que estou usando no meu plug-in está poluindo o escopo global com um nome que pode colidir com outra função (usada em outro plug-in). Então, acho que devo depreciá-lo. Mas como devo fazer isso?

function foo() {
    echo 'bar';
}

Estou ciente, _deprecate_function()mas ficaria grato por um exemplo mostrando todas as etapas que devo seguir para remover a função do núcleo do meu plugin.

Ref: https://developer.wordpress.org/reference/functions/_deprecated_function/

Além da resposta de @Welcher:

Existem alguns bons exemplos de " cemitério " no núcleo, em que " funções morrem ".

Você pode usá-los como diretrizes, por exemplo, com relação à documentação.

Aqui está um exemplo para o permalink_link()sob owp-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();
}

Aqui está a documentação embutida para a _deprecated_functionfunção que explica os argumentos de entrada:

/**
 * 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.
 */

A reprovação nem sempre é igual à remoção, geralmente significa que o item está marcado para remoção EVENTUAL da API. Esse é um método que será chamado externamente - como em outros plugins ou desenvolvedores? Se esse método for usado apenas internamente pelo plug-in, provavelmente você poderá remover com segurança substituí-lo por uma função de nome melhor.

Caso contrário, eu criaria a função com melhor nome e chamaria a pessoa com o nome incorreto com uma __doing_it_wrongchamada - leia sobre isso no codex Isso dará a outros desenvolvedores tempo para atualizar suas referências ao método e você pode remover com segurança o método em uma versão posterior.

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

Espero que isto ajude!

Você cria um novo plug-in e aconselha seus usuários a migrar para ele, pois o atual é o EOL.

Não há nada mais irritante do que autores de plugins e temas alterando suas APIs públicas e tentando tratá-lo como "apenas mais uma pequena atualização". Não há motivo para interromper sites devido a um problema pelo qual os usuários não estão sendo afetados.

Eu sugeriria algo como:

/**
 * @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();
}

Isso tem o efeito de mostrar um aviso de descontinuação nos logs, juntamente com um rastreamento de pilha. Naturalmente, isso só funcionará se o log estiver ativado no WordPress.

O operador ternário está lá porque a constante E_USER_DEPRECATED foi introduzida apenas no PHP 5.3.0. Nas versões anteriores, podemos recorrer a um aviso simples do usuário.

No manual do PHP sobre constantes de erro :

E_DEPRECATED Avisos de tempo de execução. Habilite isso para receber avisos sobre código que não funcionará em versões futuras.

O motivo pelo qual não gosto de usar _doing_it_wrong ou __deprecated_function é que essas funções são destinadas apenas ao núcleo do WordPress. A partir da referência de código nessas funções:

O acesso desta função é marcado como privado. Isso significa que ele não deve ser usado por desenvolvedores de plug-ins ou temas, apenas em outras funções principais. Ele está listado aqui para integridade.