While it is true that WordPress takes care of the majority of the activation and deactivation process, these phases are ideal to carryout any specific customizations related to the plugin. With this background, in this chapter we cover WordPress Plugin Activation, Deactivation and Uninstall phases in detail and also, how to deal them in WordPress Multisite Installations.

11.1. WordPress Plugin Activation

In Share on Social Plugin, we use Activation phase to remove stale basic locker that is left over by the previous installation and also, add settings such as plugin version etc.,

Plugin uses class Sos_Activator of admin/class-activator.php to customize the plugins’ activation and deactivation.

The method, Sos_Activator::setup(), uses WordPress function register_activation_hook() to register the method that has to be invoked when plugin is activated.

share-on-social/admin/class-activator.php

class Sos_Activator {

    public function setup () {
        register_activation_hook( SOS_PLUGIN_FILE, 
                array( $this,'activate' ));
    }

This hooks Sos_Activator::activate() as activation method. The first parameter to the registration function is the constant SOS_PLUGIN_FILE defined in the plugins’ main file. It expands to the plugin main file share-on-social.php.

When admin installs the plugin and activates it, WordPress as part of activation process calls Sos_Activator::activate() method.

share-on-social/admin/class-activator.php

    public function activate ( $networkwide ) {        
        if ( function_exists( 'is_multisite' ) && is_multisite() ) {
           ....
        } else {
            if ( false == current_user_can( 'activate_plugins' ) ) {
                return;
            }
            $this->activate_for_blog();
        }
    }

It checks whether it WordPress site is a multisite or single site and if single site, it calls Sos_Activator::activate_for_blog(). Multisite activation logic is bit more complex and we will deal with it in the next chapter.

The Sos_Activator::activate_for_blog() method calls the method to delete any existing basic locker and add settings.

share-on-social/admin/class-activator.php

    public function activate_for_blog () {
        // if exists remove it
        $this->delete_basic_locker();
        $this->add_settings();
    }

When admin reinstalls the plugin, the default basic locker created in the previous installation may still exists in the database and we delete it so as to start in a clean state.

The method Sos_Activator::delete_basic_locker() finds the post_id of the locker id ‘basic’ and delete the post using WordPress function wp_delete_post(). After plugin is fully activated, as we have already seen, the method Sos::create_post_type() registers sos custom post type and creates a new default locker.

The method Sos_Activator::add_settings() adds or updates the version number of the plugin in sos_common_options in WordPress database.

share-on-social/admin/class-activator.php

    public function delete_basic_locker () {
        $post_id = Sos_Helper::get_locker_post_id( 'basic' );
        if ( $post_id ) {
            wp_delete_post( $post_id );
        }
    }

    public function add_settings () {
        $option_group = 'sos_common_options';
        $options = get_option( $option_group );
        if ( false == $options ) {
            $options = array( 'version' => SOS_VERSION );
            add_option( $option_group, $options );
        } else {
            $options[ 'version' ] = SOS_VERSION;
            update_option( $option_group, $options );
        }
    }

Version Number

It is highly recommended to store the plugin version number in WordPress database and it comes handy either for plugin support calls or during plugin up-gradation.

Even when a plugin is not using the version number, it doesn’t hurt to store this small bit of information somewhere in the database.

Action Links

It is useful to add some Call-to-Action links in the plugin section. For Share on Social Plugin, we add action link Settings, which appears once plugin is activated, so as to draw admins’ attention to do the essential settings before they use the plugin.

WordPress filter hook plugin_action_links is used to add the action links the plugin activation section.

share-on-social/admin/class-activator.php

    public function setup () {
        add_filter( 'plugin_action_links', 
                array( $this,'action_links'), 10, 2 );
    }

To the filter method Sos_Activator::action_links(), WordPress passes the array of links, that will be added to activation section, through $links parameter. Through the $file parameter plugins’ base name is passed to the filter method.

share-on-social/admin/class-activator.php

    public function action_links ( $links, $file ) {
        if ( SOS_PLUGIN_BASENAME == $file ) {
            $settings_link = '<a href="' . get_bloginfo( 'wpurl' ) .
                     '/wp-admin/edit.php?post_type=sos&page=sos_settings_page">Settings</a>';
            array_unshift( $links, $settings_link );
        }
        return $links;
    }

The filter method returns the $links array after adding the new links that points to Share on Social Settings menu. It is important to note that when Installed Plugin page is opened the filter method Sos_Activator::action_links() is called for each and every active plugin. By using $file parameter, we add action link only when base name is share-on-social so that the link is added only for Share on Plugin.

In the next section, we install WordPress Multisite and learn to code plugin activation for Multisites.