WordPress как на ладони
wordpress jino

register_activation_hook() WP 2.0

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

Эта функция является основой для добавления функции к хуку activate_(plugin) и создана для удобного его использования.

Когда плагин активируется, срабатывает хук activate_(plugin), где (plugin) заменяется названием поддиректорией плагина, которая считается названием плагина. Например, если плагин расположен: wp-content/plugins/sampleplugin/sample.php, то название хука будет: activate_sampleplugin/sample.php.

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

В момент срабатывания хука код плагина еще не работает, т.е. например, если ваш плагин подключает textdomain во время события plugins_loaded, то эта функция для текущего события не сработает...

Хуков нет.

Возвращает

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

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

register_activation_hook( $file, $function );
$file(строка) (обязательный)
Путь до PHP файла, в котором находится функция обратного вызова, указанная во втором параметре $callback. Обычно используется волшебная константа PHP __FILE__.
$function(строка/массив) (обязательный)
Название функции обратного вызова. Для классов используйте массив: array( $this, 'название_функции' );

Примеры

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

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

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

register_activation_hook( __FILE__, 'myplugin_activate' );

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

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

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

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

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

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

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

include_once dirname( __FILE__ ) . '/your_additional_file.php';
register_activation_hook( __FILE__, array( 'НАЗВАНИЕ_КЛАССА', 'on_activate_function' ) );

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

Если вы находитесь внутри __construct():

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

Заметки

register_activation_hook() не будет работать если его активировать в момент срабатывания хука plugins_loaded или init, или любого другого. Этот хук должен вызываться до их срабатывания, до того как плагин будет загружен или активирован.

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

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

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

  3. В функции хука нельзя выводить данные на экран (echo). Этим способом нельзя проверить, работает функция или нет. Можно использовать die() или exit().

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

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

/*
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!';
}

Как все работает

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

После редиректа срабатывают только два хука: activated_plugin и shutdown. Можно попробовать прицепить функцию к ним, но это не всегда уместно. Одно из решений этой проблемы, когда нужно что-либо сделать сразу после активации плагина, использовать add_option():

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

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

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

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

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

function myplugin_activate() {

  global $myvar;
  echo $myvar; // Переменная не равна 'что-то'!
}

register_activation_hook( __FILE__, 'myplugin_activate' );

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

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

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

function myplugin_activate() {

   global $myvar;
   echo $myvar; // переменная равна 'что-то'.
}
register_activation_hook( __FILE__, 'myplugin_activate' );

Код register activation hook: wp-includes/plugin.php WP 4.8.2

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

Cвязанные функции

Из раздела: Плагины, хуки

register_activation_hook Комментариев нет

Здравствуйте, !

Ваш комментарий