register_activation_hook( string $file, callable $function )
Set the activation hook for a plugin.
Description 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 Parameters
- $file
-
(string) (Required) The filename of the plugin including the path.
- $function
-
(callable) (Required) The function hooked to the 'activate_PLUGIN' action.
Source Source
File: wp-includes/plugin.php
function register_activation_hook( $file, $function ) { $file = plugin_basename( $file ); add_action( 'activate_' . $file, $function ); }
Expand full source code Collapse full source code View on Trac
Changelog Changelog
Version | Description |
---|---|
2.0.0 | Introduced. |
User Contributed Notes User Contributed Notes
You must log in before being able to contribute a note or feedback.
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:
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() { ... }
}
Singleton class pattern
If your plugin uses the singleton class pattern, add the activation hook like so:
If the class that holds your activation function/method is in some additional file, register your activation function like this:
Or, because the activation hook requires a static function, if you’re inside of a __construct():
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
If calling this within a namespace:
Source: http://stackoverflow.com/questions/37863766/wordpress-not-recognizing-function-during-plugin-activation
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:
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.
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.If you’re looking for a similar hook that fires when a theme is activated, see after_switch_theme.
If you have a function called
myplugin_activate()
in the main plugin file at eitherwp-content/plugins/myplugin.php or
wp-content/plugins/myplugin/myplugin.php
use this code:
This will call the
myplugin_activate()
function on activation of the plugin.