activate_plugin( string $plugin, string $redirect = '', bool $network_wide = false, bool $silent = false )

Attempts activation of plugin in a “sandbox” and redirects on success.

Contents

Description Description

A plugin that is already activated will not attempt to be activated again.

The way it works is by setting the redirection to the error before trying to include the plugin file. If the plugin fails, then the redirection will not be overwritten with the success message. Also, the options will not be updated and the activation hook will not be called on plugin error.

It should be noted that in no way the below code will actually prevent errors within the file. The code should not be used elsewhere to replicate the "sandbox", which uses redirection to work. {@source 13 1}

If any errors are found or text is outputted, then it will be captured to ensure that the success redirection will update the error redirection.

Parameters Parameters

$plugin

(string) (Required) Path to the plugin file relative to the plugins directory.

$redirect

(string) (Optional) URL to redirect to.

Default value: ''

$network_wide

(bool) (Optional) Whether to enable the plugin for all sites in the network or just the current site. Multisite only.

Default value: false

$silent

(bool) (Optional) Whether to prevent calling activation hooks.

Default value: false

Top ↑

Return Return

(WP_Error|null) WP_Error on invalid file or null on success.

Top ↑

Source Source

File: wp-admin/includes/plugin.php

606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
function activate_plugin( $plugin, $redirect = '', $network_wide = false, $silent = false ) {
    $plugin = plugin_basename( trim( $plugin ) );
 
    if ( is_multisite() && ( $network_wide || is_network_only_plugin( $plugin ) ) ) {
        $network_wide        = true;
        $current             = get_site_option( 'active_sitewide_plugins', array() );
        $_GET['networkwide'] = 1; // Back compat for plugins looking for this value.
    } else {
        $current = get_option( 'active_plugins', array() );
    }
 
    $valid = validate_plugin( $plugin );
    if ( is_wp_error( $valid ) ) {
        return $valid;
    }
 
    if ( ( $network_wide && ! isset( $current[ $plugin ] ) ) || ( ! $network_wide && ! in_array( $plugin, $current ) ) ) {
        if ( ! empty( $redirect ) ) {
            wp_redirect( add_query_arg( '_error_nonce', wp_create_nonce( 'plugin-activation-error_' . $plugin ), $redirect ) ); // we'll override this later if the plugin can be included without fatal error
        }
        ob_start();
        wp_register_plugin_realpath( WP_PLUGIN_DIR . '/' . $plugin );
        $_wp_plugin_file = $plugin;
        include_once( WP_PLUGIN_DIR . '/' . $plugin );
        $plugin = $_wp_plugin_file; // Avoid stomping of the $plugin variable in a plugin.
 
        if ( ! $silent ) {
            /**
             * Fires before a plugin is activated.
             *
             * If a plugin is silently activated (such as during an update),
             * this hook does not fire.
             *
             * @since 2.9.0
             *
             * @param string $plugin       Path to the plugin file relative to the plugins directory.
             * @param bool   $network_wide Whether to enable the plugin for all sites in the network
             *                             or just the current site. Multisite only. Default is false.
             */
            do_action( 'activate_plugin', $plugin, $network_wide );
 
            /**
             * Fires as a specific plugin is being activated.
             *
             * This hook is the "activation" hook used internally by register_activation_hook().
             * The dynamic portion of the hook name, `$plugin`, refers to the plugin basename.
             *
             * If a plugin is silently activated (such as during an update), this hook does not fire.
             *
             * @since 2.0.0
             *
             * @param bool $network_wide Whether to enable the plugin for all sites in the network
             *                           or just the current site. Multisite only. Default is false.
             */
            do_action( "activate_{$plugin}", $network_wide );
        }
 
        if ( $network_wide ) {
            $current            = get_site_option( 'active_sitewide_plugins', array() );
            $current[ $plugin ] = time();
            update_site_option( 'active_sitewide_plugins', $current );
        } else {
            $current   = get_option( 'active_plugins', array() );
            $current[] = $plugin;
            sort( $current );
            update_option( 'active_plugins', $current );
        }
 
        if ( ! $silent ) {
            /**
             * Fires after a plugin has been activated.
             *
             * If a plugin is silently activated (such as during an update),
             * this hook does not fire.
             *
             * @since 2.9.0
             *
             * @param string $plugin       Path to the plugin file relative to the plugins directory.
             * @param bool   $network_wide Whether to enable the plugin for all sites in the network
             *                             or just the current site. Multisite only. Default is false.
             */
            do_action( 'activated_plugin', $plugin, $network_wide );
        }
 
        if ( ob_get_length() > 0 ) {
            $output = ob_get_clean();
            return new WP_Error( 'unexpected_output', __( 'The plugin generated unexpected output.' ), $output );
        }
        ob_end_clean();
    }
 
    return null;
}

Expand full source code Collapse full source code View on Trac

Top ↑

Changelog Changelog

Changelog
Version Description
2.5.0 Introduced.

Top ↑

Top ↑

Uses Uses

Uses
Uses Description
wp-admin/includes/plugin.php: validate_plugin()

Validate the plugin path.
wp-admin/includes/plugin.php: is_network_only_plugin()

Checks for “Network: true” in the plugin header to see if this should be activated only as a network wide plugin. The plugin would also work when Multisite is not enabled.
wp-admin/includes/plugin.php: activate_{$plugin}

Fires as a specific plugin is being activated.
wp-admin/includes/plugin.php: activated_plugin

Fires after a plugin has been activated.
wp-includes/l10n.php: __()

Retrieve the translation of $text.
wp-includes/pluggable.php: wp_create_nonce()

Creates a cryptographic token tied to a specific action, user, user session, and window of time.
wp-includes/pluggable.php: wp_redirect()

Redirects to another page.
wp-includes/load.php: is_multisite()

If Multisite is enabled.
wp-includes/functions.php: add_query_arg()

Retrieves a modified URL query string.
wp-includes/plugin.php: plugin_basename()

Gets the basename of a plugin.
wp-includes/plugin.php: wp_register_plugin_realpath()

Register a plugin’s real path.
wp-includes/plugin.php: do_action()

Execute functions hooked on a specific action hook.
wp-includes/option.php: update_site_option()

Update the value of an option that was already added for the current network.
wp-includes/option.php: get_site_option()

Retrieve an option value for the current network based on name of option.
wp-includes/option.php: update_option()

Update the value of an option that was already added.
wp-includes/option.php: get_option()

Retrieves an option value based on an option name.
wp-includes/load.php: is_wp_error()

Check whether variable is a WordPress Error.
wp-includes/class-wp-error.php: WP_Error::__construct()

Initialize the error.
Show 13 more uses Hide more uses

Top ↑

User Contributed Notes User Contributed Notes

  2. Skip to note 2 content
    You must log in to vote on the helpfulness of this noteVote results for this note: -1You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    Error Message

    Plugin will fail to activate with the following generic response for multiple reasons, including; issues parsing the header information, issue with the ‘plugin’ cache (see WordPress Object Cache), or a permissions error.

    1
    The plugin does not have a valid header
  3. Skip to note 3 content
    You must log in to vote on the helpfulness of this noteVote results for this note: -1You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    Plugin cache issue

    Issues with the plugin cache are caused when the plugin files are added or modified, after the plugins have all been initialised. This can be resolved by reloading the page, sending the activate_plugin() as a separate AJAX request, or if necessary, by manually updating the cache. Example below;

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    $cache_plugins = wp_cache_get( 'plugins', 'plugins' );
    if ( !empty( $cache_plugins ) ) {
        $new_plugin = array(
            'Name'        => $plugin_name,
            'PluginURI'   => $plugin_uri,
            'Version'     => $plugin_version,
            'Description' => $plugin_description,
            'Author'      => $author_name,
            'AuthorURI'   => $author_uri,
            'TextDomain'  => '',
            'DomainPath'  => '',
            'Network'     => '',
            'Title'       => $plugin_name,
            'AuthorName'  => $author_name,
        );
        $cache_plugins[''][$plugin_path] = $new_plugin;
        wp_cache_set( 'plugins', $cache_plugins, 'plugins' );
    }

    Expand full source codeCollapse full source code

You must log in before being able to contribute a note or feedback.