Comment déprécier une fonction utilisée dans un plugin?

L'une des fonctions que j'utilise dans mon plugin pollue la portée globale avec un nom qui pourrait entrer en collision avec une autre fonction (utilisée dans un autre plugin). Donc, je suppose que je devrais le déprécier. Mais comment dois-je procéder?

function foo() {
    echo 'bar';
}

Je suis au courant, _deprecate_function()mais je serais reconnaissant pour un exemple montrant toutes les étapes à suivre pour supprimer la fonction du cœur de mon plugin.

Réf: https://developer.wordpress.org/reference/functions/_deprecated_function/

En plus de la réponse de @Welcher:

Il y a quelques bons exemples de " cimetière " dans le noyau, où "les fonctions viennent à mourir ".

Vous pouvez les utiliser comme lignes directrices, par exemple en ce qui concerne la documentation.

Voici un exemple pour le permalink_link()sous lewp-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();
}

Voici la documentation en ligne de la _deprecated_functionfonction qui explique les arguments d'entrée:

/**
 * 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 dépréciation n'est pas toujours égale à la suppression, cela signifie généralement que l'élément est marqué pour une suppression EVENTUELLE de l'API. Est-ce une méthode qui sera appelée en externe - comme par d'autres plugins ou développeurs? Si cette méthode n'est utilisée que par le plugin en interne, vous pouvez probablement le supprimer en toute sécurité en le remplaçant par une meilleure fonction de nom.

Sinon, je créerais la fonction la mieux nommée et je demanderais à celle qui est mal nommée de l'appeler avec un __doing_it_wrongappel - lisez-la dans le codex Cela donnera aux autres développeurs le temps de mettre à jour leurs références à la méthode et vous pouvez supprimer la méthode en toute sécurité dans une version ultérieure.

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

J'espère que cela t'aides!

Vous créez un nouveau plugin et conseillez à vos utilisateurs de migrer vers celui-ci car celui-ci est EOL.

Il n'y a rien de plus ennuyeux que les auteurs de plugins et de thèmes changeant leurs API publiques et essayant de les traiter comme "juste une autre petite mise à jour". Il n'y a aucune raison de casser des sites en raison d'un problème qui n'affecte pas réellement vos utilisateurs.

Je suggérerais quelque chose comme:

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

Cela a pour effet d'afficher un avertissement de dépréciation dans les journaux avec une trace de pile. Naturellement, cela ne fonctionnera que si la journalisation est activée dans WordPress.

L'opérateur ternaire est là car la constante E_USER_DEPRECATED n'a été introduite qu'en PHP 5.3.0. Dans les anciennes versions, nous pouvons plutôt recourir à un simple avertissement utilisateur.

Du manuel PHP sur les constantes d'erreur :

E_DEPRECATED Avis d'exécution . Activez cette option pour recevoir des avertissements sur le code qui ne fonctionnera pas dans les futures versions.

La raison pour laquelle je n'aime pas utiliser _doing_it_wrong ou __deprecated_function est que ces fonctions sont destinées uniquement au noyau WordPress. De la référence de code sur ces fonctions:

L'accès à cette fonction est marqué comme privé. Cela signifie qu'il n'est pas destiné à être utilisé par les développeurs de plugins ou de thèmes, uniquement dans d'autres fonctions de base. Il est répertorié ici pour être complet.