云策 WordPress 开发者社区

函数文档

uninstall_plugin()

查看官方原文 ↗
💡 云策文档标注

概述

uninstall_plugin() 函数用于卸载单个插件，通过调用插件的卸载钩子（如果可用）来执行清理操作。它处理插件目录中的 uninstall.php 文件或注册的卸载回调，并触发相关动作钩子。

关键要点

  • 函数接受一个必需参数 $plugin，表示相对于插件目录的插件文件路径。
  • 如果找到并包含插件的 uninstall.php 文件，则返回 true；否则返回 void。
  • 在卸载前触发 pre_uninstall_plugin 钩子，卸载后触发动态命名的 uninstall_{$file} 钩子。
  • 函数内部使用 get_option 和 update_option 管理可卸载插件列表，并调用 wp_register_plugin_realpath 等辅助函数。

代码示例

function uninstall_plugin( $plugin ) {
    $file = plugin_basename( $plugin );
    $uninstallable_plugins = (array) get_option( 'uninstall_plugins' );
    do_action( 'pre_uninstall_plugin', $plugin, $uninstallable_plugins );
    if ( file_exists( WP_PLUGIN_DIR . '/' . dirname( $file ) . '/uninstall.php' ) ) {
        if ( isset( $uninstallable_plugins[ $file ] ) ) {
            unset( $uninstallable_plugins[ $file ] );
            update_option( 'uninstall_plugins', $uninstallable_plugins );
        }
        unset( $uninstallable_plugins );
        define( 'WP_UNINSTALL_PLUGIN', $file );
        wp_register_plugin_realpath( WP_PLUGIN_DIR . '/' . $file );
        include_once WP_PLUGIN_DIR . '/' . dirname( $file ) . '/uninstall.php';
        return true;
    }
    if ( isset( $uninstallable_plugins[ $file ] ) ) {
        $callable = $uninstallable_plugins[ $file ];
        unset( $uninstallable_plugins[ $file ] );
        update_option( 'uninstall_plugins', $uninstallable_plugins );
        unset( $uninstallable_plugins );
        wp_register_plugin_realpath( WP_PLUGIN_DIR . '/' . $file );
        include_once WP_PLUGIN_DIR . '/' . $file;
        add_action( "uninstall_{$file}", $callable );
        do_action( "uninstall_{$file}" );
    }
}

注意事项

  • 确保 $plugin 参数正确指向插件文件，否则可能无法触发卸载过程。
  • 卸载操作可能涉及数据库清理或文件删除，建议在测试环境中先行验证。
  • 动态钩子 uninstall_{$file} 的名称基于插件 basename 构建，需注意命名一致性。
📄 原文内容

Uninstalls a single plugin.

Description

Calls the uninstall hook, if it is available.

Parameters

$pluginstringrequired
Path to the plugin file relative to the plugins directory.

Return

true|void True if a plugin’s uninstall.php file has been found and included.
Void otherwise.

Source

function uninstall_plugin( $plugin ) {
	$file = plugin_basename( $plugin );

	$uninstallable_plugins = (array) get_option( 'uninstall_plugins' );

	/**
	 * Fires in uninstall_plugin() immediately before the plugin is uninstalled.
	 *
	 * @since 4.5.0
	 *
	 * @param string $plugin                Path to the plugin file relative to the plugins directory.
	 * @param array  $uninstallable_plugins Uninstallable plugins.
	 */
	do_action( 'pre_uninstall_plugin', $plugin, $uninstallable_plugins );

	if ( file_exists( WP_PLUGIN_DIR . '/' . dirname( $file ) . '/uninstall.php' ) ) {
		if ( isset( $uninstallable_plugins[ $file ] ) ) {
			unset( $uninstallable_plugins[ $file ] );
			update_option( 'uninstall_plugins', $uninstallable_plugins );
		}
		unset( $uninstallable_plugins );

		define( 'WP_UNINSTALL_PLUGIN', $file );

		wp_register_plugin_realpath( WP_PLUGIN_DIR . '/' . $file );
		include_once WP_PLUGIN_DIR . '/' . dirname( $file ) . '/uninstall.php';

		return true;
	}

	if ( isset( $uninstallable_plugins[ $file ] ) ) {
		$callable = $uninstallable_plugins[ $file ];
		unset( $uninstallable_plugins[ $file ] );
		update_option( 'uninstall_plugins', $uninstallable_plugins );
		unset( $uninstallable_plugins );

		wp_register_plugin_realpath( WP_PLUGIN_DIR . '/' . $file );
		include_once WP_PLUGIN_DIR . '/' . $file;

		add_action( "uninstall_{$file}", $callable );

		/**
		 * Fires in uninstall_plugin() once the plugin has been uninstalled.
		 *
		 * The action concatenates the 'uninstall_' prefix with the basename of the
		 * plugin passed to uninstall_plugin() to create a dynamically-named action.
		 *
		 * @since 2.7.0
		 */
		do_action( "uninstall_{$file}" );
	}
}

View all references View on Trac View on GitHub

Hooks

do_action( ‘pre_uninstall_plugin’, string $plugin, array $uninstallable_plugins )

Fires in uninstall_plugin() immediately before the plugin is uninstalled.

do_action( “uninstall_{$file}” )

Fires in uninstall_plugin() once the plugin has been uninstalled.

Uses Description
plugin_basename()wp-includes/plugin.php

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

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

Calls the callback functions that have been added to an action hook.
add_action()wp-includes/plugin.php

Adds a callback function to an action hook.
update_option()wp-includes/option.php

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

Retrieves an option value based on an option name.

Show 4 moreShow less

Used by Description
delete_plugins()wp-admin/includes/plugin.php

Removes directory and files of a plugin for a list of plugins.

Changelog

Version Description
2.7.0 Introduced.