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.


Top ↑

Source Source

File: wp-includes/plugin.php

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

Top ↑

Changelog Changelog

Changelog
Version Description
2.0.0 Introduced.


Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note 1 content
    Contributed by orionrush

    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' );
    
  2. Skip to note 2 content
    Contributed by ics1010

    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() { ... }
    }

  3. Skip to note 3 content
    Contributed by Codex

    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' ) );
    
  4. Skip to note 4 content
    Contributed by mallorydxw-old

    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

  5. Skip to note 6 content
    Contributed by Giulio Daprela

    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.

  6. Skip to note 7 content
    Contributed by samwilson

    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.

  7. Skip to note 9 content
    Contributed by Rinku Y

    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.

You must log in before being able to contribute a note or feedback.