REGISTER_ACTIVATION_HOOK() │ WP 2.0.0

Эта функция устанавливает хуки активации для плагина.

Что такое хук активации?

Когда плагин активируется, вызывается действие с хуком 'activate_PLUGINNAME'. Здесь PLUGINNAME заменяется на имя плагина, включая путь к нему. Например, если плагин находится в папке wp-content/plugins/sampleplugin/sample.php, то имя этого хука будет 'activate_sampleplugin/sample.php'.

Если плагин состоит из одного файла и находится по адресу wp-content/plugins/sample.php, то имя этого хука будет 'activate_sample.php'.

Что возвращает функция?

Функция не возвращает ничего (null).

Как использовать функцию

Чтобы вызвать функцию, используйте следующий синтаксис:

register_activation_hook( $file, $callback );

Параметры:

• $file (string) (обязательный) — имя файла плагина, включая путь к нему.
• $callback (callable) (обязательный) — функция, которая будет привязана к действию 'activate_PLUGIN'.

Примеры использования

Пример 1: Запуск функции PHP при активации плагина

Допустим, у нас есть функция my_plugin_activate() в основном файле плагина: wp-content/plugins/myplugin/myplugin.php. Используйте следующий код, чтобы запустить эту функцию во время активации плагина:

register_activation_hook( __FILE__, 'my_plugin_activate' );

function my_plugin_activate( $network_wide ) {
    // Код активации...
}

Обратите внимание: register_activation_hook() не должен вызывать хуки из других функций, так как они будут вызваны до загрузки или активации плагина.

Пример 2: Запуск метода класса

Если ваш плагин использует класс PHP, код активации добавляется следующим образом:

register_activation_hook( __FILE__, [ My_Plugin::class, 'install' ] );

class My_Plugin {
    public static function install() {
        // Не используйте вывод, например echo...
    }
}

Пример 3: Запуск метода класса из отдельного файла

Если класс, который содержит функцию активации, находится в другом файле, зарегистрируйте функцию активации следующим образом:

include_once __DIR__ . '/class-My_Plugin.php';

register_activation_hook( __FILE__, array( 'My_Plugin', 'on_activate_function' ) );

Пример 4: Запуск метода класса из самого класса

Если вы находитесь внутри конструктора, не забывайте, что FILE должен ссылаться на основной файл плагина:

class Activate_Plugin {

    public function __construct(){
        register_activation_hook( PLUGIN_MAIN_FILE_PATH, array( $this, 'my_method' ) );
    }
}

Пример 5: Выполнение действий сразу после активации плагина

После активации плагина срабатывают только два хуки: activated_plugin и shutdown. Если вам нужно что-то сделать сразу после активации плагина, вы можете привязать функцию к ним. Если это решение не подходит, можно использовать варианты WP: сохранить данные в опции и затем проверить, существует ли эта опция:

register_activation_hook( __FILE__, 'my_plugin_activate' );

add_action( 'admin_init', 'load_plugin' );

function my_plugin_activate( $network_wide ) {
    // Добавьте опцию для дальнейших действий, если она существует.
    add_option( 'Activated_Plugin', 'Plugin-Slug' );

    // Код активации...
}

function load_plugin() {
    if ( is_admin() && get_option( 'Activated_Plugin' ) == 'Plugin-Slug' ) {
        // Удалить добавленную опцию, чтобы она больше не срабатывала.
        delete_option( 'Activated_Plugin' );

        // Сделать что-то один раз после активации плагина.
    }
}

Пример 6: Еще одна демонстрация использования функции

Небольшой плагин, демонстрирующий, как использовать эту функцию:

/*
Plugin Name: A Test
Description: A Test
*/

require_once dirname(__FILE__) . '/my_other_file.php';

register_activation_hook( __FILE__, 'test_activated' );

global $some_var;    
$some_var = 'hey';

// Функция активации
function test_activated( $network_wide ){
   global $some_var;

   my_other_function(); // Здесь $some_var будет равно 'hey'

   echo 'test_activated вызвана!';
}

Пример 7: Вызов внутри пространства имен

Если вы вызываете это из пространства имен, синтаксис будет следующим:

register_activation_hook( __FILE__, __NAMESPACE__ . 'my_activate_callback' );

Изменения

Функция была введена в версии 2.0.0.

Как устроена функция

function register_activation_hook( $file, $callback ) {
    $file = plugin_basename( $file );
    add_action( 'activate_' . $file, $callback );
}

Теперь вы знаете, как использовать хук активации для плагинов в WordPress! Удачи в разработке вашего плагина!