register_activation_hook()

💡 云策文档标注

概述

register_activation_hook() 用于为插件设置激活钩子，当插件激活时触发 'activate_PLUGINNAME' 动作。该函数接受插件文件路径和回调函数作为参数，内部通过 add_action() 实现钩子注册。

关键要点

钩子名称基于插件文件路径生成，例如 'activate_sampleplugin/sample.php'。
参数 $file 必须是插件主文件的路径，$callback 是激活时要执行的函数。
激活钩子不能在 'plugins_loaded' 或 'init' 等钩子内注册，因为这些钩子在插件激活前已触发。
激活后页面会立即重定向，因此无法直接使用 add_action() 或 add_filter()，但可通过 add_option() 或 do_action() 间接处理。
全局变量在激活函数中可能无法访问，需在函数内外显式声明 global。
回调函数可接受一个布尔参数 $network_wide，用于判断插件是否在网络范围内激活。
对于单例类或命名空间，需使用数组或命名空间前缀指定回调。
激活钩子适用于执行一次性任务，如创建数据库表或刷新重写规则。

代码示例

register_activation_hook( __FILE__, 'my_plugin_activate' );
function my_plugin_activate( $network_wide ) {
    if ( $network_wide ) {
        // 网络激活处理
    } else {
        // 单站点激活处理
    }
    // 激活代码，如创建选项或数据库表
}

注意事项

避免在 Multisite 中滥用激活钩子，某些情况下使用基于 admin_init 的升级例程更合适。
钩子名称中的斜杠和点可能被代码规范检查工具拒绝，需注意手动调用时的兼容性。
激活钩子应注册在插件主文件中，但回调函数可以定义在其他文件中。

📄 原文内容

Set the activation hook for a plugin.

Description

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’.

Parameters

$filestringrequired: The filename of the plugin including the path.
$callbackcallablerequired: The function hooked to the 'activate_PLUGIN' action.

More Information

For more information on what will be passed to your $callback, please see the activate_{$plugin} hook.

Related discussion with another sample of working code: https://wordpress.org/support/topic/312342

Registering the hook inside the ‘plugins_loaded’ hook will not work. You can’t call register_activation_hook() inside a function hooked to the 'plugins_loaded' or 'init' hooks (or any other hook). These hooks are called before the plugin is loaded or activated.

When a plugin is activated, all active plugins are loaded, then the plugin is activated. The plugin’s activation hook is run and then the page is immediately redirected

Process Flow

If you are interested in doing something just after a plugin has been activated it is important to note that the hook process performs an instant redirect after it fires. So it is impossible to use add_action() or add_filter() type calls until the redirect has occurred (e.g., only two hooks are fired after the plugin’s activation hook: 'activated_plugin' and 'shutdown'). A quick workaround to this quirk is to use add_option() like so:

/* Main Plugin File */
...
function my_plugin_activate() {

  add_option( 'Activated_Plugin', 'Plugin-Slug' );

  /* activation code here */
}
register_activation_hook( __FILE__, 'my_plugin_activate' );

function load_plugin() {

    if ( is_admin() && get_option( 'Activated_Plugin' ) == 'Plugin-Slug' ) {

        delete_option( 'Activated_Plugin' );

        /* do stuff once right after activation */
        // example: add_action( 'init', 'my_init_function' );
    }
}
add_action( 'admin_init', 'load_plugin' );

You can check out the full post @ http://stackoverflow.com/questions/7738953/is-there-a-way-to-determine-if-a-wordpress-plugin-is-just-installed/13927297#13927297.

However, it is possible to use do_action(), like this:

function my_plugin_activate() {

     do_action( 'my_plugin_activate' );
}
register_activation_hook( __FILE__, 'my_plugin_activate' );

Included plugin files and even other plugins will be able to hook into this action.

A Note on Variable Scope

If you’re using global variables, you may find that the function you pass to register_activation_hook() does not have access to global variables at the point when it is called, even though you state their global scope within the function like this:

$myvar = 'whatever';

function myplugin_activate() {

  global $myvar;
  echo $myvar; // this will NOT be 'whatever'!
}

register_activation_hook( __FILE__, 'myplugin_activate' );

This is because on that very first include, your plugin is NOT included within the global scope. It’s included in the activate_plugin() function, and so its “main body” is not automatically in the global scope.

This is why you should always be explicit. If you want a variable to be global, then you need to declare it as such, and that means anywhere and everywhere you use it. If you use it in the main body of the plugin, then you need to declare it global there too.

When activation occurs, your plugin is included from another function and then your myplugin_activate() is called from within that function (specifically, within the activate_plugin() function) at the point where your plugin is activated. The main body variables are therefore in the scope of the activate_plugin() function and are not global, unless you explicitly declare their global scope:

global $myvar;
$myvar = 'whatever';

function myplugin_activate() {

   global $myvar;
   echo $myvar; // this will be 'whatever'
}
register_activation_hook( __FILE__, 'myplugin_activate' );

More information on this is available here: https://wordpress.org/support/topic/201309

Discussions – External Resources

A good example for a basic activation/deactivation/uninstall class by “kaiser” can be found here on WPSE: http://wordpress.stackexchange.com/questions/25910/uninstall-a-plugin-method-typical-features-how-to/25979#25979

Source

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

View all references View on Trac View on GitHub

Uses	Description
plugin_basename()`wp-includes/plugin.php`	Gets the basename of a plugin.
add_action()`wp-includes/plugin.php`	Adds a callback function to an action hook.

Changelog

Version	Description
2.0.0	Introduced.

User Contributed Notes

Skip to note 14 content

orionrush

10 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 11You must log in to vote on the helpfulness of this note
Note that register_activation_hook must not be registered from within another hook for example ‘plugins_loaded’ or ‘init’ as these will have all been called before the plugin is loaded or activated.

This will NOT work:
```
function pluginInit() {
    require_once dirname(__FILE__) . '/includes/Activator.php';
    register_activation_hook( __FILE__, 'Activator', 'activate' ) );
}
add_action( 'plugins_loaded', 'pluginInit' );
```
Log in to add feedback
Skip to note 15 content

Codex

10 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 9You must log in to vote on the helpfulness of this note
Singleton class pattern

If your plugin uses the singleton class pattern, add the activation hook like so:
```
class MyPlugin {
     static function install() {
            // do not generate any output here
     }
}
register_activation_hook( __FILE__, array( 'MyPlugin', 'install' ) );
```
If the class that holds your activation function/method is in some additional file, register your activation function like this:
```
include_once dirname( __FILE__ ) . '/your_additional_file.php';
register_activation_hook( __FILE__, array( 'YourAdditionalClass', 'on_activate_function' ) );
```
Or, because the activation hook requires a static function, if you’re inside of a __construct():
```
register_activation_hook( __FILE__, array( 'MyPlugin', 'YOUR_METHOD_NAME' ) );
```
Log in to add feedback
Skip to note 16 content

ics1010

9 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 8You must log in to vote on the helpfulness of this note

There’s a comment here that could make this confusing by giving incorrect information. The code does NOT have to be in the main file, unless you’re doing something like a single file plugin. The thing to know is that the first argument is the name required to get your code to fire, not what file the code is in. Example:
 Main plugin file: plugin/myplugin/myplugin.php include 'some_class.php'; $obj = new other_class(); Other plugin file: plugin/myplugin/some_class.php class some_class { __constructor() { register_activation_hook(__DIR__.'/myplugin.php',array($this,'activate'); } public function activate() { ... } } 

Log in to add feedback
Skip to note 17 content

tjkwebdev

9 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 3You must log in to vote on the helpfulness of this note
If calling this within a namespace:
```
register_activation_hook( __FILE__, __NAMESPACE__ . 'my_activate_callback' );
```
Source: http://stackoverflow.com/questions/37863766/wordpress-not-recognizing-function-during-plugin-activation
Log in to add feedback
Skip to note 18 content

mallorydxw-old

9 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note

According to @nacin (a lead developer for WordPress), you shouldn’t use activation hooks (especially on multisite). You should do this instead:

“It’s far better to use an upgrade routine fired on admin_init, and handle that per-site, basing it on a stored option.”

Source: https://core.trac.wordpress.org/ticket/14170#comment:68
- This issue with WP Multisite are solved and today don’t have any problem.
  
  Eduardo Villão 4 years ago
- Just because it is a god’s statement, does not mean it is correct. > It’s far better to use an upgrade routine fired on admin_init, and handle that per-site, basing it on a stored option. 1. No, it is not far better. It is far worse! `admin_init` is fired _every time admin is initiated_. An activation hook, is fired _every time the plugin is activated_. This is an entirely different thing! 2. That problem surged on Multisite, and it is actually due to wrong handling of plugin activation hook by core (IMO) and this is fixed with some user contributed plugin: https://core.trac.wordpress.org/ticket/14170#comment:21 In other words, no, it is not “better” to not use the activation hooks. They are there for reasons and they are there because they are the right thing to use for when you want to run code _on activation of the plugin_, or in other words, _just once, and with it, preserve performance_
  
  Anonymous User 3 years ago
Log in to add feedback

Skip to note 19 content

Koen Reus

6 years ago

The hooked function has one boolean argument, $network_wide which indicates if the plugin is network activated.

register_activation_hook(__FILE__, 'my_plugin_activate');
function my_plugin_activate($network_wide){
	if($network_wide){ //Plugin is network activated
		$site_ids = get_sites(array('fields' => 'ids'));
	    foreach($site_ids as $site_id){
			//Perform something on all sites within the network
      		switch_to_blog($site_id);
      		my_plugin_install_site();
      		restore_current_blog();
    	}
		return;
	}

	my_plugin_install_site();

}

function my_plugin_install_site(){
	//Do something
}

@Beda True, admin_init fires on every admin page load, but if you follow Nacin’s recommendation and condition the callback on a stored option, then the cost is near-zero.

crstauf 3 years ago

Skip to note 20 content

Mehdi Soltani

6 years ago

Sending arguments with callable function

Imagine that you have OOP structure for your plugin and need to observe SOLID principle inside it.
For this reason, you need to Dependency Injection with callable function inside your register_activation_hook function.
Sample code is like in the following:

Note

: I used both way to show calling callable function with argument and without it in activation and deactivation hooks to bold using each of them. Usage of callable function with argument is in register_activation_hook.

https://github.com/msn60/oop-wordpress-plugin-boilerplate</a>
 * @since             1.0.0
 * @package           Plugin_Name_Name_Space
 *
 * @wordpress-plugin
 * Plugin Name:       OOP WordPress Plugin Boilerplate
 * Plugin URI:        <a href="https://github.com/msn60/oop-wordpress-pluging-boilerplate-light-version" rel="nofollow ugc">https://github.com/msn60/oop-wordpress-pluging-boilerplate-light-version</a>
 * Description:       Description for OOP Plugin
 * Version:           1.0.2
 * Author:            Mehdi Soltani <soltani.n.mehdi@gmail.com>
 * Author URI:        <a href="https://wpwebmaster.ir" rel="nofollow ugc">https://wpwebmaster.ir</a>
 * License:           GPL-2.0+
 * License URI:       <a href="http://www.gnu.org/licenses/gpl-2.0.txt" rel="nofollow ugc">http://www.gnu.org/licenses/gpl-2.0.txt</a>
 */

/*
 * Define your namespaces here by use keyword
 * */

use Plugin_Name_Name_SpaceIncludesInit{
 Constant, Activator
};
use Plugin_Name_Name_SpaceIncludesConfigInitial_Value;
use Plugin_Name_Name_SpaceIncludesUninstall{
	Deactivator, Uninstall
};

/**
 * If this file is called directly, then abort execution.
 */
if ( ! defined( 'ABSPATH' ) ) {
	exit;
}


/**
 * Class Plugin_Name_Plugin
 *
 * This class is primary file of plugin which is used from
 * singletone design pattern.
 *
 * @package    Plugin_Name_Name_Space
 * @author     Your_Name <youremail@nomail.com>
 * @see        Plugin_Name_Name_SpaceIncludesInitCore Class
 * @see        Plugin_Name_Name_SpaceIncludesInitConstant Class
 * @see        Plugin_Name_Name_SpaceIncludesInitActivator Class
 * @see        Plugin_Name_Name_SpaceIncludesUninstallDeactivator Class
 * @see        Plugin_Name_Name_SpaceIncludesUninstallUninstall Class
 */
final class Plugin_Name_Plugin {
	/**
	 * Instance property of Plugin_Name_Plugin Class.
	 * This is a property in your plugin primary class. You will use to create
	 * one object from Plugin_Name_Plugin class in whole of program execution.
	 *
	 * @access private
	 * @var    Plugin_Name_Plugin $instance create only one instance from plugin primary class
	 * @static
	 */
	private static $instance;
	/**
	 * @var Initial_Value $initial_values An object  to keep all of initial values for theme
	 */
	protected $initial_values;


	/**
	 * Plugin_Name_Plugin constructor.
	 * It defines related constant, include autoloader class, register activation hook,
	 * deactivation hook and uninstall hook and call Core class to run dependencies for plugin
	 *
	 * @access private
	 */
	public function __construct() {
		/*Define Autoloader class for plugin*/
		$autoloader_path = 'includes/class-autoloader.php';
		/**
		 * Include autoloader class to load all of classes inside this plugin
		 */
		require_once trailingslashit( plugin_dir_path( __FILE__ ) ) . $autoloader_path;
		/*Define required constant for plugin*/
		Constant::define_constant();

		/**
		 * Register activation hook.
		 * Register activation hook for this plugin by invoking activate
		 * in Plugin_Name_Plugin class.
		 *
		 * @param string   $file     path to the plugin file.
		 * @param callback $function The function to be run when the plugin is activated.
		 */
		register_activation_hook(
			__FILE__,
			function () {
				$this->activate(
					new Activator( intval( get_option( 'last_your_plugin_name_dbs_version' ) ) )
				);
			}
		);
		/**
		 * Register deactivation hook.
		 * Register deactivation hook for this plugin by invoking deactivate
		 * in Plugin_Name_Plugin class.
		 *
		 * @param string   $file     path to the plugin file.
		 * @param callback $function The function to be run when the plugin is deactivated.
		 */
		register_deactivation_hook(
			__FILE__,
			array( $this, 'deactivate' )
		);
	}

	/**
	 * Call activate method.
	 * This function calls activate method from Activator class.
	 * You can use from this method to run every thing you need when plugin is activated.
	 *
	 * @access public
	 * @since  1.0.0
	 * @see    Plugin_Name_Name_SpaceIncludesInitActivator Class
	 */
	public function activate( Activator $activator_object ) {
		global $wpdb;
		$activator_object->activate(
			true,
			new Table( $wpdb, PLUGIN_NAME_DB_VERSION, get_option( 'has_table_name' ) )
		);
	}

	/**
	 * Create an instance from Plugin_Name_Plugin class.
	 *
	 * @access public
	 * @since  1.0.0
	 * @return Plugin_Name_Plugin
	 */
	public static function instance() {
		if ( is_null( ( self::$instance ) ) ) {
			self::$instance = new self();
		}

		return self::$instance;
	}
	

	/**
	 * Load Core plugin class.
	 *
	 * @access public
	 * @since  1.0.0
	 */
	public function run_plugin_name_plugin() {
		// TODO: Do you codes here to run the plugin
	}

	/**
	 * Call deactivate method.
	 * This function calls deactivate method from Dectivator class.
	 * You can use from this method to run every thing you need when plugin is deactivated.
	 *
	 * @access public
	 * @since  1.0.0
	 */
	public function deactivate() {
		Deactivator::deactivate();
	}
}


$plugin_name_plugin_object = Plugin_Name_Plugin::instance();
$plugin_name_plugin_object->run_plugin_name_plugin();

Skip to note 21 content

Rajan Karmaker

5 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
You can flush permalink if you have custom rewrite rules in your plugin
```
register_activation_hook( __FILE__, 'wpdocs_myplugin_activate' );

function wpdocs_myplugin_activate() {
	flush_rewrite_rules();
}
```
Log in to add feedback
Skip to note 22 content

Alvaro Torres

4 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

Really useful when, for example, when we need to create a DB table for our plugin functionalities:
 function create_ourtable(){ global $wpdb; $prefix = $wpdb->prefix; $form_db = $prefix . "ourtable"; //Check if table exists. In case it's false we create it if($wpdb->get_var("SHOW TABLES LIKE '$form_db'") !== $form_db){ $sql = "CREATE TABLE $form_db(id mediumint unsigned not null primary key auto_increment, dates timestamp, names varchar(500), wp_user mediumint unsigned)"; require_once(ABSPATH . 'wp-admin/includes/upgrade.php'); dbDelta($sql); } 

Log in to add feedback
Skip to note 23 content

NateWr

10 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: -1You must log in to vote on the helpfulness of this note

If you’re looking for a similar hook that fires when a theme is activated, see after_switch_theme.

Log in to add feedback
Skip to note 24 content

samwilson

9 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: -1You must log in to vote on the helpfulness of this note

Note that the WordPress code sniffer rules will reject the hook name that is constructed by this function, if you ever have to call the hook manually (for example, from a test). The WordPress.NamingConventions.ValidHookName.UseUnderscores rule rejects slashes and dots in hook names.

Log in to add feedback
Skip to note 25 content

Giulio Daprela

10 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: -3You must log in to vote on the helpfulness of this note
Please note that register_activation_hook() must be called from the main plugin file – the one that has “Plugin Name: …” directive.
This code added in the main plugin file will work:
```
require_once ( dirname( __FILE__ ) . '/includes/class-my-class.php' );

register_activation_hook( __FILE__, array ( $my_class, 'function_to_call') );
```
However, if you try to add register_activation_hook() in the constructor of the class it won’t work because it’s not in the main plugin file.
Log in to add feedback
Skip to note 26 content

Rinku Y

10 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: -8You must log in to vote on the helpfulness of this note
If you have a function called myplugin_activate() in the main plugin file at either

wp-content/plugins/myplugin.php or
wp-content/plugins/myplugin/myplugin.php
use this code:
```
register_activation_hook( __FILE__, 'myplugin_deactivate' );
```
This will call the myplugin_activate() function on activation of the plugin.
Log in to add feedback

云策 WordPress 开发者社区

函数文档