register_activation_hook()WP 2.0.0

Set the activation hook for a plugin.

When a plugin is activated, the action 'activate_PLUGINNAME' hook is called. In the name of this hook, PLUGINNAME is replaced with the name of the plugin, including the optional subdirectory. For example, when the plugin is located in wp-content/plugins/sampleplugin/sample.php, then the name of this hook will become 'activate_sampleplugin/sample.php'.

When the plugin consists of only one file and is (as by default) located at wp-content/plugins/sample.php the name of this hook will be 'activate_sample.php'.

No Hooks.

Return

null. Nothing (null).

Usage

register_activation_hook( $file, $callback );
$file(string) (required)
The filename of the plugin including the path.
$callback(callable) (required)
The function hooked to the 'activate_PLUGIN' action.

Examples

2

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

#2 Running a class method

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

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

class My_Plugin {

	 public static function install( $network_wide ) {
		// Don't create any output here ...
	 }
}
0

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

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

}
0

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

#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!';
}
0

#7 If calling this within a namespace:

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

Changelog

Since 2.0.0 Introduced.

register_activation_hook() code WP 6.4.3

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