The three events that frame a plugin's existence on a site. Each has a different scope, different runtime context, and different non-negotiable rules. Get the contract wrong and you ship plugins that:
\nThis skill assumes the plugin already has a clean bootstrap (see wp-plugin-bootstrap). It covers ONLY what happens at the three lifecycle boundaries.
Update-time migrations after plugin files are replaced are out of scope here; note that activation does not fire on an ordinary plugin update.
\nTrigger when ANY of the following is true:
\nregister_activation_hook, register_deactivation_hook, or uninstall.php.wp_options\".The diff or file most likely contains: register_activation_hook, register_deactivation_hook, register_uninstall_hook (anti-pattern, see below), uninstall.php, WP_UNINSTALL_PLUGIN, dbDelta, wp_unschedule_hook, wp_clear_scheduled_hook, delete_option, delete_site_option, or switch_to_blog.
| Event | \nHook / file | \nWhen it fires | \nRuntime context | \n
|---|---|---|---|
| Activate | \nregister_activation_hook( __FILE__, $cb ) → activate_<basename> | \nUser clicks \"Activate\" in /wp-admin/plugins.php. Also re-fires on reactivation. NOT on plugin update. | \nFull WP loaded, user logged in, plugin's main file already loaded. Classes via autoloader available. | \n
| Deactivate | \nregister_deactivation_hook( __FILE__, $cb ) → deactivate_<basename> | \nUser clicks \"Deactivate\". | \nFull WP loaded, plugin loaded. | \n
| Uninstall | \nuninstall.php at plugin root | \nUser clicks \"Delete\" on a deactivated plugin. | \nFull WP loaded, BUT plugin's main file NOT loaded — uninstall.php runs in isolation with only the WP API available. WP_UNINSTALL_PLUGIN constant is defined (wp-admin/includes/plugin.php:1324). | \n
That third row is the unintuitive one. WP includes uninstall.php at the top of uninstall_plugin() — your namespaced classes, your Plugin::instance(), your composer autoload — none of it is loaded. Only the WP global functions and the $wpdb global are available.
register_activation_hook( __FILE__, static function (): void {\n // 1. Requirements re-check (the bootstrap-time check may have been bypassed\n // by direct DB activation). Bail loud if anything is missing.\n if ( ! function_exists( 'jet_form_builder' ) ) {\n require_once ABSPATH . 'wp-admin/includes/plugin.php';\n deactivate_plugins( plugin_basename( __FILE__ ) );\n wp_die( esc_html( 'JetFormBuilder must be active.' ), '', array( 'back_link' => true ) );\n }\n\n // 2. Seed default options — add_option respects existing values, so\n // reactivation after a deactivate-without-uninstall preserves user\n // preferences. NEVER use update_option here.\n add_option( 'myplugin_settings', array(\n 'log_level' => 'errors',\n 'cache_ttl' => 3600,\n ) );\n\n // 3. Schema migration via dbDelta. Note the explicit require_once —\n // dbDelta is in wp-admin/includes/upgrade.php, NOT loaded by default.\n require_once ABSPATH . 'wp-admin/includes/upgrade.php';\n\n global $wpdb;\n $charset = $wpdb->get_charset_collate();\n // dbDelta is finicky — follow the canonical style EXACTLY:\n // - one column per line, two spaces after column name\n // - PRIMARY KEY on its own line at the end\n // - lowercase types ('bigint(20)', 'datetime'), as WP itself uses\n // - no IF NOT EXISTS (dbDelta diff-applies)\n dbDelta( \"CREATE TABLE {$wpdb->prefix}myplugin_log (\n id bigint(20) unsigned NOT NULL AUTO_INCREMENT,\n created_at datetime NOT NULL,\n message text NOT NULL,\n PRIMARY KEY (id),\n KEY created_at (created_at)\n ) {$charset};\" );\n\n // 4. Schedule recurring cron events (the schedule constant must already\n // be registered on the 'cron_schedules' filter in your runtime code).\n if ( ! wp_next_scheduled( 'myplugin_daily_cleanup' ) ) {\n wp_schedule_event( time() + DAY_IN_SECONDS, 'daily', 'myplugin_daily_cleanup' );\n }\n\n // 5. Capability seeding (only if you genuinely need plugin-specific caps).\n $editor = get_role( 'editor' );\n if ( $editor && ! $editor->has_cap( 'manage_myplugin' ) ) {\n $editor->add_cap( 'manage_myplugin' );\n }\n} );\nRules for the activation callback:
\nactivate_plugin() programmatically, bypassing the wp-admin UI's pre-checks. Belt and suspenders.add_option, NOT update_option for default seeding. update_option overwrites existing values, destroying user preferences if the plugin is reactivated.require_once 'wp-admin/includes/upgrade.php' before dbDelta() — the file is not auto-loaded outside the admin context.add_action, add_filter) here. Activation is one-shot; runtime hooks belong in plugins_loaded.wp_schedule_single_event instead.WP passes $network_wide as the first argument to your activation hook callback (wp-admin/includes/plugin.php, do_action( \"activate_{$plugin}\", $network_wide )). It's true if the user clicked \"Network Activate\", false (or unset on single-site) otherwise. Use this — don't reconstruct it from is_network_admin() or is_plugin_active_for_network(), both of which are less reliable in WP-CLI and during the activation event itself (the sitewide active option hasn't been written yet at the moment the hook fires).
register_activation_hook( __FILE__, static function ( bool $network_wide = false ): void {\n if ( $network_wide ) {\n // Network activation: seed every site's per-site state.\n foreach ( get_sites( array( 'fields' => 'ids' ) ) as $site_id ) {\n switch_to_blog( $site_id );\n myplugin_setup_site();\n restore_current_blog();\n }\n // Plus any network-wide options.\n add_site_option( 'myplugin_network_settings', myplugin_network_defaults() );\n } else {\n myplugin_setup_site();\n }\n} );\nThe same pattern applies to register_deactivation_hook, which receives $network_deactivating.
register_deactivation_hook( __FILE__, static function (): void {\n // Clear ALL scheduled events for our hooks, regardless of $args.\n // wp_unschedule_hook (since WP 4.9) is more robust than\n // wp_clear_scheduled_hook because it doesn't require remembering\n // the exact $args that were passed at schedule time.\n wp_unschedule_hook( 'myplugin_daily_cleanup' );\n wp_unschedule_hook( 'myplugin_token_refresh' );\n\n // OPTIONAL: clear active-state transients that are meaningless when\n // the plugin is off. Most TTL-bearing transients can self-expire.\n delete_transient( 'myplugin_api_status' );\n} );\nThe hard rule: deactivation is REVERSIBLE. The user clicked \"Deactivate\", not \"Delete\". They might activate again tomorrow and expect their settings, custom tables, post meta, and capabilities to still be intact.
\nSo the deactivate callback does:
\nIt does NOT do:
\nCron is per-blog in multisite — each site has its own scheduled events. wp_unschedule_hook only affects the current blog. The deactivation callback receives $network_deactivating as its first argument; use it to decide whether to loop:
register_deactivation_hook( __FILE__, static function ( bool $network_deactivating = false ): void {\n if ( $network_deactivating ) {\n foreach ( get_sites( array( 'fields' => 'ids' ) ) as $site_id ) {\n switch_to_blog( $site_id );\n wp_unschedule_hook( 'myplugin_daily_cleanup' );\n restore_current_blog();\n }\n } else {\n wp_unschedule_hook( 'myplugin_daily_cleanup' );\n }\n} );\nuninstall.phpPlace uninstall.php at the plugin root, guard it with\nWP_UNINSTALL_PLUGIN, and assume the plugin bootstrap/autoloader did not run.\nUse raw WordPress functions or deliberately require a dependency-free constants\nfile. Delete every owned option, meta key, transient, cron event, capability,\npost/object, upload, and custom table unless an explicit preserve-data policy\nsays otherwise.
On multisite, distinguish per-site data from network options and shared users.\nLoop sites for per-site cleanup and call delete_site_option() for network\nstate. Prefer uninstall.php to register_uninstall_hook() so uninstall does\nnot need to load the complete plugin while its dependencies may be inactive.
Read references/uninstall-and-multisite.md before implementing destructive\ncleanup; it contains the isolated-file pattern and failure cases.
add_action here.uninstall.php, multisite-aware.uninstall.php runs without your classes. Use raw WP functions and inline strings (or manually require a constants file).wp_unschedule_hook($hook) over wp_clear_scheduled_hook($hook, $args) — args-mismatch means orphaned events. The former clears all events for a hook regardless of args (since WP 4.9, wp-includes/cron.php).add_option for activation seeding, never update_option — preserves existing user preferences across reactivation.require_once 'wp-admin/includes/upgrade.php' before any dbDelta() call.delete_site_option for network-level data, loop sites for per-site cleanup.preserve_data_on_uninstall toggle. Some users reinstall; uninstall ≠ \"I want to lose everything\".Use references/uninstall-and-multisite.md to review reactivation overwrites,\ncron-argument mismatches, unavailable plugin classes, non-trivial registered\nuninstall callbacks, and destructive deactivation.
wp-plugin-bootstrap first — it covers the main plugin file (header, constants, autoload, requirements check at activation entry).wp-security-audit on the activation handler — it's a write endpoint with admin context.wp-i18n-audit if the lifecycle handlers emit translated strings (admin notices, wp_die messages).cron_schedules filter), Action Scheduler integration — adjacent topic, separate skill (wp-plugin-cron, planned).dbDelta — versioned update migrations need their own pattern; do not rely only on upgrader_process_complete.wp plugin activate / wp plugin deactivate semantics — same hooks fire, but the multisite detection (is_network_admin()) is different.uninstall.php equivalent; theme cleanup is generally less mechanized.references/uninstall-and-multisite.md.register_activation_hook / register_deactivation_hook / register_uninstall_hook: wp-includes/plugin.phpuninstall_plugin() (the function that includes uninstall.php): wp-admin/includes/plugin.php:1302-1330wp_unschedule_hook (since 4.9): wp-includes/cron.phpdbDelta: wp-admin/includes/upgrade.phpwp-includes/ms-blogs.php