web-dev-qa-db-fra.com

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

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 je serais reconnaissant pour un exemple montrant toutes les étapes à suivre pour supprimer la fonction du noyau de mon plugin.

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

phpfunctionsdeprecation
15
henrywright

En plus de la réponse de @Welcher:

Il y a de bons exemples " graveyard " 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 la permalink_link() sous le 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();
}

Voici la documentation en ligne de la fonction _deprecated_function 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.
 */
9
birgire

Deprecation n'est pas toujours égal à être supprimé, cela signifie généralement que l'élément est marqué pour la suppression 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.

Sinon, je créerais la fonction mieux nommée et demanderais à celui mal nommé de l'appeler avec un appel __doing_it_wrong - à lire dans le codex Cela donnera le temps aux autres développeurs 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!

7
Welcher

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 versions plus anciennes, nous pouvons utiliser un simple avertissement d'utilisateur.

À partir 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. 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 listé ici pour être complet.

1
alexg

Vous créez un nouveau plug-in et conseillez à vos utilisateurs de migrer vers celui-ci car l'actuel est EOL.

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

1
Mark Kaplun