If you’re developing a plugin, chances are you’ve been caught out by the WordPress activation/deactivation hooks.
I’ve been working on an Instagram plugin for WordPress, and in doing so have needed to use the functions register_activation_hook and register_deactivation_hook.
However, I – like many others, it seems – can’t get the hooked functions to execute. They simply don’t fire. To illustrate the problem, here’s an example from the code:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 |
define('MY_INSTAGRAM_PLUGIN_PATH', plugin_dir_path(__FILE__)); require_once MY_INSTAGRAM_PLUGIN_PATH . 'my-instagram-widget.php'; $my_instagram = new My_Instagram(); class My_Instagram { /** * Standard constructor to initalise hooks and options * * @return void */ public function __construct() { register_activation_hook(__FILE__, array($this, 'install')); register_deactivation_hook(__FILE__, array($this, 'uninstall')); } /** * Set up the table and options * * @return void */ public function install() { ... } /** * Drop the table and options associated with the plugin * * @return void */ public function uninstall() { ... } } |
I would fully expect the system to execute the functions hooked within the constructor. Had that been the case, I wouldn’t have lost a day debugging a non-existant problem.
Finding a solution
Of course, everyone’s setup is different. There were many suggestions for fixing the problem. For the sake of usefulness, here’s the other major suggestion:
Your global variables aren’t global
If (like me), your plugin is a global, you actually need to explicitly define it as such with the global keyword. For example, the snippet
|
1 |
$my_instagram = new My_Instagram(); |
should instead by written this way:
|
1 2 |
global $my_instagram; $my_instagram = new My_Instagram(); |
Why? Well, for this, we need to consider how the plugin has its code loaded. After installation, your plugin has its code included “normally” with standard includes. This creates the global scope that you would expect. However, when you register a function with register_(de)activation_hook, it is called from within another function’s scope, effectively hiding your non-explicit globals.
Confused? Consider the plugin example from earlier. The variable $my_instagram is declared in the global scope, with global visibility. When your code executes, your plugin is included at the same scope, meaning you will have access to the variable (as they share the same suitably-high scope). Due to the way the hook/filter system in WordPress works, your activation/deactivation hooks are executed within a localised (not global) scope.
This scope-confusion applies to all functions created using create_function, or (in our specific example), functions called with call_user_func (and call_user_func_array). These functions have their own scope and are thus shielded from the cheap-and-nasty pile of implicit “globals” that haven’t been properly declared as such.
You can find a suitably more technical (and probably correct) write-up at the WordPress Codex page for register_activation_hook.
tl;dr: Explicitly declare your globals if you want them to work everywhere.
Ok, that’s great, but what’s the answer?
After having accidentally (and rather unwillingly) been given a very rough refresher on scope, I found that this was not my problem at all. Even running proxy functions (which eliminates scope issues) failed to call the functions specified in the hook.
After much trial and error (and I mean much), I found that the paths within register_(de)activation_hook were not matching the path found in plugin_dir_path. In fact, __FILE__ was returning a completely different path.
The problem? I had symlinked the theme directory in my install, meaning that __FILE__ returned a different path to plugin_dir_path. This is especially important, as the file path specified by the first parameter of register_(de)activation_hook is included before the function specified by the second parameter is called. So, if the path in the first parameter is wrong, you probably aren’t going to be executing many functions today.
The Fix
This is always my favourite part. To fix the symlinking problem, you just have to be very specific when you’re asking WordPress to execute a hook for you.
Fixing the first example, we get:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 |
define('MY_INSTAGRAM_PLUGIN_PATH', WP_PLUGIN_DIR . '/my-instagram/'); require_once MY_INSTAGRAM_PLUGIN_PATH . 'my-instagram-widget.php'; global $my_instagram; $my_instagram = new My_Instagram(); class My_Instagram { /** * Standard constructor to initalise hooks and options * * @return void */ public function __construct() { register_activation_hook(MY_INSTAGRAM_PLUGIN_PATH . 'my-instagram.php', array($this, 'install')); register_deactivation_hook(MY_INSTAGRAM_PLUGIN_PATH . 'my-instagram.php', array($this, 'uninstall')); } /** * Set up the table and options * * @return void */ public function install() { ... } /** * Drop the table and options associated with the plugin * * @return void */ public function uninstall() { ... } } |
The most important changes occur on lines 1, 16, and 17. The first line fixes the definition by manually specifying the path using the base plugin directory (instead of an automagic WordPress search). Lines 16 and 17 specify the main plugin file itself as the path (instead of relying on __FILE__).
This allowed WordPress to find the plugin files without a hitch, which is especially important in the installation/uninstallation phases.
Moral of the story? Check your paths first.
