Удаление, активация и деактивация плагина: типичные функции и инструкции

Существует три различных хука. Они срабатывают в следующих случаях:

• Удаление
• Деактивация
• Активация

Как безопасно запускать функции в этих сценариях

Ниже показаны правильные способы безопасного подключения функций обратного вызова, которые срабатывают во время упомянутых действий.

Поскольку вы можете использовать этот код в плагине, который использует:

• обычные функции,
• класс или
• внешний класс,

я покажу три разных демонстрационных плагина, которые вы можете изучить, а затем реализовать код в своем собственном плагине(ах).

Важное замечание заранее!

Поскольку эта тема чрезвычайно сложная и очень детализированная, с множеством крайних случаев, этот ответ никогда не будет идеальным. Я буду продолжать улучшать его со временем, так что заглядывайте сюда регулярно.

(1) Активация/Деактивация/Удаление плагинов.

Функции обратного вызова настройки плагина запускаются ядром WordPress, и вы не можете повлиять на то, как ядро это делает. Есть несколько моментов, которые нужно учитывать:

• Никогда не выводите ничего через echo/print во время функций обратного вызова настройки. Это приведет к сообщению headers already sent, и ядро порекомендует деактивировать и удалить ваш плагин... не спрашивайте: я знаю...
• Вы не увидите никакого визуального вывода. Но я добавил операторы exit() во все различные функции обратного вызова, чтобы вы могли понять, что действительно происходит. Просто раскомментируйте их, чтобы увидеть работу.
• Очень важно проверять, что __FILE__ != WP_PLUGIN_INSTALL и (если нет: прерывать выполнение!), чтобы убедиться, что плагин действительно удаляется. Я рекомендую просто запускать функции on_deactivation() во время разработки, чтобы сэкономить время на восстановление всего. По крайней мере, я так делаю.
• Я также добавляю некоторые меры безопасности. Некоторые из них уже выполняются ядром, но, как говорится, Лучше перестраховаться, чем потом жалеть!.
  • Сначала я запрещаю прямой доступ к файлу, если ядро не загружено: defined( 'ABSPATH' ) OR exit;
  • Затем я проверяю, имеет ли текущий пользователь права на выполнение этой задачи.
  • Последней задачей я проверяю реферер. Примечание: Могут быть неожиданные результаты с экраном wp_die(), запрашивающим соответствующие права (и хотите ли вы попробовать снова... ну конечно), если у вас произошла ошибка. Это происходит, потому что ядро перенаправляет вас, устанавливает текущее значение $GLOBALS['wp_list_table']->current_action(); в error_scrape, а затем проверяет реферер для check_admin_referer('plugin-activation-error_' . $plugin);, где $plugin — это $_REQUEST['plugin']. Так что перенаправление происходит на полпути загрузки страницы, и вы получаете эту странную полосу прокрутки и экран смерти внутри желтого уведомления/сообщения администратора. Если это произойдет: сохраняйте спокойствие и просто ищите ошибку с помощью exit() и пошаговой отладки.

(A) Плагин с обычными функциями

Помните, что это может не работать, если вы подключаете функции обратного вызова до определения функции.

<?php
defined( 'ABSPATH' ) OR exit;
/**
 * Plugin Name: (WCM) Activate/Deactivate/Uninstall - Functions
 * Description: Пример плагина, демонстрирующий функции обратного вызова для активации/деактивации/удаления с обычными функциями.
 * Author:      Franz Josef Kaiser/wecodemore
 * Author URL:  http://unserkaiser.com
 * Plugin URL:  http://wordpress.stackexchange.com/questions/25910/uninstall-activate-deactivate-a-plugin-typical-features-how-to/25979#25979
 */

function WCM_Setup_Demo_on_activation()
{
    if ( ! current_user_can( 'activate_plugins' ) )
        return;
    $plugin = isset( $_REQUEST['plugin'] ) ? $_REQUEST['plugin'] : '';
    check_admin_referer( "activate-plugin_{$plugin}" );

    # Раскомментируйте следующую строку, чтобы увидеть функцию в действии
    # exit( var_dump( $_GET ) );
}

function WCM_Setup_Demo_on_deactivation()
{
    if ( ! current_user_can( 'activate_plugins' ) )
        return;
    $plugin = isset( $_REQUEST['plugin'] ) ? $_REQUEST['plugin'] : '';
    check_admin_referer( "deactivate-plugin_{$plugin}" );

    # Раскомментируйте следующую строку, чтобы увидеть функцию в действии
    # exit( var_dump( $_GET ) );
}

function WCM_Setup_Demo_on_uninstall()
{
    if ( ! current_user_can( 'activate_plugins' ) )
        return;
    check_admin_referer( 'bulk-plugins' );

    // Важно: Проверьте, что файл тот же,
    // который был зарегистрирован во время хука удаления.
    if ( __FILE__ != WP_UNINSTALL_PLUGIN )
        return;

    # Раскомментируйте следующую строку, чтобы увидеть функцию в действии
    # exit( var_dump( $_GET ) );
}

register_activation_hook(   __FILE__, 'WCM_Setup_Demo_on_activation' );
register_deactivation_hook( __FILE__, 'WCM_Setup_Demo_on_deactivation' );
register_uninstall_hook(    __FILE__, 'WCM_Setup_Demo_on_uninstall' );

(B) Архитектура на основе классов/OOP

Это наиболее распространенный пример в современных плагинах.

<?php
defined( 'ABSPATH' ) OR exit;
/**
 * Plugin Name: (WCM) Activate/Deactivate/Uninstall - CLASS
 * Description: Пример плагина, демонстрирующий функции обратного вызова для активации/деактивации/удаления в классах/объектах.
 * Author:      Franz Josef Kaiser/wecodemore
 * Author URL:  http://unserkaiser.com
 * Plugin URL:  http://wordpress.stackexchange.com/questions/25910/uninstall-activate-deactivate-a-plugin-typical-features-how-to/25979#25979
 */

register_activation_hook(   __FILE__, array( 'WCM_Setup_Demo_Class', 'on_activation' ) );
register_deactivation_hook( __FILE__, array( 'WCM_Setup_Demo_Class', 'on_deactivation' ) );
register_uninstall_hook(    __FILE__, array( 'WCM_Setup_Demo_Class', 'on_uninstall' ) );

add_action( 'plugins_loaded', array( 'WCM_Setup_Demo_Class', 'init' ) );
class WCM_Setup_Demo_Class
{
    protected static $instance;

    public static function init()
    {
        is_null( self::$instance ) AND self::$instance = new self;
        return self::$instance;
    }

    public static function on_activation()
    {
        if ( ! current_user_can( 'activate_plugins' ) )
            return;
        $plugin = isset( $_REQUEST['plugin'] ) ? $_REQUEST['plugin'] : '';
        check_admin_referer( "activate-plugin_{$plugin}" );

        # Раскомментируйте следующую строку, чтобы увидеть функцию в действии
        # exit( var_dump( $_GET ) );
    }

    public static function on_deactivation()
    {
        if ( ! current_user_can( 'activate_plugins' ) )
            return;
        $plugin = isset( $_REQUEST['plugin'] ) ? $_REQUEST['plugin'] : '';
        check_admin_referer( "deactivate-plugin_{$plugin}" );

        # Раскомментируйте следующую строку, чтобы увидеть функцию в действии
        # exit( var_dump( $_GET ) );
    }

    public static function on_uninstall()
    {
        if ( ! current_user_can( 'activate_plugins' ) )
            return;
        check_admin_referer( 'bulk-plugins' );

        // Важно: Проверьте, что файл тот же,
        // который был зарегистрирован во время хука удаления.
        if ( __FILE__ != WP_UNINSTALL_PLUGIN )
            return;

        # Раскомментируйте следующую строку, чтобы увидеть функцию в действии
        # exit( var_dump( $_GET ) );
    }

    public function __construct()
    {
        # Инициализация плагина: Подключите ваши функции обратного вызова
    }
}

(C) Архитектура на основе классов/OOP с внешним объектом настройки

Этот сценарий предполагает, что у вас есть главный файл плагина и второй файл с именем setup.php в подкаталоге плагина с именем inc: ~/wp-content/plugins/your_plugin/inc/setup.php. Это будет работать даже если папка плагина находится вне стандартной структуры WP, если папка контента переименована или если ваш файл настройки имеет другое имя. Только папка inc должна иметь то же имя и расположение относительно корневой директории плагина.

Примечание: Вы можете просто взять три функции register_*_hook() и классы и вставить их в свой плагин.

Главный файл плагина:

<?php
defined( 'ABSPATH' ) OR exit;
/**
 * Plugin Name: (WCM) Activate/Deactivate/Uninstall - FILE/CLASS
 * Description: Пример плагина
 * Author:      Franz Josef Kaiser/wecodemore
 * Author URL:  http://unserkaiser.com
 * Plugin URL:  http://wordpress.stackexchange.com/questions/25910/uninstall-activate-deactivate-a-plugin-typical-features-how-to/25979#25979
 */

register_activation_hook(   __FILE__, array( 'WCM_Setup_Demo_File_Inc', 'on_activation' ) );
register_deactivation_hook( __FILE__, array( 'WCM_Setup_Demo_File_Inc', 'on_deactivation' ) );
register_uninstall_hook(    __FILE__, array( 'WCM_Setup_Demo_File_Inc', 'on_uninstall' ) );

add_action( 'plugins_loaded', array( 'WCM_Setup_Demo_File', 'init' ) );
class WCM_Setup_Demo_File
{
    protected static $instance;

    public static function init()
    {
        is_null( self::$instance ) AND self::$instance = new self;
        return self::$instance;
    }

    public function __construct()
    {
        add_action( current_filter(), array( $this, 'load_files' ), 30 );
    }

    public function load_files()
    {
        foreach ( glob( plugin_dir_path( __FILE__ ).'inc/*.php' ) as $file )
            include_once $file;
    }
}

Файл настройки:

<?php
defined( 'ABSPATH' ) OR exit;

class WCM_Setup_Demo_File_Inc
{
    public static function on_activation()
    {
        if ( ! current_user_can( 'activate_plugins' ) )
            return;
        $plugin = isset( $_REQUEST['plugin'] ) ? $_REQUEST['plugin'] : '';
        check_admin_referer( "activate-plugin_{$plugin}" );

        # Раскомментируйте следующую строку, чтобы увидеть функцию в действии
        # exit( var_dump( $_GET ) );
    }

    public static function on_deactivation()
    {
        if ( ! current_user_can( 'activate_plugins' ) )
            return;
        $plugin = isset( $_REQUEST['plugin'] ) ? $_REQUEST['plugin'] : '';
        check_admin_referer( "deactivate-plugin_{$plugin}" );

        # Раскомментируйте следующую строку, чтобы увидеть функцию в действии
        # exit( var_dump( $_GET ) );
    }

    public static function on_uninstall()
    {
        if ( ! current_user_can( 'activate_plugins' ) )
            return;
        check_admin_referer( 'bulk-plugins' );

        // Важно: Проверьте, что файл тот же,
        // который был зарегистрирован во время хука удаления.
        if ( __FILE__ != WP_UNINSTALL_PLUGIN )
            return;

        # Раскомментируйте следующую строку, чтобы увидеть функцию в действии
        # exit( var_dump( $_GET ) );
    }
}

(2) Обновления плагинов

Если вы пишете плагин, у которого есть собственная таблица в БД или опции, могут возникнуть ситуации, когда вам нужно изменить или обновить что-то.

К сожалению, пока нет возможности выполнить что-то при установке или обновлении плагина/темы. К счастью, есть обходной путь: подключите пользовательскую функцию к пользовательской опции (да, это некрасиво — но работает).

function prefix_upgrade_plugin() 
{
    $v = 'plugin_db_version';
    $update_option = null;
    // Обновление до версии 2
    if ( 2 !== get_option( $v ) ) 
    {
        if ( 2 < get_option( $v ) )
        {
            // Функция обратного вызова должна вернуть true при успехе
            $update_option = custom_upgrade_cb_fn_v3();

            // Обновляем опцию только в случае успеха
            if ( $update_option )
                update_option( $v, 2 );
        }
    }

    // Обновление до версии 3, выполняется сразу после обновления до версии 2
    if ( 3 !== get_option( $v ) ) 
    {
        // Повторно запускаем с начала, если предыдущее обновление не удалось
        if ( 2 < get_option( $v ) )
            return prefix_upgrade_plugin();

        if ( 3 < get_option( $v ) )
        {
            // Функция обратного вызова должна вернуть true при успехе
            $update_option = custom_upgrade_cb_fn_v3();

            // Обновляем опцию только в случае успеха
            if ( $update_option )
                update_option( $v, 3 );
        }
    }

    // Возвращаем результат функции обновления, чтобы можно было проверить успех/неудачу/ошибку
    if ( $update_option )
        return $update_option;

return false;
}
add_action('admin_init', 'prefix_upgrade_plugin' );

^{Источник}

Эта функция обновления не самый красивый/хорошо написанный пример, но, как уже говорилось: это пример, и техника работает хорошо. Я улучшу это в будущих обновлениях.