Uninstall and cleanup hooks in Wordpress - Mini Project: Build & Apply

WordPress Plugin Uninstall and Cleanup Hooks

📖 Scenario: You have created a WordPress plugin that stores some settings and creates a custom database table. Now you want to make sure that when the plugin is uninstalled, all its data is cleaned up properly.

🎯 Goal: Build a WordPress plugin that uses the uninstall hook to remove plugin options and drop the custom database table when the plugin is uninstalled.

📋 What You'll Learn

Create an array called $my_plugin_options with exact keys and values

Create a variable called $table_name with the exact table name

Write a function called my_plugin_uninstall that deletes all options in $my_plugin_options and drops the table $table_name

Register the uninstall hook using register_uninstall_hook with the function my_plugin_uninstall

💡 Why This Matters

🌍 Real World

Plugins often store data in the database. Cleaning up on uninstall prevents leftover clutter and keeps the site clean.

💼 Career

Knowing how to properly use uninstall hooks is essential for WordPress plugin developers to maintain good plugin hygiene and user trust.

1

Setup plugin options and table name

Create an array called $my_plugin_options with these exact keys and values: 'setting_one' => 'value1', 'setting_two' => 'value2'. Also create a variable called $table_name and set it to $wpdb->prefix . 'my_plugin_table'.

Wordpress

<?php
global $wpdb;
# Create $my_plugin_options array and $table_name variable here

Hint

Use array() to create $my_plugin_options and concatenate $wpdb->prefix with the table name for $table_name.

2

Define the uninstall function

Write a function called my_plugin_uninstall that uses global $wpdb. Inside it, loop over $my_plugin_options keys and delete each option using delete_option. Then drop the table $table_name using $wpdb->query with the SQL DROP TABLE IF EXISTS.

Wordpress

 'value1', 'setting_two' => 'value2');
$table_name = $wpdb->prefix . 'my_plugin_table';

# Define function my_plugin_uninstall here

Hint

Use foreach to loop over the keys of $my_plugin_options and call delete_option for each. Use $wpdb->query to drop the table.

3

Register the uninstall hook

Use register_uninstall_hook with __FILE__ and the function name 'my_plugin_uninstall' to register the uninstall cleanup.

Wordpress

 'value1', 'setting_two' => 'value2');
$table_name = $wpdb->prefix . 'my_plugin_table';

function my_plugin_uninstall() {
    global $wpdb;
    global $my_plugin_options, $table_name;
    foreach (array_keys($my_plugin_options) as $option_name) {
        delete_option($option_name);
    }
    $wpdb->query("DROP TABLE IF EXISTS $table_name");
}

# Register uninstall hook here

Hint

Call register_uninstall_hook with __FILE__ and the uninstall function name as a string.

4

Add plugin header comment

Add the WordPress plugin header comment at the top of the file with these exact lines: Plugin Name: My Cleanup Plugin, Description: A plugin that cleans up on uninstall, Version: 1.0, Author: Your Name.

Wordpress

# Add the plugin header comment at the top of the file
 'value1', 'setting_two' => 'value2');
$table_name = $wpdb->prefix . 'my_plugin_table';

function my_plugin_uninstall() {
    global $wpdb;
    global $my_plugin_options, $table_name;
    foreach (array_keys($my_plugin_options) as $option_name) {
        delete_option($option_name);
    }
    $wpdb->query("DROP TABLE IF EXISTS $table_name");
}

register_uninstall_hook(__FILE__, 'my_plugin_uninstall');

Hint

The plugin header comment must be at the very top of the file inside /* ... */.

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