register_activation_hook() │ WP 2.0.0

Registers a function that will be triggered at the time of plugin activation.

This function attaches the specified callback function to the hook activate_(plugin) and is a wrapper for this hook. (plugin) is replaced with the name of the relative path to the main plugin file. For example, if the main plugin file is: wp-content/plugins/sampleplugin/sample.php, then the hook name will be: activate_sampleplugin/sample.php.

Since version 3.1, the hook is triggered only during plugin activation and does not trigger during automatic plugin updates.

Usage Rules

The function will not work if called at the time of triggering any hook, such as plugins_loaded, init. The function must be called directly from the main plugin file.

Activation rules:

The function must be called from the main plugin file, where the directive Plugin Name: ... is located, and must not be called from any hook, such as plugins_loaded or init.
The attached callback function must be available at the time of the hook's execution. That is, it needs to be included in the global scope (for example, include the PHP file where register_activation_hook() is called). Or if it is a class method, the class or its instance must be available for its method to execute at the time of the hook's execution.
Output to the screen (echo) does not work in the hook function. Because a redirect occurs and you will not see the echo. But you can use die() or log the result via error_log() or in some other way.
Global variables (if any) must be explicitly defined to be accessible from the hook function.

Note on Variable Scope

When activating a plugin, the main plugin file is included not in the global scope but inside the function activate_plugin(). Therefore, variables that are considered global in the normal operation of the plugin will not be so.

Thus, the callback function used in register_activation_hook() may not see global variables, even if you declared them as global inside that function. For example:

$myvar = 'Hello';

register_activation_hook( __FILE__, 'myplugin_activate' );

function myplugin_activate(){
	global $myvar;
	echo $myvar;   // value is not 'Hello'
}

Due to this peculiarity, all global variables must be defined as global, even if the variable is specified in the body of the plugin. Example of correct usage:

global $myvar; // explicitly stating that this is a global variable
$myvar = 'Hello';

register_activation_hook( __FILE__, 'myplugin_activate' );

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

No Hooks.

Returns

null. Does not return anything.

Usage

register_activation_hook( $file, $callback );

$file(string) (required)

Path to the main PHP file of the plugin including the name of the plugin itself. Usually uses the PHP magic constant __FILE__.

$function(string/array/lambda) (required)

Name of the callback function. For classes, use an array: array( $this, 'function_name' );.

The function will receive a boolean variable $network_wide - whether the plugin is activated for the entire network of sites in a multisite.

Examples

Good examples of using activation, deactivation, and deletion of a plugin within a class (OOP) can be found in the examples of register_deactivation_hook.

#1 Running PHP function when the plugin is activated

Suppose we have a function my_plugin_activate() in the main plugin file: wp-content/plugins/myplugin/myplugin.php, then use this code to run this function during plugin activation:

register_activation_hook( __FILE__, 'my_plugin_activate' );

function my_plugin_activate( $network_wide ) {
	// Activation code ...
}

Note that register_activation_hook() must NOT be registered from within another hook as these will have all been called before the plugin is loaded or activated.

BAD NOT working example:

// NOT working example:
add_action( 'plugins_loaded', 'pluginInit' );

function pluginInit() {

	require_once dirname(__FILE__) . '/includes/Activator.php';

	register_activation_hook( __FILE__, 'Activator', 'activate' ) );
}

#2 Running a class method

If the plugin uses a PHP class, the activation code is added as follows:

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

class My_Plugin {
	public static function install() {
		// Don't use any output here, for example echo ...
	}
}

#3 Running a class method from a separate file

If the class that contains the activation function is in a separate file, register the activation function as follows:

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

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

#4 Running a class method from the class itself

If you are inside __construct(). Important, __FILE__ must "look" at the main plugin file:

class Activate_Plugin {

	public function __construct(){

		register_activation_hook( PLUGIN_MAIN_FILE_PATH, array( $this, 'my_method' ) );
	}

}

#5 Doing something right after the plug-in is activated

After activating the plugin, only two hooks are triggered: activated_plugin and shutdown.

When you need to do something immediately after activating a plugin, you can pin a function to them.

When this solution is not suitable, you can use WP options: save data to an option and then check if the option is there, and do something if the option is there:

// Main plugin file.

...

register_activation_hook( __FILE__, 'my_plugin_activate' );

add_action( 'admin_init', 'load_plugin' );

function my_plugin_activate( $network_wide ) {

  // add an option to do something later, if there is one.
  add_option( 'Activated_Plugin', 'Plugin-Slug' );

  // Here the activation code ...
}

function load_plugin() {

	if ( is_admin() && get_option( 'Activated_Plugin' ) == 'Plugin-Slug' ) {
		// delete the added option so that it is no longer triggered
		// and do what needs to be done...
		delete_option( 'Activated_Plugin' );

		// Do something once, after activating the plugin
		// For example: add_action('init', 'my_init_function' );
	}

}

Another option to do something during the activation of the plugin is to create your event this way:

register_activation_hook( __FILE__, 'my_plugin_activate' );

function my_plugin_activate(){

	// Set your hook, so that it can be hooked from the plugin files themselves
	do_action( 'my_plugin_activate' );
}

#6 Another demonstration of using the function

A small plugin that demonstrates how the function should be used:

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

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

/* 
This code will not work. The activation hook must be called from the main file.
register_activation_hook ( dirname(__FILE__) . '/my_other_file.php', 'my_other_function');
*/

// This is a working code.
register_activation_hook( __FILE__, 'test_activated' );

/* 
This is the correct way to declare and access global variables.
Global variables must be declared clearly.
Without this, you won't have access to them.
*/
global $some_var;    
$some_var = 'hey';

// Activation function
function test_activated( $network_wide ){

   // here $some_var will not equal hey
   global $some_var;

   // And here $some_var will be equal to hey
   // This function is defined in the 'my_other_file.php' file
   my_other_function();

   /* 
   This option will not work.

   If you want to write the logs to a temporary file, use fopen/fwrite.

   If you want to check if the activation hook works,
   use exit() inside the hook function.
   */
   echo 'test_activated called!';
}

#7 If calling this within a namespace:

register_activation_hook( __FILE__, __NAMESPACE__ . '\my_activate_callback' );

Changelog

Since 2.0.0

Introduced.

`register_activation_hook() register activation hook` code ^{WP 6.9}

wp-includes/plugin.php

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