Function Reference/register activation hook

来自WordPress中文文档
跳转至: 导航搜索

wordpress.org.cn

Description

The register_activation_hook function registers a plugin function to be run when the plugin is activated.

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/plugin/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/plugin/sample.php the name of this hook will be 'activate_sample.php'.

This function is a wrapper for the 'activate_PLUGINNAME' action, and is easier to use.

Usage

%%% <?php register_activation_hook( $file, $function ); ?> %%%

Parameters

tt$file/tt
(string) (required) Path to the main plugin file inside the wp-content/plugins directory. A full path will work.
Default: Nonenoinclude

div class=template-description style=padding: 0 1.5em; border: 1px solid #eeeeee; background-color: #f9f9f9

Notes

This template is for standardizing how parameters look in the Function Reference and in Template Tags. Here is an example of this template being called: prenowiki检查到模板循环:模板:Parameter/nowiki/pre 检查到模板循环:模板:Parameter

The usage of this template is below: prenowiki检查到模板循环:模板:Parameter/nowiki/pre Let's take a closer look at the parameters..

name
The name of the parameter.
datatype
The datatype that should be given for this parameter when called.
  • string
  • integer
  • boolean
  • mixed
description
A short description of the parameter.
importance
Set this parameter to optional if the parameter is optional. Otherwise, do not declare this parameter—it defaults to required.
  • required
  • optional
default
If this parameter is optional, ttdefault/tt is the value that will be used if the parameter is not declared.

wordpress.org.cn /div /noinclude

tt$function/tt
(callback) (required) The function to be run when the plugin is activated. Any of PHP's callback pseudo-types will work.
Default: Nonenoinclude

div class=template-description style=padding: 0 1.5em; border: 1px solid #eeeeee; background-color: #f9f9f9

Notes

This template is for standardizing how parameters look in the Function Reference and in Template Tags. Here is an example of this template being called: prenowiki检查到模板循环:模板:Parameter/nowiki/pre 检查到模板循环:模板:Parameter

The usage of this template is below: prenowiki检查到模板循环:模板:Parameter/nowiki/pre Let's take a closer look at the parameters..

name
The name of the parameter.
datatype
The datatype that should be given for this parameter when called.
  • string
  • integer
  • boolean
  • mixed
description
A short description of the parameter.
importance
Set this parameter to optional if the parameter is optional. Otherwise, do not declare this parameter—it defaults to required.
  • required
  • optional
default
If this parameter is optional, ttdefault/tt is the value that will be used if the parameter is not declared.

wordpress.org.cn /div /noinclude

Examples

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:

function myplugin_activate() {

    // Activation code here...
}
register_activation_hook( __FILE__, 'myplugin_activate' );

This will call the myplugin_activate() function on activation of the plugin.

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 if you're inside of a __construct():

register_activation_hook( __FILE__, array( $this, 'YOUR_METHOD_NAME' ) );

Notes

  • Related discussion with another sample of working code: http://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 being activated. The plugin's activation hook is run and then the page is immediately redirected (see below).

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: http://wordpress.org/support/topic/201309

Discussions

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

Changelog

Source File

register_activation_hook() is located in onlyincludecodewp-includes/plugin.php/code/onlyinclude

div class=template-description style=padding: 0 1.5em; border: 1px solid #eeeeee; background-color: #f9f9f9

Template Description

Link to the source code on http://core.trac.wordpress.org/browser/.

Parameters

  1. filename
  2. (option) path to codetag/code (version) or codetrunk/code. This option is only used for a new function.br /Default: codetrunk/code -- trunk is the latest bleeding edge development version of WordPress.

Usage

Link to the stable version: pre检查到模板循环:模板:Trac/pre

Link to trunk: pre检查到模板循环:模板:Trac/pre

/div

wordpress.org.cn

Related

includeonlydiv style=clear:both; background-color:#F7F7F7; border:1px solid #CCCCCC; color:#000000; padding:7px; margin:0.5em auto 0.5em auto; vertical-align:middle;See also index of Function Reference and index of Template Tags./div/includeonlynoinclude

Description

This Template is used by Codex:Template Messages.

Usage

pre 检查到模板循环:模板:Message /pre

Result

检查到模板循环:模板:Message

/noinclude