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

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

register_activation_hook() повинна викликатися з основного файлу плагіна, з того, де розташована директива Plugin Name: ...і не повинна викликатися з будь-якого хука, на кшталт plugins_loadedабо init.
Функція хука повинна бути в тому ж файлі, що і хук або підключатися заздалегідь з іншого файлу.
Функція хука не працює на екран (echo). Тому що відбувається редирект і echo ви не побачите. Але можна використовувати die() .
Глобальні змінні (якщо вони є) повинні бути явно визначені, щоб був доступ до них з функції хука.

Нотатка про область змінних

При активації плагіна, головний файл плагіна підключається над глобальної області, а всередині функції 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 .

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

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

register_activation_hook( __FILE__, 'my_plugin_activate' );

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

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

Якщо плагін використовує PHP клас, код активації додається так:

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

class My_Plugin {
	 static function install() {
			// Не створюйте тут жодного висновку...
	 }
}

#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, 'YOUR_METHOD_NAME' ) );

#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' );

#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 6.0.2}

wp-includes/plugin.php

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