Uninstall and cleanup hooks in Wordpress - Step-by-Step Execution

Concept Flow - Uninstall and cleanup hooks

Plugin Installed

↓

Plugin Activated

↓

Plugin Used

↓

User Chooses to Uninstall

↓

Trigger uninstall.php

↓

Run uninstall hook

↓

Cleanup Database and Files

↓

Plugin Fully Removed

This flow shows how WordPress runs uninstall hooks to clean up plugin data when a user uninstalls a plugin.

Execution Sample

Wordpress

<?php
// uninstall.php
if (!defined('WP_UNINSTALL_PLUGIN')) {
    exit;
}
// Remove options
delete_option('my_plugin_option');
// Remove custom tables
global $wpdb;
$wpdb->query("DROP TABLE IF EXISTS {$wpdb->prefix}my_plugin_table");

This code runs when the plugin is uninstalled to delete saved options and custom database tables.

Execution Table

Step	Action	Check	Result	Effect
1	Check if WP_UNINSTALL_PLUGIN is defined	WP_UNINSTALL_PLUGIN defined?	Yes	Continue uninstall
2	Delete option 'my_plugin_option'	Option exists?	Yes	Option removed from database
3	Drop custom table 'wp_my_plugin_table'	Table exists?	Yes	Table deleted from database
4	Finish uninstall script	No more cleanup	Done	Plugin data fully cleaned

💡 Uninstall script ends after cleaning options and tables

Variable Tracker

Variable	Start	After Step 2	After Step 3	Final
WP_UNINSTALL_PLUGIN	defined	defined	defined	defined
my_plugin_option	exists	deleted	deleted	deleted
wp_my_plugin_table	exists	exists	deleted	deleted

Key Moments - 2 Insights

Why do we check if WP_UNINSTALL_PLUGIN is defined?

This check ensures the uninstall script runs only when WordPress triggers uninstall, preventing direct access. See execution_table step 1.

What happens if the option or table does not exist?

The delete_option and DROP TABLE commands safely do nothing if the data is missing, so uninstall continues without errors. See execution_table steps 2 and 3.

Visual Quiz - 3 Questions

Look at the execution table, what happens at step 2?

A The plugin option is deleted from the database

B The uninstall script exits immediately

C The custom table is dropped

D WP_UNINSTALL_PLUGIN is undefined

💡 Hint

Check the 'Action' and 'Effect' columns in execution_table row 2

At which step does the uninstall script confirm it is running inside WordPress uninstall?

A Step 4

B Step 3

C Step 1

D Step 2

💡 Hint

Look at the 'Check' column in execution_table row 1

If the custom table does not exist, what changes in the execution table?

A Step 2 result changes to 'No'

B Step 3 result changes to 'No', and table is not deleted

C Step 4 is skipped

D Uninstall script exits at step 1

💡 Hint

Refer to execution_table step 3 'Check' and 'Result' columns

Concept Snapshot

WordPress uninstall hooks run when a plugin is removed.
Use uninstall.php with a check for WP_UNINSTALL_PLUGIN.
Delete options and custom tables to clean data.
This prevents leftover data after uninstall.
Always secure uninstall.php from direct access.

Full Transcript

When a WordPress plugin is uninstalled, WordPress runs the uninstall.php script if it exists. This script must check if the constant WP_UNINSTALL_PLUGIN is defined to confirm it is running during uninstall and not accessed directly. The script then deletes plugin options using delete_option and removes custom database tables with SQL DROP TABLE commands. This cleanup ensures no leftover data remains after the plugin is removed. The execution table shows step-by-step how the uninstall script checks conditions and deletes data safely. Variables like WP_UNINSTALL_PLUGIN, plugin options, and tables change state during the process. Key points include the importance of the WP_UNINSTALL_PLUGIN check and safe deletion commands that do nothing if data is missing. The visual quiz tests understanding of these steps and their effects.

Practice

1. What is the main purpose of using register_uninstall_hook in a WordPress plugin?

easy

A. To register a new shortcode for the plugin

B. To add a settings page in the admin dashboard

C. To clean up plugin data when the plugin is deleted

D. To enqueue scripts and styles for the plugin

Solution

1. Step 1: Understand the role of uninstall hooks

   Uninstall hooks are designed to remove all plugin data when the plugin is deleted to keep the site clean.

2. Step 2: Identify the function of register_uninstall_hook

   This function links a cleanup function that runs on plugin deletion to remove options, transients, and custom tables.

3. Final Answer:

   To clean up plugin data when the plugin is deleted -> Option C

4. Quick Check:

   Uninstall hook purpose = clean up data [OK]

Hint: Uninstall hooks remove plugin data on deletion [OK]

Common Mistakes:

• Confusing uninstall hooks with activation hooks
• Thinking uninstall hooks add features instead of cleaning
• Using uninstall hook to enqueue scripts

2. Which of the following is the correct way to register an uninstall hook in a WordPress plugin?

easy

A. register_activation_hook(__FILE__, 'my_cleanup_function');

B. add_action('uninstall_plugin', 'my_cleanup_function');

C. add_filter('uninstall_hook', 'my_cleanup_function');

D. register_uninstall_hook(__FILE__, 'my_cleanup_function');

Solution

1. Step 1: Recall the correct function for uninstall hooks

   The correct function to register an uninstall hook is register_uninstall_hook with the plugin file and cleanup function.

2. Step 2: Check the syntax of each option

   register_uninstall_hook(__FILE__, 'my_cleanup_function'); uses the correct function and parameters. Options A, B, and D use incorrect functions or hooks.

3. Final Answer:

   register_uninstall_hook(__FILE__, 'my_cleanup_function'); -> Option D

4. Quick Check:

   Correct uninstall hook syntax = register_uninstall_hook(__FILE__, 'my_cleanup_function'); [OK]

Hint: Use register_uninstall_hook with __FILE__ and function name [OK]

Common Mistakes:

• Using activation hook instead of uninstall hook
• Using add_action with wrong hook name
• Confusing filters with hooks

3. Consider this uninstall function in a plugin:

function cleanup_plugin() {
  delete_option('plugin_setting');
  delete_transient('plugin_cache');
  global $wpdb;
  $wpdb->query("DROP TABLE IF EXISTS {$wpdb->prefix}plugin_data");
}

What will happen when the plugin is uninstalled?

medium

A. All plugin data including options, transients, and custom tables will be removed

B. Only the option 'plugin_setting' will be deleted

C. The transient 'plugin_cache' will be deleted but the table remains

D. Nothing will be deleted because uninstall hooks do not run functions

Solution

1. Step 1: Analyze the cleanup function actions

   The function deletes an option, a transient, and drops a custom database table using SQL.

2. Step 2: Understand uninstall hook behavior

   When the uninstall hook calls this function, all these cleanup actions will run, removing all plugin data.

3. Final Answer:

   All plugin data including options, transients, and custom tables will be removed -> Option A

4. Quick Check:

   Cleanup function deletes all data = All plugin data including options, transients, and custom tables will be removed [OK]

Hint: Cleanup function removes all data types explicitly [OK]

Common Mistakes:

• Assuming uninstall hooks do not run cleanup functions
• Thinking only options or transients are deleted
• Ignoring the SQL DROP TABLE command

4. Identify the error in this uninstall hook registration:

register_uninstall_hook('my-plugin/my-plugin.php', 'cleanup_plugin');

function cleanup_plugin() {
  delete_option('my_plugin_option');
}

medium

A. The plugin file path should use __FILE__ instead of a string

B. The cleanup function name must be prefixed with 'uninstall_'

C. delete_option cannot be used in uninstall functions

D. The uninstall hook must be registered inside the cleanup function

Solution

1. Step 1: Check the first parameter of register_uninstall_hook

   The first parameter should be the plugin main file path, usually passed as __FILE__ for reliability.

2. Step 2: Understand why using a string path is problematic

   Using a string path can cause the hook not to trigger if the path is incorrect or changes; __FILE__ ensures correct reference.

3. Final Answer:

   The plugin file path should use __FILE__ instead of a string -> Option A

4. Quick Check:

   Use __FILE__ for plugin path in uninstall hook [OK]

Hint: Always use __FILE__ for plugin path in uninstall hook [OK]

Common Mistakes:

• Using string path instead of __FILE__
• Thinking function name must have uninstall prefix
• Registering hook inside cleanup function

5. You want to ensure your plugin cleans up all its data on uninstall, including options, transients, and a custom table named wp_custom_data. Which of the following uninstall functions correctly performs this cleanup?

hard

A. function uninstall_plugin() {
delete_option('plugin_option');
delete_transient('plugin_transient');
global $wpdb;
$wpdb->query("DROP TABLE wp_custom_data");
}

B. function uninstall_plugin() {
delete_option('plugin_option');
delete_transient('plugin_transient');
global $wpdb;
$wpdb->query("DROP TABLE IF EXISTS wp_custom_data");
}

C. function uninstall_plugin() {
delete_option('plugin_option');
delete_transient('plugin_transient');
global $wpdb;
$wpdb->query("DELETE FROM wp_custom_data");
}

D. function uninstall_plugin() {
delete_option('plugin_option');
delete_transient('plugin_transient');
}

Solution

1. Step 1: Review each cleanup action

   function uninstall_plugin() { delete_option('plugin_option'); delete_transient('plugin_transient'); global $wpdb; $wpdb->query("DROP TABLE IF EXISTS wp_custom_data"); } deletes the option, transient, and drops the custom table safely using IF EXISTS.

2. Step 2: Compare with other options

   function uninstall_plugin() { delete_option('plugin_option'); delete_transient('plugin_transient'); global $wpdb; $wpdb->query("DROP TABLE wp_custom_data"); } drops table without IF EXISTS (may cause error if table missing). function uninstall_plugin() { delete_option('plugin_option'); delete_transient('plugin_transient'); global $wpdb; $wpdb->query("DELETE FROM wp_custom_data"); } deletes rows but not table. function uninstall_plugin() { delete_option('plugin_option'); delete_transient('plugin_transient'); } misses table cleanup.

3. Final Answer:

   function uninstall_plugin() { delete_option('plugin_option'); delete_transient('plugin_transient'); global $wpdb; $wpdb->query("DROP TABLE IF EXISTS wp_custom_data"); } -> Option B

4. Quick Check:

   Safe drop table + delete option and transient = function uninstall_plugin() { delete_option('plugin_option'); delete_transient('plugin_transient'); global $wpdb; $wpdb->query("DROP TABLE IF EXISTS wp_custom_data"); } [OK]

Hint: Use DROP TABLE IF EXISTS to safely remove custom tables [OK]

Common Mistakes:

• Dropping table without IF EXISTS causing errors
• Deleting rows instead of dropping table
• Forgetting to remove custom tables