Jak wycofać funkcję używaną we wtyczce?

Jedną z funkcji, których używam w mojej wtyczce, jest zanieczyszczenie zasięgu globalnego nazwą, która może kolidować z inną funkcją (używaną w innej wtyczce). Więc chyba powinienem to zrobić. Ale jak mam to zrobić?

function foo() {
    echo 'bar';
}

Jestem tego świadomy, _deprecate_function()ale byłbym wdzięczny za przykład pokazujący wszystkie kroki, które powinienem podjąć, aby usunąć funkcję z rdzenia mojej wtyczki.

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

Oprócz odpowiedzi @Welcher:

Istnieje kilka dobrych „ cmentarnych ” przykładów w rdzeniu, w których „ funkcje umierają ”.

Możesz wykorzystać je jako wytyczne, np. Dotyczące dokumentacji.

Oto jeden taki przykład dla permalink_link()podwp-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();
}

Oto wbudowana dokumentacja _deprecated_functionfunkcji wyjaśniająca argumenty wejściowe:

/**
 * 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.
 */

Usunięcie wycofania nie zawsze jest równoznaczne z usunięciem, zwykle oznacza to, że element jest oznaczony do WYDARZENIA z API. Czy jest to metoda, która zostanie wywołana zewnętrznie - tak jak w przypadku innych wtyczek lub programistów? Jeśli ta metoda jest używana tylko przez wtyczkę wewnętrznie, prawdopodobnie możesz bezpiecznie usunąć zastąpić ją lepszą funkcją nazwy.

Jeśli nie, utworzę funkcję o lepszej nazwie, a źle nazwane wywołanie wywoła __doing_it_wrongją - przeczytaj o tym w kodeksie. Daje to innym programistom czas na aktualizację odniesień do metody i możesz bezpiecznie usunąć metodę w późniejsza wersja.

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

Mam nadzieję że to pomoże!

Tworzysz nową wtyczkę i doradzasz użytkownikom migrację do niej, ponieważ bieżąca to EOL.

Nie ma nic bardziej irytującego niż autorzy wtyczek i motywów zmieniający swoje publiczne interfejsy API i starający się traktować to jako „kolejną małą aktualizację”. Nie ma powodu, aby niszczyć witryny z powodu problemu, na który faktycznie nie mają wpływu użytkownicy.

Sugerowałbym coś takiego:

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

Powoduje to wyświetlenie w dziennikach ostrzeżenia o wycofaniu oraz śledzenia stosu. Oczywiście będzie to działać tylko wtedy, gdy w WordPress jest włączone rejestrowanie.

Operator trójskładnikowy istnieje, ponieważ stała E_USER_DEPRECATED została wprowadzona tylko w PHP 5.3.0. W starszych wersjach możemy zamiast tego wrócić do prostego ostrzeżenia użytkownika.

Z podręcznika PHP o stałych błędów :

E_DEPRECATED Powiadomienia o czasie wykonywania. Włącz tę opcję, aby otrzymywać ostrzeżenia o kodzie, który nie będzie działał w przyszłych wersjach.

Powodem, dla którego nie lubię używać _doing_it_wrong lub __deprecated_function jest to, że te funkcje są przeznaczone tylko dla rdzenia WordPress. Z odwołania do kodu na temat tych funkcji:

Dostęp do tej funkcji jest oznaczony jako prywatny. Oznacza to, że nie jest przeznaczony do użytku przez twórców wtyczek lub motywów, a jedynie do innych podstawowych funkcji. Podano tutaj kompletność.