Function Documentation

WordPress Function Documentation Progress

Writing Plugins: Including an Uninstaller

I think the central issue is that, plugin developers think writing an uninstaller is difficult, but it is not. I’ve been doing it for quite a while in my private WordPress plugins. It was quite easy. I think that the few plugins which do implement it, do so in a way that over complicates it for other novice users.

  1. Activation Step

    The core simple concept is to have an option that tells your plugin whether the plugin should be uninstalled or not. If you add options anyway, then this isn’t to difficult.

  2. Deactivation Step

    The second concept is to check that option during the deactivation and then if it is set to true, then you remove everything that you added in the activation step.

  3. Plugin Option Administration

    I think this is where novice plugin authors get tripped up and most other people. If you already have an options page, then it should be simple to add a checkbox that states whether the user wants to uninstall the plugin when it is deactivated.

    If you don’t have an options page, then let me walk you through that.

Activation Step

The code is pretty much uniform for all of my plugins and most plugins that I see.


function myplugin_activation()
{
    $option = get_option('myplugin_option');

    if( false === $option )
    {
        // Install tables and setup options

        $option = array();
        $option['uninstall'] = false;
        // Other options
        
        add_option('myplugin_option', $option);
    }
}

register_activation_hook(__FILE__, 'myplugin_activation');

And that implements the entire step for adding the uninstall option. Not to difficult, I don’t think. If you have any questions, then feel free to ask.

Deactivation Step

The deactivation step is as easy as the activation step (and I think the only difficult part is creating the administration page).

What you do is get the options and test to see if the options exist (should always exist, but you never know if the user deleted your options for you). Then you test to see if the uninstall option is true and remove everything.


function myplugin_deactivation()
{
    $options = get_option('myplugin_option');

    if( is_array($options) && $options['uninstall'] === true)
    {
        delete_option('myplugin_option');
        // Remove other tables and installed items.
    }
}

register_deactivation_hook(__FILE__, 'myplugin_deactivation');

That is it! Quite easy, I believe. The hard part is creating the administration page, until you get used to doing them.

Administration Page Alternative

You do have an alternative, if you don’t want to create an administration page. What I’ve done, was test to see if an constant is defined and if it is, I run the uninstall in the deactivation hook. This will require manual work on the user’s part, and instructions on your part. Quite frankly this is only useful for testing of your uninstaller, and for personal projects where you don’t really need an administration page. However, if you plan on placing your plugin in the open, it will be a good idea to use the other method.


function myplugin_deactivation()
{
    if( defined('UNINSTALL_MYPLUGIN') )
    {
        delete_option('myplugin_option');
        // Remove other tables and installed items.
    }
}

register_deactivation_hook(__FILE__, 'myplugin_deactivation');

Administration Step

The administration creation is not difficult, just time consuming. When you have it set up, it is fairly straight forward. I would also suggest that if you are just going to include the uninstaller option that you have your plugin page in the plugin page.

I’ll post the administration creation step in a later step. If you need more information then the WordPress codex has all that you need for creating administration pages.

January 24, 2008 Posted by | Writing Plugins Series | , , , | Leave a comment

Writing Plugins: Activation and Deactivation

WordPress provides hooks for when the plugin is activated and deactivated. Some plugins will have logic in their init function which check to see if set up or installed itself and if it didn’t it would install or upgrade itself.

The upgrader check can still remain in the init function, a user might have not deactivated the plugin before uploading the new files. The installer can be placed in the activation hook which can check if the plugin had been installed and install if it hadn’t installed already. It can also check to see if it needs to upgrade, in case the user deactivated before uploading the new plugin files or had the plugin deactivated for some other reason.

Any amount of code for which can be moved to the activation and deactivation functions from the init function can save that much overhead and reduce the complexity of the init process.

Activation

function myplugin_activation() {
    $pluginOptions = get_option('myplugin_data');

    if ( false === $pluginOptions ) {
        // Install plugin
    } else if ( MYPLUGIN_VER != $pluginOptions['version'] ) {
        // Upgrade plugin
    }
}

register_activation_hook(__FILE__, 'myplugin_activation');

It is really that easy. WordPress provides a convenience function for hooking into the plugin’s activation hook, no matter where the plugin is located. If your plugin is moved from its directory structure, then if you manually hooked into the activation action, you might not be hooking into the right one. There is a way around that problem, but it is easier to just use register_activation_hook() instead.

Deactivation

The deactivation is easier, but most plugins don’t need it. You can be annoying and prevent the user from disabling your plugin, but they’ll get wise to your deception and remove your plugin, if you choose to do that. It would be unwise to include anything in your plugin that might discourage further usage and users.

It will be useful if you wish to include an uninstaller, in case your plugin creates new tables or adds options or whatever else that may need to be cleaned up. The topic of building an uninstaller is for another day, right now, it is one idea in case you have other needs or ideas for it.

function myplugin_deactivation() {
    $pluginOptions = get_option('myplugin_data');

    if ( true === $pluginOptions['uninstall'] ) {
        delete_option('myplugin_data');
    }
}

register_deactivation_hook(__FILE__, 'myplugin_deactivation');

Again, WordPress provides another convenience function for the deactivation of your plugin. The logic for the deactivation is a lot less than the activation in most cases.

January 8, 2008 Posted by | Writing Plugins Series | , , , | Leave a comment

Writing Plugins: Put all logic in functions

The only code that should be outside functions are the hooks into activate, deactivate, and init hook. A plugin should not assume that it can put HTML and echo blocks outside of functions, because the HTML and logic will display before WordPress is initiated.

The explanation for this is the plugins are included into the process after all of the WordPress library files are included, but before the rest of WordPress is set up. The reason to hook into the ‘init’ hook is that is when WordPress is finished setting everything up and is called at the very end of the wp-setting.php file.

Every plugin should have this code structure:

function mynamespace_init() {
    // hook into all needed filters and actions
}

add_action('init', 'mynamespace_init');

What You Should Never Do

  1. if( WordPress is Setup ) {
        echo "I'm evil
    "; }

    This will always fail, because there is no way to figure out if WordPress is ready for output without using the Plugin API.


  2. require ( ABSPATH . WPINC . '/plugins.php' );

    This will cause WordPress to fail since plugins.php is already included at the time your plugin is included. You should never include WordPress library files! The exception to this might be the admin library files, but you should always check for the function you want before trying to include the file and should always check the inclusion path inside the admin page you’ll be hooking into.

January 7, 2008 Posted by | Writing Plugins Series | , , | 1 Comment