@mytechtoday/augment-extensions 0.5.0 → 1.2.0

package/augment-extensions/domain-rules/wordpress-plugin/rules/activation-hooks.md

@@ -1,770 +1,770 @@
-# WordPress Plugin Activation, Deactivation, and Uninstall Hooks
-
-## Overview
-
-This document covers the proper implementation of plugin lifecycle hooks: activation, deactivation, and uninstall. These hooks are critical for setting up plugin requirements, cleaning up data, and ensuring a smooth user experience.
-
----
-
-## Activation Hook
-
-### Purpose
-
-The activation hook runs **once** when the plugin is activated. Use it to:
-
-- Create custom database tables
-- Add default options
-- Set up capabilities/roles
-- Schedule cron events
-- Flush rewrite rules
-- Check system requirements
-
-### Basic Implementation
-
-```php
-<?php
-/**
- * Plugin Name: My Plugin
- */
-
-// Register activation hook
-register_activation_hook(__FILE__, 'my_plugin_activate');
-
-function my_plugin_activate() {
-    // Activation code here
-    
-    // Example: Add default options
-    add_option('my_plugin_version', '1.0.0');
-    add_option('my_plugin_settings', array(
-        'enabled' => true,
-        'api_key' => ''
-    ));
-    
-    // Flush rewrite rules
-    flush_rewrite_rules();
-}
-```
-
-### Object-Oriented Implementation
-
-```php
-<?php
-class My_Plugin_Activator {
-    public static function activate() {
-        self::create_tables();
-        self::add_default_options();
-        self::add_capabilities();
-        self::schedule_cron();
-        
-        // Store activation timestamp
-        update_option('my_plugin_activated_time', time());
-    }
-    
-    private static function create_tables() {
-        global $wpdb;
-        $table_name = $wpdb->prefix . 'my_plugin_data';
-        $charset_collate = $wpdb->get_charset_collate();
-        
-        $sql = "CREATE TABLE $table_name (
-            id mediumint(9) NOT NULL AUTO_INCREMENT,
-            name varchar(100) NOT NULL,
-            data text NOT NULL,
-            created_at datetime DEFAULT CURRENT_TIMESTAMP,
-            PRIMARY KEY  (id)
-        ) $charset_collate;";
-        
-        require_once(ABSPATH . 'wp-admin/includes/upgrade.php');
-        dbDelta($sql);
-    }
-    
-    private static function add_default_options() {
-        $defaults = array(
-            'my_plugin_version' => '1.0.0',
-            'my_plugin_settings' => array(
-                'enabled' => true,
-                'items_per_page' => 10
-            )
-        );
-        
-        foreach ($defaults as $key => $value) {
-            add_option($key, $value);
-        }
-    }
-    
-    private static function add_capabilities() {
-        $role = get_role('administrator');
-        if ($role) {
-            $role->add_cap('manage_my_plugin');
-            $role->add_cap('edit_my_plugin_items');
-        }
-    }
-    
-    private static function schedule_cron() {
-        if (!wp_next_scheduled('my_plugin_daily_task')) {
-            wp_schedule_event(time(), 'daily', 'my_plugin_daily_task');
-        }
-    }
-}
-
-// Register hook
-register_activation_hook(__FILE__, array('My_Plugin_Activator', 'activate'));
-```
-
-### System Requirements Check
-
-```php
-<?php
-function my_plugin_activate() {
-    // Check PHP version
-    if (version_compare(PHP_VERSION, '7.4', '<')) {
-        deactivate_plugins(plugin_basename(__FILE__));
-        wp_die('This plugin requires PHP 7.4 or higher.');
-    }
-    
-    // Check WordPress version
-    global $wp_version;
-    if (version_compare($wp_version, '5.8', '<')) {
-        deactivate_plugins(plugin_basename(__FILE__));
-        wp_die('This plugin requires WordPress 5.8 or higher.');
-    }
-    
-    // Check for required plugins
-    if (!is_plugin_active('woocommerce/woocommerce.php')) {
-        deactivate_plugins(plugin_basename(__FILE__));
-        wp_die('This plugin requires WooCommerce to be installed and activated.');
-    }
-    
-    // Check for required PHP extensions
-    if (!extension_loaded('curl')) {
-        deactivate_plugins(plugin_basename(__FILE__));
-        wp_die('This plugin requires the PHP cURL extension.');
-    }
-    
-    // All checks passed - proceed with activation
-    my_plugin_setup();
-}
-```
-
-### Multisite Activation
-
-```php
-<?php
-function my_plugin_activate($network_wide) {
-    if (is_multisite() && $network_wide) {
-        // Network activation
-        global $wpdb;
-        
-        // Get all blog IDs
-        $blog_ids = $wpdb->get_col("SELECT blog_id FROM $wpdb->blogs");
-        
-        foreach ($blog_ids as $blog_id) {
-            switch_to_blog($blog_id);
-            my_plugin_activate_single_site();
-            restore_current_blog();
-        }
-    } else {
-        // Single site activation
-        my_plugin_activate_single_site();
-    }
-}
-
-function my_plugin_activate_single_site() {
-    // Activation code for single site
-    add_option('my_plugin_version', '1.0.0');
-}
-
-register_activation_hook(__FILE__, 'my_plugin_activate');
-```
-
----
-
-## Deactivation Hook
-
-### Purpose
-
-The deactivation hook runs when the plugin is deactivated. Use it to:
-
-- Clear scheduled cron events
-- Flush rewrite rules
-- Clear transients/caches
-- **DO NOT** delete user data or options
-
-### Basic Implementation
-
-```php
-<?php
-register_deactivation_hook(__FILE__, 'my_plugin_deactivate');
-
-function my_plugin_deactivate() {
-    // Clear scheduled events
-    $timestamp = wp_next_scheduled('my_plugin_daily_task');
-    if ($timestamp) {
-        wp_unschedule_event($timestamp, 'my_plugin_daily_task');
-    }
-    
-    // Flush rewrite rules
-    flush_rewrite_rules();
-    
-    // Clear transients
-    delete_transient('my_plugin_cache');
-}
-```
-
-### Object-Oriented Implementation
-
-```php
-<?php
-class My_Plugin_Deactivator {
-    public static function deactivate() {
-        self::clear_cron_jobs();
-        self::flush_cache();
-        self::flush_rewrite_rules();
-        
-        // Log deactivation
-        update_option('my_plugin_deactivated_time', time());
-    }
-    
-    private static function clear_cron_jobs() {
-        $cron_hooks = array(
-            'my_plugin_daily_task',
-            'my_plugin_hourly_task',
-            'my_plugin_cleanup_task'
-        );
-
-        foreach ($cron_hooks as $hook) {
-            $timestamp = wp_next_scheduled($hook);
-            if ($timestamp) {
-                wp_unschedule_event($timestamp, $hook);
-            }
-        }
-    }
-
-    private static function flush_cache() {
-        // Delete transients
-        delete_transient('my_plugin_cache');
-        delete_transient('my_plugin_api_response');
-
-        // Clear object cache
-        wp_cache_flush();
-    }
-
-    private static function flush_rewrite_rules() {
-        flush_rewrite_rules();
-    }
-}
-
-register_deactivation_hook(__FILE__, array('My_Plugin_Deactivator', 'deactivate'));
-```
-
-### What NOT to Do on Deactivation
-
-❌ **DO NOT** delete user data
-❌ **DO NOT** delete options/settings
-❌ **DO NOT** drop database tables
-❌ **DO NOT** remove user capabilities
-
-**Reason**: Users may reactivate the plugin and expect their data to be intact.
-
----
-
-## Uninstall Hook
-
-### Purpose
-
-The uninstall hook runs when the plugin is **deleted** (not just deactivated). Use it to:
-
-- Delete all plugin options
-- Drop custom database tables
-- Remove custom capabilities
-- Delete uploaded files
-- Clean up everything
-
-### Method 1: uninstall.php (Recommended)
-
-Create a file named `uninstall.php` in the plugin root:
-
-```php
-<?php
-/**
- * Uninstall script
- *
- * Runs when plugin is deleted via WordPress admin
- */
-
-// Exit if accessed directly
-if (!defined('WP_UNINSTALL_PLUGIN')) {
-    exit;
-}
-
-// Delete options
-delete_option('my_plugin_version');
-delete_option('my_plugin_settings');
-delete_option('my_plugin_activated_time');
-delete_option('my_plugin_deactivated_time');
-
-// Delete transients
-delete_transient('my_plugin_cache');
-
-// Drop custom tables
-global $wpdb;
-$table_name = $wpdb->prefix . 'my_plugin_data';
-$wpdb->query("DROP TABLE IF EXISTS $table_name");
-
-// Remove capabilities
-$role = get_role('administrator');
-if ($role) {
-    $role->remove_cap('manage_my_plugin');
-    $role->remove_cap('edit_my_plugin_items');
-}
-
-// Delete uploaded files
-$upload_dir = wp_upload_dir();
-$plugin_upload_dir = $upload_dir['basedir'] . '/my-plugin';
-if (is_dir($plugin_upload_dir)) {
-    // Recursively delete directory
-    array_map('unlink', glob("$plugin_upload_dir/*.*"));
-    rmdir($plugin_upload_dir);
-}
-
-// Clear scheduled events (if any remain)
-wp_clear_scheduled_hook('my_plugin_daily_task');
-```
-
-### Method 2: register_uninstall_hook()
-
-```php
-<?php
-/**
- * Plugin Name: My Plugin
- */
-
-// Register uninstall hook
-register_uninstall_hook(__FILE__, 'my_plugin_uninstall');
-
-function my_plugin_uninstall() {
-    // Uninstall code here
-    delete_option('my_plugin_version');
-    delete_option('my_plugin_settings');
-
-    global $wpdb;
-    $table_name = $wpdb->prefix . 'my_plugin_data';
-    $wpdb->query("DROP TABLE IF EXISTS $table_name");
-}
-```
-
-### Object-Oriented Uninstall (uninstall.php)
-
-```php
-<?php
-if (!defined('WP_UNINSTALL_PLUGIN')) {
-    exit;
-}
-
-// Load plugin classes
-require_once plugin_dir_path(__FILE__) . 'includes/class-uninstaller.php';
-
-// Run uninstall
-My_Plugin_Uninstaller::uninstall();
-```
-
-**Uninstaller Class** (`includes/class-uninstaller.php`):
-
-```php
-<?php
-class My_Plugin_Uninstaller {
-    public static function uninstall() {
-        self::delete_options();
-        self::delete_transients();
-        self::drop_tables();
-        self::remove_capabilities();
-        self::delete_files();
-        self::clear_cron();
-    }
-
-    private static function delete_options() {
-        $options = array(
-            'my_plugin_version',
-            'my_plugin_settings',
-            'my_plugin_activated_time',
-            'my_plugin_deactivated_time'
-        );
-
-        foreach ($options as $option) {
-            delete_option($option);
-        }
-    }
-
-    private static function delete_transients() {
-        global $wpdb;
-
-        // Delete all transients with plugin prefix
-        $wpdb->query(
-            "DELETE FROM $wpdb->options
-             WHERE option_name LIKE '_transient_my_plugin_%'
-             OR option_name LIKE '_transient_timeout_my_plugin_%'"
-        );
-    }
-
-    private static function drop_tables() {
-        global $wpdb;
-
-        $tables = array(
-            $wpdb->prefix . 'my_plugin_data',
-            $wpdb->prefix . 'my_plugin_logs'
-        );
-
-        foreach ($tables as $table) {
-            $wpdb->query("DROP TABLE IF EXISTS $table");
-        }
-    }
-
-    private static function remove_capabilities() {
-        $capabilities = array(
-            'manage_my_plugin',
-            'edit_my_plugin_items',
-            'delete_my_plugin_items'
-        );
-
-        $roles = array('administrator', 'editor');
-
-        foreach ($roles as $role_name) {
-            $role = get_role($role_name);
-            if ($role) {
-                foreach ($capabilities as $cap) {
-                    $role->remove_cap($cap);
-                }
-            }
-        }
-    }
-
-    private static function delete_files() {
-        $upload_dir = wp_upload_dir();
-        $plugin_dir = $upload_dir['basedir'] . '/my-plugin';
-
-        if (is_dir($plugin_dir)) {
-            self::delete_directory($plugin_dir);
-        }
-    }
-
-    private static function delete_directory($dir) {
-        if (!is_dir($dir)) {
-            return;
-        }
-
-        $files = array_diff(scandir($dir), array('.', '..'));
-
-        foreach ($files as $file) {
-            $path = $dir . '/' . $file;
-            is_dir($path) ? self::delete_directory($path) : unlink($path);
-        }
-
-        rmdir($dir);
-    }
-
-    private static function clear_cron() {
-        wp_clear_scheduled_hook('my_plugin_daily_task');
-        wp_clear_scheduled_hook('my_plugin_hourly_task');
-    }
-}
-```
-
-### Multisite Uninstall
-
-```php
-<?php
-if (!defined('WP_UNINSTALL_PLUGIN')) {
-    exit;
-}
-
-if (is_multisite()) {
-    global $wpdb;
-
-    // Get all blog IDs
-    $blog_ids = $wpdb->get_col("SELECT blog_id FROM $wpdb->blogs");
-
-    foreach ($blog_ids as $blog_id) {
-        switch_to_blog($blog_id);
-        my_plugin_uninstall_single_site();
-        restore_current_blog();
-    }
-
-    // Delete network-wide options
-    delete_site_option('my_plugin_network_settings');
-} else {
-    my_plugin_uninstall_single_site();
-}
-
-function my_plugin_uninstall_single_site() {
-    // Delete options
-    delete_option('my_plugin_version');
-    delete_option('my_plugin_settings');
-
-    // Drop tables
-    global $wpdb;
-    $table_name = $wpdb->prefix . 'my_plugin_data';
-    $wpdb->query("DROP TABLE IF EXISTS $table_name");
-}
-```
-
----
-
-## Database Table Management
-
-### Creating Tables (Activation)
-
-```php
-<?php
-function my_plugin_create_tables() {
-    global $wpdb;
-
-    $table_name = $wpdb->prefix . 'my_plugin_data';
-    $charset_collate = $wpdb->get_charset_collate();
-
-    $sql = "CREATE TABLE $table_name (
-        id bigint(20) unsigned NOT NULL AUTO_INCREMENT,
-        user_id bigint(20) unsigned NOT NULL,
-        title varchar(255) NOT NULL,
-        content longtext NOT NULL,
-        status varchar(20) DEFAULT 'draft',
-        created_at datetime DEFAULT CURRENT_TIMESTAMP,
-        updated_at datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
-        PRIMARY KEY  (id),
-        KEY user_id (user_id),
-        KEY status (status)
-    ) $charset_collate;";
-
-    require_once(ABSPATH . 'wp-admin/includes/upgrade.php');
-    dbDelta($sql);
-
-    // Store database version
-    add_option('my_plugin_db_version', '1.0');
-}
-```
-
-### Updating Tables (Version Check)
-
-```php
-<?php
-function my_plugin_update_db_check() {
-    $current_version = get_option('my_plugin_db_version', '0');
-    $new_version = '1.1';
-
-    if (version_compare($current_version, $new_version, '<')) {
-        my_plugin_update_tables();
-        update_option('my_plugin_db_version', $new_version);
-    }
-}
-add_action('plugins_loaded', 'my_plugin_update_db_check');
-
-function my_plugin_update_tables() {
-    global $wpdb;
-
-    $table_name = $wpdb->prefix . 'my_plugin_data';
-
-    // Add new column
-    $wpdb->query("ALTER TABLE $table_name ADD COLUMN new_field varchar(100) DEFAULT NULL");
-}
-```
-
----
-
-## Best Practices
-
-### Activation
-
-✅ Check system requirements (PHP, WordPress, extensions)
-✅ Create database tables using `dbDelta()`
-✅ Add default options with `add_option()` (not `update_option()`)
-✅ Flush rewrite rules if registering custom post types/taxonomies
-✅ Schedule cron events
-✅ Store activation timestamp
-✅ Check for multisite and handle accordingly
-
-### Deactivation
-
-✅ Clear scheduled cron events
-✅ Flush rewrite rules
-✅ Clear transients and caches
-❌ **DO NOT** delete user data
-❌ **DO NOT** delete options
-❌ **DO NOT** drop tables
-
-### Uninstall
-
-✅ Use `uninstall.php` (preferred) or `register_uninstall_hook()`
-✅ Delete ALL plugin options
-✅ Drop ALL custom tables
-✅ Remove ALL capabilities
-✅ Delete ALL uploaded files
-✅ Clear ALL scheduled events
-✅ Handle multisite properly
-✅ Be thorough - leave no trace
-
----
-
-## Common Patterns
-
-### Version-Based Activation
-
-```php
-<?php
-function my_plugin_activate() {
-    $current_version = get_option('my_plugin_version', '0');
-    $new_version = '2.0.0';
-
-    if (version_compare($current_version, $new_version, '<')) {
-        // Upgrade from older version
-        my_plugin_upgrade($current_version, $new_version);
-    } else {
-        // Fresh install
-        my_plugin_fresh_install();
-    }
-
-    update_option('my_plugin_version', $new_version);
-}
-
-function my_plugin_upgrade($from, $to) {
-    // Migration logic
-    if (version_compare($from, '1.5.0', '<')) {
-        // Migrate from < 1.5.0
-    }
-
-    if (version_compare($from, '2.0.0', '<')) {
-        // Migrate from < 2.0.0
-    }
-}
-
-function my_plugin_fresh_install() {
-    // Fresh installation logic
-    my_plugin_create_tables();
-    my_plugin_add_default_options();
-}
-```
-
-### Conditional Uninstall
-
-```php
-<?php
-// uninstall.php
-
-if (!defined('WP_UNINSTALL_PLUGIN')) {
-    exit;
-}
-
-// Check if user wants to keep data
-$keep_data = get_option('my_plugin_keep_data_on_uninstall', false);
-
-if (!$keep_data) {
-    // Delete everything
-    delete_option('my_plugin_version');
-    delete_option('my_plugin_settings');
-
-    global $wpdb;
-    $wpdb->query("DROP TABLE IF EXISTS {$wpdb->prefix}my_plugin_data");
-} else {
-    // Keep data, just mark as uninstalled
-    update_option('my_plugin_uninstalled', true);
-}
-```
-
----
-
-## Security Considerations
-
-### Activation
-
-✅ Verify user capabilities before activation
-✅ Validate system requirements
-✅ Use nonces for AJAX activation
-✅ Sanitize any user input during activation
-
-### Uninstall
-
-✅ Check `WP_UNINSTALL_PLUGIN` constant
-✅ Verify user has permission to delete plugins
-✅ Use `$wpdb->prepare()` for database queries
-✅ Validate file paths before deletion
-
----
-
-## Testing
-
-### Test Activation
-
-```php
-<?php
-// Test activation in different scenarios
-function test_my_plugin_activation() {
-    // Test fresh install
-    delete_option('my_plugin_version');
-    my_plugin_activate();
-    assert(get_option('my_plugin_version') === '1.0.0');
-
-    // Test upgrade
-    update_option('my_plugin_version', '0.9.0');
-    my_plugin_activate();
-    assert(get_option('my_plugin_version') === '1.0.0');
-}
-```
-
-### Test Uninstall
-
-```php
-<?php
-// Test uninstall cleanup
-function test_my_plugin_uninstall() {
-    // Activate plugin
-    my_plugin_activate();
-
-    // Verify data exists
-    assert(get_option('my_plugin_version') !== false);
-
-    // Uninstall
-    require_once 'uninstall.php';
-
-    // Verify cleanup
-    assert(get_option('my_plugin_version') === false);
-
-    global $wpdb;
-    $table_exists = $wpdb->get_var(
-        "SHOW TABLES LIKE '{$wpdb->prefix}my_plugin_data'"
-    );
-    assert($table_exists === null);
-}
-```
-
----
-
-## Troubleshooting
-
-### Activation Errors
-
-**Problem**: Plugin activates but doesn't create tables
-**Solution**: Check `dbDelta()` syntax, ensure `upgrade.php` is included
-
-**Problem**: Activation fails silently
-**Solution**: Enable `WP_DEBUG` and check error logs
-
-**Problem**: Multisite activation doesn't work
-**Solution**: Check `$network_wide` parameter and use `switch_to_blog()`
-
-### Uninstall Issues
-
-**Problem**: `uninstall.php` doesn't run
-**Solution**: Ensure file is in plugin root, check `WP_UNINSTALL_PLUGIN` constant
-
-**Problem**: Data not fully deleted
-**Solution**: Check for site-specific options in multisite, verify table names
-
----
-
-## Summary
-
-| Hook | When | Purpose | Delete Data? |
-|------|------|---------|--------------|
-| Activation | Plugin activated | Setup, create tables, add options | No |
-| Deactivation | Plugin deactivated | Clear caches, unschedule cron | **NO** |
-| Uninstall | Plugin deleted | Complete cleanup | **YES** |
-
-**Golden Rule**: Only delete user data during uninstall, never during deactivation.
-
+# WordPress Plugin Activation, Deactivation, and Uninstall Hooks
+
+## Overview
+
+This document covers the proper implementation of plugin lifecycle hooks: activation, deactivation, and uninstall. These hooks are critical for setting up plugin requirements, cleaning up data, and ensuring a smooth user experience.
+
+---
+
+## Activation Hook
+
+### Purpose
+
+The activation hook runs **once** when the plugin is activated. Use it to:
+
+- Create custom database tables
+- Add default options
+- Set up capabilities/roles
+- Schedule cron events
+- Flush rewrite rules
+- Check system requirements
+
+### Basic Implementation
+
+```php
+<?php
+/**
+ * Plugin Name: My Plugin
+ */
+
+// Register activation hook
+register_activation_hook(__FILE__, 'my_plugin_activate');
+
+function my_plugin_activate() {
+    // Activation code here
+    
+    // Example: Add default options
+    add_option('my_plugin_version', '1.0.0');
+    add_option('my_plugin_settings', array(
+        'enabled' => true,
+        'api_key' => ''
+    ));
+    
+    // Flush rewrite rules
+    flush_rewrite_rules();
+}
+```
+
+### Object-Oriented Implementation
+
+```php
+<?php
+class My_Plugin_Activator {
+    public static function activate() {
+        self::create_tables();
+        self::add_default_options();
+        self::add_capabilities();
+        self::schedule_cron();
+        
+        // Store activation timestamp
+        update_option('my_plugin_activated_time', time());
+    }
+    
+    private static function create_tables() {
+        global $wpdb;
+        $table_name = $wpdb->prefix . 'my_plugin_data';
+        $charset_collate = $wpdb->get_charset_collate();
+        
+        $sql = "CREATE TABLE $table_name (
+            id mediumint(9) NOT NULL AUTO_INCREMENT,
+            name varchar(100) NOT NULL,
+            data text NOT NULL,
+            created_at datetime DEFAULT CURRENT_TIMESTAMP,
+            PRIMARY KEY  (id)
+        ) $charset_collate;";
+        
+        require_once(ABSPATH . 'wp-admin/includes/upgrade.php');
+        dbDelta($sql);
+    }
+    
+    private static function add_default_options() {
+        $defaults = array(
+            'my_plugin_version' => '1.0.0',
+            'my_plugin_settings' => array(
+                'enabled' => true,
+                'items_per_page' => 10
+            )
+        );
+        
+        foreach ($defaults as $key => $value) {
+            add_option($key, $value);
+        }
+    }
+    
+    private static function add_capabilities() {
+        $role = get_role('administrator');
+        if ($role) {
+            $role->add_cap('manage_my_plugin');
+            $role->add_cap('edit_my_plugin_items');
+        }
+    }
+    
+    private static function schedule_cron() {
+        if (!wp_next_scheduled('my_plugin_daily_task')) {
+            wp_schedule_event(time(), 'daily', 'my_plugin_daily_task');
+        }
+    }
+}
+
+// Register hook
+register_activation_hook(__FILE__, array('My_Plugin_Activator', 'activate'));
+```
+
+### System Requirements Check
+
+```php
+<?php
+function my_plugin_activate() {
+    // Check PHP version
+    if (version_compare(PHP_VERSION, '7.4', '<')) {
+        deactivate_plugins(plugin_basename(__FILE__));
+        wp_die('This plugin requires PHP 7.4 or higher.');
+    }
+    
+    // Check WordPress version
+    global $wp_version;
+    if (version_compare($wp_version, '5.8', '<')) {
+        deactivate_plugins(plugin_basename(__FILE__));
+        wp_die('This plugin requires WordPress 5.8 or higher.');
+    }
+    
+    // Check for required plugins
+    if (!is_plugin_active('woocommerce/woocommerce.php')) {
+        deactivate_plugins(plugin_basename(__FILE__));
+        wp_die('This plugin requires WooCommerce to be installed and activated.');
+    }
+    
+    // Check for required PHP extensions
+    if (!extension_loaded('curl')) {
+        deactivate_plugins(plugin_basename(__FILE__));
+        wp_die('This plugin requires the PHP cURL extension.');
+    }
+    
+    // All checks passed - proceed with activation
+    my_plugin_setup();
+}
+```
+
+### Multisite Activation
+
+```php
+<?php
+function my_plugin_activate($network_wide) {
+    if (is_multisite() && $network_wide) {
+        // Network activation
+        global $wpdb;
+        
+        // Get all blog IDs
+        $blog_ids = $wpdb->get_col("SELECT blog_id FROM $wpdb->blogs");
+        
+        foreach ($blog_ids as $blog_id) {
+            switch_to_blog($blog_id);
+            my_plugin_activate_single_site();
+            restore_current_blog();
+        }
+    } else {
+        // Single site activation
+        my_plugin_activate_single_site();
+    }
+}
+
+function my_plugin_activate_single_site() {
+    // Activation code for single site
+    add_option('my_plugin_version', '1.0.0');
+}
+
+register_activation_hook(__FILE__, 'my_plugin_activate');
+```
+
+---
+
+## Deactivation Hook
+
+### Purpose
+
+The deactivation hook runs when the plugin is deactivated. Use it to:
+
+- Clear scheduled cron events
+- Flush rewrite rules
+- Clear transients/caches
+- **DO NOT** delete user data or options
+
+### Basic Implementation
+
+```php
+<?php
+register_deactivation_hook(__FILE__, 'my_plugin_deactivate');
+
+function my_plugin_deactivate() {
+    // Clear scheduled events
+    $timestamp = wp_next_scheduled('my_plugin_daily_task');
+    if ($timestamp) {
+        wp_unschedule_event($timestamp, 'my_plugin_daily_task');
+    }
+    
+    // Flush rewrite rules
+    flush_rewrite_rules();
+    
+    // Clear transients
+    delete_transient('my_plugin_cache');
+}
+```
+
+### Object-Oriented Implementation
+
+```php
+<?php
+class My_Plugin_Deactivator {
+    public static function deactivate() {
+        self::clear_cron_jobs();
+        self::flush_cache();
+        self::flush_rewrite_rules();
+        
+        // Log deactivation
+        update_option('my_plugin_deactivated_time', time());
+    }
+    
+    private static function clear_cron_jobs() {
+        $cron_hooks = array(
+            'my_plugin_daily_task',
+            'my_plugin_hourly_task',
+            'my_plugin_cleanup_task'
+        );
+
+        foreach ($cron_hooks as $hook) {
+            $timestamp = wp_next_scheduled($hook);
+            if ($timestamp) {
+                wp_unschedule_event($timestamp, $hook);
+            }
+        }
+    }
+
+    private static function flush_cache() {
+        // Delete transients
+        delete_transient('my_plugin_cache');
+        delete_transient('my_plugin_api_response');
+
+        // Clear object cache
+        wp_cache_flush();
+    }
+
+    private static function flush_rewrite_rules() {
+        flush_rewrite_rules();
+    }
+}
+
+register_deactivation_hook(__FILE__, array('My_Plugin_Deactivator', 'deactivate'));
+```
+
+### What NOT to Do on Deactivation
+
+❌ **DO NOT** delete user data
+❌ **DO NOT** delete options/settings
+❌ **DO NOT** drop database tables
+❌ **DO NOT** remove user capabilities
+
+**Reason**: Users may reactivate the plugin and expect their data to be intact.
+
+---
+
+## Uninstall Hook
+
+### Purpose
+
+The uninstall hook runs when the plugin is **deleted** (not just deactivated). Use it to:
+
+- Delete all plugin options
+- Drop custom database tables
+- Remove custom capabilities
+- Delete uploaded files
+- Clean up everything
+
+### Method 1: uninstall.php (Recommended)
+
+Create a file named `uninstall.php` in the plugin root:
+
+```php
+<?php
+/**
+ * Uninstall script
+ *
+ * Runs when plugin is deleted via WordPress admin
+ */
+
+// Exit if accessed directly
+if (!defined('WP_UNINSTALL_PLUGIN')) {
+    exit;
+}
+
+// Delete options
+delete_option('my_plugin_version');
+delete_option('my_plugin_settings');
+delete_option('my_plugin_activated_time');
+delete_option('my_plugin_deactivated_time');
+
+// Delete transients
+delete_transient('my_plugin_cache');
+
+// Drop custom tables
+global $wpdb;
+$table_name = $wpdb->prefix . 'my_plugin_data';
+$wpdb->query("DROP TABLE IF EXISTS $table_name");
+
+// Remove capabilities
+$role = get_role('administrator');
+if ($role) {
+    $role->remove_cap('manage_my_plugin');
+    $role->remove_cap('edit_my_plugin_items');
+}
+
+// Delete uploaded files
+$upload_dir = wp_upload_dir();
+$plugin_upload_dir = $upload_dir['basedir'] . '/my-plugin';
+if (is_dir($plugin_upload_dir)) {
+    // Recursively delete directory
+    array_map('unlink', glob("$plugin_upload_dir/*.*"));
+    rmdir($plugin_upload_dir);
+}
+
+// Clear scheduled events (if any remain)
+wp_clear_scheduled_hook('my_plugin_daily_task');
+```
+
+### Method 2: register_uninstall_hook()
+
+```php
+<?php
+/**
+ * Plugin Name: My Plugin
+ */
+
+// Register uninstall hook
+register_uninstall_hook(__FILE__, 'my_plugin_uninstall');
+
+function my_plugin_uninstall() {
+    // Uninstall code here
+    delete_option('my_plugin_version');
+    delete_option('my_plugin_settings');
+
+    global $wpdb;
+    $table_name = $wpdb->prefix . 'my_plugin_data';
+    $wpdb->query("DROP TABLE IF EXISTS $table_name");
+}
+```
+
+### Object-Oriented Uninstall (uninstall.php)
+
+```php
+<?php
+if (!defined('WP_UNINSTALL_PLUGIN')) {
+    exit;
+}
+
+// Load plugin classes
+require_once plugin_dir_path(__FILE__) . 'includes/class-uninstaller.php';
+
+// Run uninstall
+My_Plugin_Uninstaller::uninstall();
+```
+
+**Uninstaller Class** (`includes/class-uninstaller.php`):
+
+```php
+<?php
+class My_Plugin_Uninstaller {
+    public static function uninstall() {
+        self::delete_options();
+        self::delete_transients();
+        self::drop_tables();
+        self::remove_capabilities();
+        self::delete_files();
+        self::clear_cron();
+    }
+
+    private static function delete_options() {
+        $options = array(
+            'my_plugin_version',
+            'my_plugin_settings',
+            'my_plugin_activated_time',
+            'my_plugin_deactivated_time'
+        );
+
+        foreach ($options as $option) {
+            delete_option($option);
+        }
+    }
+
+    private static function delete_transients() {
+        global $wpdb;
+
+        // Delete all transients with plugin prefix
+        $wpdb->query(
+            "DELETE FROM $wpdb->options
+             WHERE option_name LIKE '_transient_my_plugin_%'
+             OR option_name LIKE '_transient_timeout_my_plugin_%'"
+        );
+    }
+
+    private static function drop_tables() {
+        global $wpdb;
+
+        $tables = array(
+            $wpdb->prefix . 'my_plugin_data',
+            $wpdb->prefix . 'my_plugin_logs'
+        );
+
+        foreach ($tables as $table) {
+            $wpdb->query("DROP TABLE IF EXISTS $table");
+        }
+    }
+
+    private static function remove_capabilities() {
+        $capabilities = array(
+            'manage_my_plugin',
+            'edit_my_plugin_items',
+            'delete_my_plugin_items'
+        );
+
+        $roles = array('administrator', 'editor');
+
+        foreach ($roles as $role_name) {
+            $role = get_role($role_name);
+            if ($role) {
+                foreach ($capabilities as $cap) {
+                    $role->remove_cap($cap);
+                }
+            }
+        }
+    }
+
+    private static function delete_files() {
+        $upload_dir = wp_upload_dir();
+        $plugin_dir = $upload_dir['basedir'] . '/my-plugin';
+
+        if (is_dir($plugin_dir)) {
+            self::delete_directory($plugin_dir);
+        }
+    }
+
+    private static function delete_directory($dir) {
+        if (!is_dir($dir)) {
+            return;
+        }
+
+        $files = array_diff(scandir($dir), array('.', '..'));
+
+        foreach ($files as $file) {
+            $path = $dir . '/' . $file;
+            is_dir($path) ? self::delete_directory($path) : unlink($path);
+        }
+
+        rmdir($dir);
+    }
+
+    private static function clear_cron() {
+        wp_clear_scheduled_hook('my_plugin_daily_task');
+        wp_clear_scheduled_hook('my_plugin_hourly_task');
+    }
+}
+```
+
+### Multisite Uninstall
+
+```php
+<?php
+if (!defined('WP_UNINSTALL_PLUGIN')) {
+    exit;
+}
+
+if (is_multisite()) {
+    global $wpdb;
+
+    // Get all blog IDs
+    $blog_ids = $wpdb->get_col("SELECT blog_id FROM $wpdb->blogs");
+
+    foreach ($blog_ids as $blog_id) {
+        switch_to_blog($blog_id);
+        my_plugin_uninstall_single_site();
+        restore_current_blog();
+    }
+
+    // Delete network-wide options
+    delete_site_option('my_plugin_network_settings');
+} else {
+    my_plugin_uninstall_single_site();
+}
+
+function my_plugin_uninstall_single_site() {
+    // Delete options
+    delete_option('my_plugin_version');
+    delete_option('my_plugin_settings');
+
+    // Drop tables
+    global $wpdb;
+    $table_name = $wpdb->prefix . 'my_plugin_data';
+    $wpdb->query("DROP TABLE IF EXISTS $table_name");
+}
+```
+
+---
+
+## Database Table Management
+
+### Creating Tables (Activation)
+
+```php
+<?php
+function my_plugin_create_tables() {
+    global $wpdb;
+
+    $table_name = $wpdb->prefix . 'my_plugin_data';
+    $charset_collate = $wpdb->get_charset_collate();
+
+    $sql = "CREATE TABLE $table_name (
+        id bigint(20) unsigned NOT NULL AUTO_INCREMENT,
+        user_id bigint(20) unsigned NOT NULL,
+        title varchar(255) NOT NULL,
+        content longtext NOT NULL,
+        status varchar(20) DEFAULT 'draft',
+        created_at datetime DEFAULT CURRENT_TIMESTAMP,
+        updated_at datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+        PRIMARY KEY  (id),
+        KEY user_id (user_id),
+        KEY status (status)
+    ) $charset_collate;";
+
+    require_once(ABSPATH . 'wp-admin/includes/upgrade.php');
+    dbDelta($sql);
+
+    // Store database version
+    add_option('my_plugin_db_version', '1.0');
+}
+```
+
+### Updating Tables (Version Check)
+
+```php
+<?php
+function my_plugin_update_db_check() {
+    $current_version = get_option('my_plugin_db_version', '0');
+    $new_version = '1.1';
+
+    if (version_compare($current_version, $new_version, '<')) {
+        my_plugin_update_tables();
+        update_option('my_plugin_db_version', $new_version);
+    }
+}
+add_action('plugins_loaded', 'my_plugin_update_db_check');
+
+function my_plugin_update_tables() {
+    global $wpdb;
+
+    $table_name = $wpdb->prefix . 'my_plugin_data';
+
+    // Add new column
+    $wpdb->query("ALTER TABLE $table_name ADD COLUMN new_field varchar(100) DEFAULT NULL");
+}
+```
+
+---
+
+## Best Practices
+
+### Activation
+
+✅ Check system requirements (PHP, WordPress, extensions)
+✅ Create database tables using `dbDelta()`
+✅ Add default options with `add_option()` (not `update_option()`)
+✅ Flush rewrite rules if registering custom post types/taxonomies
+✅ Schedule cron events
+✅ Store activation timestamp
+✅ Check for multisite and handle accordingly
+
+### Deactivation
+
+✅ Clear scheduled cron events
+✅ Flush rewrite rules
+✅ Clear transients and caches
+❌ **DO NOT** delete user data
+❌ **DO NOT** delete options
+❌ **DO NOT** drop tables
+
+### Uninstall
+
+✅ Use `uninstall.php` (preferred) or `register_uninstall_hook()`
+✅ Delete ALL plugin options
+✅ Drop ALL custom tables
+✅ Remove ALL capabilities
+✅ Delete ALL uploaded files
+✅ Clear ALL scheduled events
+✅ Handle multisite properly
+✅ Be thorough - leave no trace
+
+---
+
+## Common Patterns
+
+### Version-Based Activation
+
+```php
+<?php
+function my_plugin_activate() {
+    $current_version = get_option('my_plugin_version', '0');
+    $new_version = '2.0.0';
+
+    if (version_compare($current_version, $new_version, '<')) {
+        // Upgrade from older version
+        my_plugin_upgrade($current_version, $new_version);
+    } else {
+        // Fresh install
+        my_plugin_fresh_install();
+    }
+
+    update_option('my_plugin_version', $new_version);
+}
+
+function my_plugin_upgrade($from, $to) {
+    // Migration logic
+    if (version_compare($from, '1.5.0', '<')) {
+        // Migrate from < 1.5.0
+    }
+
+    if (version_compare($from, '2.0.0', '<')) {
+        // Migrate from < 2.0.0
+    }
+}
+
+function my_plugin_fresh_install() {
+    // Fresh installation logic
+    my_plugin_create_tables();
+    my_plugin_add_default_options();
+}
+```
+
+### Conditional Uninstall
+
+```php
+<?php
+// uninstall.php
+
+if (!defined('WP_UNINSTALL_PLUGIN')) {
+    exit;
+}
+
+// Check if user wants to keep data
+$keep_data = get_option('my_plugin_keep_data_on_uninstall', false);
+
+if (!$keep_data) {
+    // Delete everything
+    delete_option('my_plugin_version');
+    delete_option('my_plugin_settings');
+
+    global $wpdb;
+    $wpdb->query("DROP TABLE IF EXISTS {$wpdb->prefix}my_plugin_data");
+} else {
+    // Keep data, just mark as uninstalled
+    update_option('my_plugin_uninstalled', true);
+}
+```
+
+---
+
+## Security Considerations
+
+### Activation
+
+✅ Verify user capabilities before activation
+✅ Validate system requirements
+✅ Use nonces for AJAX activation
+✅ Sanitize any user input during activation
+
+### Uninstall
+
+✅ Check `WP_UNINSTALL_PLUGIN` constant
+✅ Verify user has permission to delete plugins
+✅ Use `$wpdb->prepare()` for database queries
+✅ Validate file paths before deletion
+
+---
+
+## Testing
+
+### Test Activation
+
+```php
+<?php
+// Test activation in different scenarios
+function test_my_plugin_activation() {
+    // Test fresh install
+    delete_option('my_plugin_version');
+    my_plugin_activate();
+    assert(get_option('my_plugin_version') === '1.0.0');
+
+    // Test upgrade
+    update_option('my_plugin_version', '0.9.0');
+    my_plugin_activate();
+    assert(get_option('my_plugin_version') === '1.0.0');
+}
+```
+
+### Test Uninstall
+
+```php
+<?php
+// Test uninstall cleanup
+function test_my_plugin_uninstall() {
+    // Activate plugin
+    my_plugin_activate();
+
+    // Verify data exists
+    assert(get_option('my_plugin_version') !== false);
+
+    // Uninstall
+    require_once 'uninstall.php';
+
+    // Verify cleanup
+    assert(get_option('my_plugin_version') === false);
+
+    global $wpdb;
+    $table_exists = $wpdb->get_var(
+        "SHOW TABLES LIKE '{$wpdb->prefix}my_plugin_data'"
+    );
+    assert($table_exists === null);
+}
+```
+
+---
+
+## Troubleshooting
+
+### Activation Errors
+
+**Problem**: Plugin activates but doesn't create tables
+**Solution**: Check `dbDelta()` syntax, ensure `upgrade.php` is included
+
+**Problem**: Activation fails silently
+**Solution**: Enable `WP_DEBUG` and check error logs
+
+**Problem**: Multisite activation doesn't work
+**Solution**: Check `$network_wide` parameter and use `switch_to_blog()`
+
+### Uninstall Issues
+
+**Problem**: `uninstall.php` doesn't run
+**Solution**: Ensure file is in plugin root, check `WP_UNINSTALL_PLUGIN` constant
+
+**Problem**: Data not fully deleted
+**Solution**: Check for site-specific options in multisite, verify table names
+
+---
+
+## Summary
+
+| Hook | When | Purpose | Delete Data? |
+|------|------|---------|--------------|
+| Activation | Plugin activated | Setup, create tables, add options | No |
+| Deactivation | Plugin deactivated | Clear caches, unschedule cron | **NO** |
+| Uninstall | Plugin deleted | Complete cleanup | **YES** |
+
+**Golden Rule**: Only delete user data during uninstall, never during deactivation.
+