Come deprecare una funzione utilizzata in un plugin?

Una delle funzioni che sto usando nel mio plugin è inquinare l'ambito globale con un nome che potrebbe scontrarsi con un'altra funzione (usata in un altro plugin). Quindi, suppongo che dovrei deprecarlo. Ma come dovrei farlo?

function foo() {
    echo 'bar';
}

Sono a conoscenza, _deprecate_function()ma sarei grato per un esempio che mostra tutti i passaggi che dovrei prendere per rimuovere la funzione dal core del mio plugin.

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

Oltre alla risposta di @Welcher:

Ci sono alcuni buoni esempi di " cimitero " nel nucleo, in cui "le funzioni vengono a morire ".

È possibile utilizzarli come linee guida, ad esempio per quanto riguarda la documentazione.

Ecco un esempio per il permalink_link()sottowp-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();
}

Ecco la documentazione in linea per la _deprecated_functionfunzione che spiega gli argomenti di input:

/**
 * 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 deprecazione non equivale sempre alla rimozione, di solito significa che l'elemento è contrassegnato per la RIMOZIONE EVENTUALE dall'API. È un metodo che verrà chiamato esternamente, come in altri plugin o sviluppatori? Se questo metodo viene utilizzato solo internamente dal plugin, è possibile rimuoverlo in modo sicuro sostituendolo con una funzione di nome migliore.

In caso contrario, creerei la funzione con il nome migliore e la chiamerei male con quella chiamata con una __doing_it_wrongchiamata - leggi su di essa nel codice Questo darà agli altri sviluppatori il tempo di aggiornare i loro riferimenti al metodo e puoi tranquillamente rimuovere il metodo in una versione successiva.

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

Spero che sia di aiuto!

Si crea un nuovo plug-in e si consiglia ai propri utenti di migrare verso di esso poiché quello attuale è EOL.

Non c'è niente di più fastidioso di autori di plugin e temi che cambiano le loro API pubbliche e provano a trattarlo come "solo un altro piccolo aggiornamento". Non vi è alcun motivo per interrompere i siti a causa di un problema a cui gli utenti non sono effettivamente interessati.

Vorrei suggerire qualcosa di simile:

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

Ciò ha l'effetto di mostrare un avviso di deprecazione nei registri insieme a una traccia dello stack. Naturalmente questo funzionerà solo se la registrazione è abilitata in WordPress.

L'operatore ternario è lì perché la costante E_USER_DEPRECATED è stata introdotta solo in PHP 5.3.0. Nelle versioni precedenti possiamo invece ricorrere a un semplice avviso utente.

Dal manuale di PHP sulle costanti di errore :

E_DEPRECATED Avvisi di runtime. Abilita questo per ricevere avvisi sul codice che non funzionerà nelle versioni future.

Il motivo per cui non mi piace usare _doing_it_wrong o __deprecated_function è che queste funzioni sono destinate solo al core di WordPress. Dal riferimento al codice su tali funzioni:

L'accesso a questa funzione è contrassegnato come privato. Ciò significa che non è destinato all'uso da parte di sviluppatori di plugin o temi, ma solo in altre funzioni principali. È elencato qui per completezza.