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. Функция должна вызываться напрямую из главного файла плагина.

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

  1. register_activation_hook() должна вызываться из основного файла плагина, из того где расположена директива Plugin Name: ... и не должна вызываться из какого-либо хука, вроде plugins_loaded или init.

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

  3. В функции хука не работает вывод на экран (echo). Потому что происходит редирект и echo вы не увидите. Но можно использовать die().

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

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

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

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

$myvar = 'что-то';

register_activation_hook( __FILE__, 'myplugin_activate' );

function myplugin_activate(){
	global $myvar;
	echo $myvar;   // Переменная не равна 'что-то'
}

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

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

register_activation_hook( __FILE__, 'myplugin_activate' );

function myplugin_activate(){
	global $myvar;
	echo $myvar;   //> что-то
}

Хуков нет.

Возвращает

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

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

register_activation_hook( $file, $function );
$file(строка) (обязательный)
Путь до главного php файла плагина включая название самого плагина. Обычно используется волшебная константа PHP __FILE__.
$function(строка/массив/лямбда) (обязательный)

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

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

Примеры

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

0

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

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

register_activation_hook( __FILE__, 'my_plugin_activate' );

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

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

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

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

class My_Plugin {
	 static function install() {
			// Не создавайте здесь никакого вывода ...
	 }
}
0

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

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

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

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

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

register_activation_hook( __FILE__, array( $this, 'YOUR_METHOD_NAME' ) );
0

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

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

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

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

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

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

  // Здесь код активации ...
}
register_activation_hook( __FILE__, 'my_plugin_activate' );

function load_plugin() {

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

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

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

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

#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() WP 6.4.3

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