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

14

Uma das funções que estou usando no meu plugin é poluir o escopo global com um nome que poderia colidir com outra função (usada em outro plugin). Então, eu acho que deveria depreciá-lo. Mas como devo fazer isso?

function foo() {
    echo 'bar';
}

Estou ciente de _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 plug-in.

Ref: enlace

    
por henrywright 22.12.2015 / 14:38

4 respostas

9

Além da resposta de @Welcher:

Existem alguns bons exemplos " cemitério " no núcleo, onde " funções vêm para morrer ".

Você pode usá-los como diretrizes, por exemplo, sobre a documentação.

Veja um exemplo para o permalink_link() no 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();
}

Esta é a documentação inline da função _deprecated_function 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.
 */
    
por birgire 22.12.2015 / 15:22
7

A desativação nem sempre é igual à remoção, geralmente significa que o item está marcado para remoção EVENTUAL da API. Este é um método que será chamado externamente - como em outros plugins ou desenvolvedores? Se este método só é usado pelo plug-in internamente, você provavelmente pode remover com segurança a substituição por uma função de nome melhor.

Se não, eu criaria a função com melhor nome e faria com que o mal nomeado o chamasse com uma chamada __doing_it_wrong - leia sobre isso no codex Isso dará a outros desenvolvedores tempo para atualizar suas referências ao método e você poderá remover o método com segurança 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 isso ajude!

    
por Welcher 22.12.2015 / 15:09
2

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 os autores de plugins e de temas mudando suas APIs públicas e tentem tratá-las como "apenas outra pequena atualização". Não há motivos para interromper sites devido a um problema em que seus usuários não estão sendo afetados.

    
por Mark Kaplun 22.12.2015 / 15:06
1

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 reprovação nos logs junto 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. Em versões mais antigas, podemos recorrer a um simples aviso de usuário.

Do Manual do PHP sobre constantes de erros :

  

E_DEPRECATED Avisos em tempo de execução. Habilite isso para receber avisos sobre códigos que não funcionarão 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 sobre essas funções:

  

O acesso desta função está marcado como privado. Isso significa que não é destinado ao uso por desenvolvedores de plug-ins ou de temas, apenas em outras funções principais. Está listado aqui para ser completo.

    
por alexg 06.07.2017 / 10:33