¿Cómo desaprobar una función utilizada en un complemento?

Una de las funciones que estoy usando en mi complemento es contaminar el alcance global con un nombre que podría colisionar con otra función (utilizada en otro complemento). Entonces, supongo que debería desaprobarlo. Pero, ¿cómo debo hacer eso?

function foo() {
    echo 'bar';
}

Estoy al tanto, _deprecate_function()pero agradecería un ejemplo que muestre todos los pasos que debo seguir para eliminar la función del núcleo de mi complemento.

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

Además de la respuesta de @Welcher:

Hay algunos buenos ejemplos de " cementerio " en el núcleo, donde "las funciones vienen a morir ".

Puede usarlos como pautas, por ejemplo, con respecto a la documentación.

Aquí hay un ejemplo de esto permalink_link()debajo dewp-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();
}

Aquí está la documentación en línea para la _deprecated_functionfunción que explica los 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.
 */

La desaprobación no siempre equivale a ser eliminado, por lo general significa que el elemento está marcado para su eliminación EVENTUAL de la API. ¿Es este un método que se llamará externamente, como lo hacen otros complementos o desarrolladores? Si este método solo es utilizado internamente por el complemento, probablemente pueda eliminarlo con seguridad y reemplazarlo con una mejor función de nombre.

De lo contrario, crearía la función mejor nombrada y la llamaría mal con una __doing_it_wrongllamada; lea sobre esto en el códice Esto les dará tiempo a otros desarrolladores para actualizar sus referencias al método y puede eliminarlo de manera segura en Una versión 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 esto ayude!

Crea un nuevo complemento y aconseja a sus usuarios que migren a él, ya que el actual es EOL.

No hay nada más molesto que los autores de plugins y temas que cambian sus API públicas e intentan tratarlo como "solo otra pequeña actualización". No hay razón para romper sitios debido a un problema por el cual sus usuarios no se ven afectados.

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

Esto tiene el efecto de mostrar una advertencia de desuso en los registros junto con un seguimiento de la pila. Naturalmente, esto solo funcionará si el registro está habilitado en WordPress.

El operador ternario está allí porque la constante E_USER_DEPRECATED solo se introdujo en PHP 5.3.0. En versiones anteriores, podemos recurrir a una simple advertencia de usuario.

Del manual de PHP sobre constantes de error :

E_DEPRECATED Avisos de tiempo de ejecución. Habilite esto para recibir advertencias sobre el código que no funcionará en futuras versiones.

La razón por la que no me gusta usar _doing_it_wrong o __deprecated_function es que estas funciones están destinadas solo al núcleo de WordPress. De la referencia del código en esas funciones:

El acceso de esta función está marcado como privado. Esto significa que no está destinado a ser utilizado por desarrolladores de plugins o temas, solo en otras funciones principales. Se enumera aquí para completar.