register_activation_hook() │ WP 2.0.0

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

Эта функция прикрепляет указанную callback функцию к хуку activate_(plugin) и является оберткой для этого хука. (plugin) тут заменяется названием относительного пути до главного файла плагина. Например, если главный файл плагина: wp-content/plugins/sampleplugin/sample.php, тогда название хука будет: activate_sampleplugin/sample.php.

С версии 3.1. хук срабатывает только во время активации плагина, и не срабатывает во время автоматического обновления плагина.

Читайте подробнее:

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

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

Правила активации:

Функция должна вызываться из основного файла плагина, из того где расположена директива Plugin Name: ... и не должна вызываться из какого-либо хука, вроде plugins_loaded или init.
Прикрепляемая коллбэк функция должна быть доступна в момент срабатывания хука. Т.е. её нужно подключать в глобальную область видимости (например иклудить php файл там же где вызывается register_activation_hook()). Или если это метод класса, класс или его экзепляр должен быть доступен, чтобы его метод отработал в помент срабатывания хука.
В функции хука не работает вывод на экран (echo). Потому что происходит редирект и echo вы не увидите. Но можно использовать die() или логировать результат через error_log() или как-то еще.
Глобальные переменные (если они есть) должны быть определены явно, чтобы был доступ к ним из функции хука.

Заметка про область переменных

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

Так, коллбэк-функция, которая используется в register_activation_hook() может не видеть глобальные переменные, даже если вы объявили их как глобальные внутри этой функции. Например:

$myvar = 'Hello';

register_activation_hook( __FILE__, 'myplugin_activate' );

function myplugin_activate( $network_wide ){
	global $myvar;
	echo $myvar;   // значение не равно 'Hello'
}

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

global $myvar; // указываем явно что это глобальная переменная
$myvar = 'Hello';

register_activation_hook( __FILE__, 'myplugin_activate' );

function myplugin_activate( $network_wide ){
	global $myvar;
	echo $myvar;   //> Hello
}

Хуков нет.

Возвращает

null. Ничего не возвращает.

Использование

register_activation_hook( $file, $callback );

$file(строка) (обязательный)

Путь до главного php файла плагина включая название самого плагина. Обычно используется волшебная константа PHP __FILE__.

$function(строка/массив/лямбда) (обязательный)

Название функции обратного вызова. Для классов используйте массив: array( $this, 'название_функции' );.

Функция получит логическую переменную:

$network_wide - активируется ли плагин для всей сети сайтов, при мультисайте.

Примеры

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

#1 Запуск функции при активации плагина

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

register_activation_hook( __FILE__, 'my_plugin_activate' );

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

#2 Запуск метода класса

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

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

class My_Plugin {
	public static function install( $network_wide ) {
		// Не делайте здесь вывода на экран...

		if ( $network_wide ) {
			// Активировали для всей сети.
		} else {
			// Активировали только для текущего сайта.
		}
	}
}

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

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

include_once __DIR__ . '/class-My_Plugin.php';
register_activation_hook( __FILE__, array( 'My_Plugin', 'on_activate_function' ) );

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

Если вы находитесь внутри __construct(). Важно, __FILE__ должен «смотреть» на главный файл плагина:

register_activation_hook( __FILE__, array( $this, 'my_method_name' ) );

#5 Делаем что-либо сразу после активации плагина

После активации плагина срабатывают только два хука: activated_plugin и shutdown.

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

Когда такое решение не подходит, можно использовать опции WP: сохранять данные в опцию и затем проверять наличие опции, и делать что-либо, если опция есть:

// Основной файл плагина.
...

register_activation_hook( __FILE__, 'my_plugin_activate' );
function my_plugin_activate( $network_wide ) {
  // добавляем опцию, чтобы потом если она есть сделать что-либо.
  add_option( 'Activated_Plugin', 'Plugin-Slug' );

  // Здесь код активации ...
}

add_action( 'admin_init', 'load_plugin' );
function load_plugin() {

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

		// Делаем что-либо единожды, после активации плагина
		// Например: add_action( 'init', 'my_init_function' );
	}
}

Другой вариант сделать что-то во время активации плагина - это создать свое событие так:

register_activation_hook( __FILE__, 'my_plugin_activate' );
function my_plugin_activate( $network_wide ){
	// Устанавливаем свой хук, чтобы к нему можно было прицепиться из файлов самого плагина
	do_action( 'my_plugin_activate' );
}

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

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

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

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

/* 
Этот код не будет работать. Хук активации должен вызываться из основного файла.
register_activation_hook ( dirname(__FILE__) . '/my_other_file.php', 'my_other_function');
*/

// Это рабочий код.
register_activation_hook( __FILE__, 'test_activated' );

/* 
Это правильный вариант объявления и доступа к глобальным переменным.
Глобальные переменные должны объявляться четко. 
Без этого у вас не будет доступа к ним.
*/
global $some_var;    
$some_var = 'hey';

// Функция активации
function test_activated(){

   // тут $some_var не будет равно hey
   global $some_var;

   // А тут $some_var будет равно hey
   // Эта функция определена в файле 'my_other_file.php'
   my_other_function();

   /* 
   Этот вариант не будет работать. 

   Если нужно записать логи во временный файл, используйте fopen/fwrite.

   Если вы хотите проверить, работает ли хук активации, 
   используйте exit() внутри функции хука.
   */
   echo 'test_activated called!';
}

Список изменений

С версии 2.0.0

Введена.

Код `register_activation_hook() register activation hook` ^{WP 7.0}

wp-includes/plugin.php

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