Comment déconseiller une fonction utilisée dans un plugin?

14

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éconseiller. Mais comment dois-je m'y prendre?

function foo() {
    echo 'bar';
}

Je suis au courant de _deprecate_function() mais souhaiterais un exemple montrant toutes les étapes à suivre pour supprimer la fonction du noyau de mon plugin.

Réf.: enlace

    
posée henrywright 22.12.2015 - 14:38

4 réponses

9

En plus de la réponse de @Welcher:

Il existe de bons exemples " graveyard " dans le noyau, où " Les fonctions viennent de mourir ".

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

Voici un exemple de ce type pour permalink_link() dans le co_ %

/**
 * 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 concernant la wp-includes/deprecated.php 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.
 */
    
réponse donnée birgire 22.12.2015 - 15:22
7

Deprecation n'est pas toujours égal à être supprimé, cela signifie généralement que l'élément est marqué pour suppression par EVENTUAL de l'API. Est-ce une méthode qui sera appelée en externe - comme dans d'autres plugins ou développeurs? Si cette méthode est uniquement utilisée en interne par le plug-in, vous pouvez probablement l'enlever en toute sécurité, remplacez-la par une meilleure fonction de nom.

Dans le cas contraire, je créerais la fonction la mieux nommée et la personne mal nommée l'appellera avec un appel __doing_it_wrong . Pour en savoir plus, consultez la section codex Cela laissera aux autres développeurs le temps de mettre à jour leurs références à la méthode et vous pourrez 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 aide!

    
réponse donnée Welcher 22.12.2015 - 15:09
2

Vous créez un nouveau plug-in et conseillez à vos utilisateurs de le migrer, car celui-ci est EOL.

Il n’existe rien de plus ennuyeux que les auteurs de plug-ins et de thèmes qui modifient leurs API publiques et essaient de les traiter comme "juste une autre petite mise à niveau". Il n’ya aucune raison de casser des sites en raison d’un problème qui n’affecte pas vos utilisateurs.

    
réponse donnée Mark Kaplun 22.12.2015 - 15:06
1

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 présent car la constante E_USER_DEPRECATED n'a été introduite que dans PHP 5.3.0. Dans les anciennes versions, nous pouvons utiliser un simple avertissement utilisateur.

Extrait 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 versions futures.

La raison pour laquelle je n'aime pas utiliser _doing_it_wrong ou __ deprecated_function est que ces fonctions sont uniquement destinées au noyau WordPress. A partir 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, mais uniquement dans d'autres fonctions principales. Il est répertorié ici pour être complet.

    
réponse donnée alexg 06.07.2017 - 10:33

Lire d'autres questions sur les étiquettes