Uninstall, Activate, Deactivate a plugin: typical features & how-to

There are three different hooks. They trigger in the following cases:

  • Uninstall
  • Deactivation
  • Activation

How-to trigger functions safely during the scenarios

The following shows the right ways to safely hook callback functions that get triggered during the mentioned actions.

As you could use this code in a plugin that uses

  • plain functions,
  • a class or
  • an external class,

I’ll show three different demo plugins that you can inspect and then later on implement the code in your own plugin(s).

Important note upfront!

As this topic is extremely difficult and very detailed and has a dozen+ edge cases, this answer will never be perfect. I’ll keep improving it over time, so check back on a regular base.

(1) Activate/Deactivate/Uninstall plugins.

The plugin setup callbacks are triggered by core and you have no influence on how core does this. There’re some things to keep in mind:

  • Never, ever echo/print anything(!) during setup callbacks. This will lead to headers already sent message and core will recommend to deactivate and delete your plugin… don’t ask: I know…
  • You won’t see any visual output. But I added exit() statements to all different callbacks so you can get some insights on what is really happening. Just uncomment them to see stuff working.
  • It’s extremely important that you check if __FILE__ != WP_PLUGIN_INSTALL and (if not: abort!) to see if one is really uninstalling the plugin. I’d recommend to simply trigger on_deactivation() callbacks during development, so you save yourself the time that you’d need to get everything back in. At least this is what I do.
  • I as well do some security stuff. Some is done by core as well, but hey! Better safe than sorry!.
    • First I disallow direct file access when core isn’t loaded: defined( 'ABSPATH' ) OR exit;
    • Then I check if the current user is allowed to do this task.
    • As a last task, I check the referrer. Note: There can be unexpected results with a wp_die() screen asking for proper permissions (and if you want to try again … yeah, sure), when you got an error. This happens as core redirects you, sets the current $GLOBALS['wp_list_table']->current_action(); to error_scrape and then checks the referrer for check_admin_referer('plugin-activation-error_' . $plugin);, where $plugin is $_REQUEST['plugin']. So the redirect happens at half the page load and you get this wired scroll bar and the die screen insight the yellow admin notice/message box. If this happens: Stay calm and just search for the error with some exit() and step-by-step debugging.

(A) Plain functions plugin

Remember that this might not work if you hook the callbacks before the function definition.

<?php
defined( 'ABSPATH' ) OR exit;
/**
 * Plugin Name: (WCM) Activate/Deactivate/Uninstall - Functions
 * Description: Example Plugin to show activation/deactivation/uninstall callbacks for plain functions.
 * Author:      Franz Josef Kaiser/wecodemore
 * Author URL:  http://unserkaiser.com
 * Plugin URL:  http://wordpress.stackexchange.com/questions/25910/uninstall-activate-deactivate-a-plugin-typical-features-how-to/25979#25979
 */

function WCM_Setup_Demo_on_activation()
{
    if ( ! current_user_can( 'activate_plugins' ) )
        return;
    $plugin = isset( $_REQUEST['plugin'] ) ? $_REQUEST['plugin'] : '';
    check_admin_referer( "activate-plugin_{$plugin}" );

    # Uncomment the following line to see the function in action
    # exit( var_dump( $_GET ) );
}

function WCM_Setup_Demo_on_deactivation()
{
    if ( ! current_user_can( 'activate_plugins' ) )
        return;
    $plugin = isset( $_REQUEST['plugin'] ) ? $_REQUEST['plugin'] : '';
    check_admin_referer( "deactivate-plugin_{$plugin}" );

    # Uncomment the following line to see the function in action
    # exit( var_dump( $_GET ) );
}

function WCM_Setup_Demo_on_uninstall()
{
    if ( ! current_user_can( 'activate_plugins' ) )
        return;
    check_admin_referer( 'bulk-plugins' );

    // Important: Check if the file is the one
    // that was registered during the uninstall hook.
    if ( __FILE__ != WP_UNINSTALL_PLUGIN )
        return;

    # Uncomment the following line to see the function in action
    # exit( var_dump( $_GET ) );
}

register_activation_hook(   __FILE__, 'WCM_Setup_Demo_on_activation' );
register_deactivation_hook( __FILE__, 'WCM_Setup_Demo_on_deactivation' );
register_uninstall_hook(    __FILE__, 'WCM_Setup_Demo_on_uninstall' );

(B) A class based/OOP architecture

This is the most common example in nowadays plugins.

<?php
defined( 'ABSPATH' ) OR exit;
/**
 * Plugin Name: (WCM) Activate/Deactivate/Uninstall - CLASS
 * Description: Example Plugin to show activation/deactivation/uninstall callbacks for classes/objects.
 * Author:      Franz Josef Kaiser/wecodemore
 * Author URL:  http://unserkaiser.com
 * Plugin URL:  http://wordpress.stackexchange.com/questions/25910/uninstall-activate-deactivate-a-plugin-typical-features-how-to/25979#25979
 */


register_activation_hook(   __FILE__, array( 'WCM_Setup_Demo_Class', 'on_activation' ) );
register_deactivation_hook( __FILE__, array( 'WCM_Setup_Demo_Class', 'on_deactivation' ) );
register_uninstall_hook(    __FILE__, array( 'WCM_Setup_Demo_Class', 'on_uninstall' ) );

add_action( 'plugins_loaded', array( 'WCM_Setup_Demo_Class', 'init' ) );
class WCM_Setup_Demo_Class
{
    protected static $instance;

    public static function init()
    {
        is_null( self::$instance ) AND self::$instance = new self;
        return self::$instance;
    }

    public static function on_activation()
    {
        if ( ! current_user_can( 'activate_plugins' ) )
            return;
        $plugin = isset( $_REQUEST['plugin'] ) ? $_REQUEST['plugin'] : '';
        check_admin_referer( "activate-plugin_{$plugin}" );

        # Uncomment the following line to see the function in action
        # exit( var_dump( $_GET ) );
    }

    public static function on_deactivation()
    {
        if ( ! current_user_can( 'activate_plugins' ) )
            return;
        $plugin = isset( $_REQUEST['plugin'] ) ? $_REQUEST['plugin'] : '';
        check_admin_referer( "deactivate-plugin_{$plugin}" );

        # Uncomment the following line to see the function in action
        # exit( var_dump( $_GET ) );
    }

    public static function on_uninstall()
    {
        if ( ! current_user_can( 'activate_plugins' ) )
            return;
        check_admin_referer( 'bulk-plugins' );

        // Important: Check if the file is the one
        // that was registered during the uninstall hook.
        if ( __FILE__ != WP_UNINSTALL_PLUGIN )
            return;

        # Uncomment the following line to see the function in action
        # exit( var_dump( $_GET ) );
    }

    public function __construct()
    {
        # INIT the plugin: Hook your callbacks
    }
}

(C) A class based/OOP architecture with an external setup object

This scenario assumes that you got a main plugin file and a second file named setup.php in a subdirectory of the plugin named inc: ~/wp-content/plugins/your_plugin/inc/setup.php. This will work as well when the plugin folder is outside the default WP folder structure, as well when the content dir is renamed or in cases where your setup file is named different. Only the inc folder has to have the same name & location relative from the plugins root directory.

Note: You can simply take the three register_*_hook()* functions and the classes and drop them into your plugin.

The main plugin file:

<?php
defined( 'ABSPATH' ) OR exit;
/**
 * Plugin Name: (WCM) Activate/Deactivate/Uninstall - FILE/CLASS
 * Description: Example Plugin
 * Author:      Franz Josef Kaiser/wecodemore
 * Author URL:  http://unserkaiser.com
 * Plugin URL:  http://wordpress.stackexchange.com/questions/25910/uninstall-activate-deactivate-a-plugin-typical-features-how-to/25979#25979
 */


register_activation_hook(   __FILE__, array( 'WCM_Setup_Demo_File_Inc', 'on_activation' ) );
register_deactivation_hook( __FILE__, array( 'WCM_Setup_Demo_File_Inc', 'on_deactivation' ) );
register_uninstall_hook(    __FILE__, array( 'WCM_Setup_Demo_File_Inc', 'on_uninstall' ) );

add_action( 'plugins_loaded', array( 'WCM_Setup_Demo_File', 'init' ) );
class WCM_Setup_Demo_File
{
    protected static $instance;

    public static function init()
    {
        is_null( self::$instance ) AND self::$instance = new self;
        return self::$instance;
    }

    public function __construct()
    {
        add_action( current_filter(), array( $this, 'load_files' ), 30 );
    }

    public function load_files()
    {
        foreach ( glob( plugin_dir_path( __FILE__ ).'inc/*.php' ) as $file )
            include_once $file;
    }
}

The setup file:

<?php
defined( 'ABSPATH' ) OR exit;

class WCM_Setup_Demo_File_Inc
{
    public static function on_activation()
    {
        if ( ! current_user_can( 'activate_plugins' ) )
            return;
        $plugin = isset( $_REQUEST['plugin'] ) ? $_REQUEST['plugin'] : '';
        check_admin_referer( "activate-plugin_{$plugin}" );

        # Uncomment the following line to see the function in action
        # exit( var_dump( $_GET ) );
    }

    public static function on_deactivation()
    {
        if ( ! current_user_can( 'activate_plugins' ) )
            return;
        $plugin = isset( $_REQUEST['plugin'] ) ? $_REQUEST['plugin'] : '';
        check_admin_referer( "deactivate-plugin_{$plugin}" );

        # Uncomment the following line to see the function in action
        # exit( var_dump( $_GET ) );
    }

    public static function on_uninstall()
    {
        if ( ! current_user_can( 'activate_plugins' ) )
            return;
        check_admin_referer( 'bulk-plugins' );

        // Important: Check if the file is the one
        // that was registered during the uninstall hook.
        if ( __FILE__ != WP_UNINSTALL_PLUGIN )
            return;

        # Uncomment the following line to see the function in action
        # exit( var_dump( $_GET ) );
    }
}

(2) Plugin updates

If you write a plugin that has its own DB table or options, there might be scenarios where you need to change or upgrade things.

Sadly so far there’s no possibility to run something on plugin/theme install or update/upgrade. Gladly there’s a work-around: Hook a custom function to a custom option (yea, it’s lame – but it works).

function prefix_upgrade_plugin() 
{
    $v = 'plugin_db_version';
    $update_option = null;
    // Upgrade to version 2
    if ( 2 !== get_option( $v ) ) 
    {
        if ( 2 < get_option( $v ) )
        {
            // Callback function must return true on success
            $update_option = custom_upgrade_cb_fn_v3();

            // Only update option if it was an success
            if ( $update_option )
                update_option( $v, 2 );
        }
    }

    // Upgrade to version 3, runs just after upgrade to version 2
    if ( 3 !== get_option( $v ) ) 
    {
        // re-run from beginning if previous update failed
        if ( 2 < get_option( $v ) )
            return prefix_upgrade_plugin();

        if ( 3 < get_option( $v ) )
        {
            // Callback function must return true on success
            $update_option = custom_upgrade_cb_fn_v3();

            // Only update option if it was an success
            if ( $update_option )
                update_option( $v, 3 );
        }
    }

    // Return the result from the update cb fn, so we can test for success/fail/error
    if ( $update_option )
        return $update_option;

return false;
}
add_action('admin_init', 'prefix_upgrade_plugin' );

Source

This update function is a not-so-nice/well-written example, but as said: It’s an example and the technique works well. Will improve that with a later update.

Related Posts:

  1. How to automate wordpress plugin activate and deactivate by php logic?
  2. My plugin does not install correctly if a previous version is still installed
  3. How to delete custom taxonomy terms in plugin’s uninstall.php?
  4. Function to activate WordPress theme inside a plugin
  5. Activate Plugin which is in subfolder?
  6. Force plugin to fail activation
  7. WordPress register_activation_hook table creation not working
  8. Correct way to use register_activation_hook
  9. OOP: Display warning and deactivate the plugin if PHP version is less than 5.4
  10. Do you clean up your self-written plugins’ at deactivation?
  11. Auto add content such as pages upon plugin activation?
  12. Default Plugin Settings Not Writing to Database
  13. Plugin Deactivate Self on Activation Errors
  14. Why my Plugin keeps deactivating automatically?
  15. Prevent a plugin from being automatically activated
  16. UnInstallation of a Plugin from a developers perspective – The correct and clean method
  17. Own plugin corrups plugin-activation
  18. uninstall.php file in Plugin to clean DB
  19. Are functions in main plugin file called before function bound to register_activation_hook runs?
  20. Force file download on plugin activation
  21. How to delete custom taxonomy terms in plugin’s uninstall.php?
  22. Remove .htaccess portion upon plugin deactivation?
  23. Run function on plugin activation before plugin is loaded
  24. Can plugin2 uninstall plugin1 at the very beginning of plugin2’s installation?
  25. plugin uninstall function drop the tables, but shows errors on admin
  26. How to deactivate my plugin upon deactivation of NextGen
  27. Activation flow of a plugin in a multisite environment
  28. How to check for already existing plugin versions on activation? and prevent errors
  29. My WordPress activation hook isn’t working
  30. Different plugins activated online and offline
  31. Is it possible to run javascript on plugin deactivated?
  32. Show Similar Post Titles ( Similar to Stack Exchange )
  33. How do I unlock a post programmatically?
  34. Customizing subject in comment notification e-mails
  35. enqueue script only if it is not already enqueue
  36. Plugin child folder?
  37. merging an array to an existing array using add_filter
  38. How do I store information in a dynamic block in WordPress?
  39. Is it possible to set up multistore in Woocommerce? [closed]
  40. How to check what plugins used to be on a WordPress installation?
  41. How to generate video out of images via WordPress plugin
  42. How to slice an array using posts_per_page? [closed]
  43. Get plugin option in another PHP file
  44. woocommerce payment gateway callback not firing [closed]
  45. White page by using filter template_include
  46. How to export post 2 posts WordPress plugin data [closed]
  47. Customization API for plugin development
  48. User switching only with specific role and return
  49. Adding Font Awesome to WP Plugin
  50. Does plugin’s uninstall.php file have access to the plugin ‘s object?
  51. Display custom content using page.php from theme
  52. how to deactivate a plugin without using a WP function?
  53. WordPress error: Options page Setting_ not found in the allowed options list
  54. Plugin retrieving results even after uninstallation
  55. How to add a dvi tag to a shortcode then change a generated text using jQuery
  56. Translations for my plugin don’t show up
  57. Is there a better way of handling AJAX requests in WordPress?
  58. how to add a comment button to be displayed only for the posts in the home page [closed]
  59. How to add category and subcategory in WordPress custom code?
  60. The “Child Pages Shortcode” plugin, block template
  61. Can’t create tables with my plugin
  62. How to get a custom page through plugin?
  63. using wp_cache in plugin
  64. How to data add to table when update post wordpress? when we clicked!
  65. can’t unzip file
  66. WooCommerce – I want to add functionality of one plugin to another plugin — best approach?
  67. Check if theme supports sidebar
  68. Problem with MEMCACHE and Redis with wp_options
  69. Change plugin descriptions
  70. How to display the custom post related blog by category?
  71. WP Forms not displaying,becomming an fatal error
  72. I want to schedule email (date, time is in database->table) wp_schedule_event() not working
  73. How to create a page with the selected template after activating the plugin
  74. I enabled debugging but I still get the same message: There has been a critical error on your website
  75. wp_mail function not working in WordPress Plugin Boilerplate
  76. When/where would want to attach other classes to the base class in a WordPress plugin?
  77. Use Case: Multiple Shipping Methods per Order
  78. Showing how many times is plugin activated or deactivated
  79. Could someone maybe point me in the direction of a decent tutorial on how to create a wordpress plugin that is compatible with another plugin please?
  80. Custom plugin which downloads updates from custom endpoint, extracts new version zip into a new name
  81. How to get post that has non zero or greater than zero meta value
  82. Form tries to download a file on submit
  83. wp meta_query meta_value compare =REGEXP delimited by space
  84. How to insert variable which contain array value in wp_options table?
  85. Multiselect value in wp_query
  86. How to Overwrite validate_plugin function
  87. how to load a file from a plugin when a url is passed
  88. Is it possible to cancel a post status transition?
  89. Form data to wordpress DB
  90. Activate plugins by a theme’s functions.php?
  91. Is it possible to send user new password after they clicking on forgot password in word press
  92. Register additional wp plugin directory
  93. How to include a custom thumbnail with my WordPress plugin?
  94. How to display blog posts only authored by the administrator
  95. Send email notification when meet the condition
  96. ACF Plugin WP with list-group – Vimeo [closed]
  97. how to make wordpress remember my choice
  98. Meta box not displaying on the plugin page
  99. wordpress admin-ajax bad request 400
  100. public custom posts not showing in my wordpress plugin

Leave a Comment

Hata!: SQLSTATE[HY000] [1045] Access denied for user 'divattrend_liink'@'localhost' (using password: YES)