WordPress register_activation_hook Example: Run Plugin Setup Safely

Last reviewed: April 25, 2026

Plugin activation is the right time to run one-time setup tasks such as creating options, assigning baseline capabilities, and scheduling jobs. The mistake is treating activation as a normal runtime hook and stuffing it with logic that should execute on every request.

This guide shows how to use register_activation_hook() for predictable plugin setup, how to keep the callback small, and how to avoid the scope and performance mistakes that make activation flows brittle.

Register the hook from the main plugin file

<?php
/**
 * Plugin Name: VulnWP Setup
 */

register_activation_hook( __FILE__, 'vulnwp_setup_activate' );

function vulnwp_setup_activate() {
	add_option( 'vulnwp_setup_version', '1.0.0', '', false );
	add_option( 'vulnwp_scan_enabled', 'yes', '', false );
}

The activation hook must be registered from the main plugin file. Registering it inside init, plugins_loaded, or another callback will not work because WordPress needs that registration during the activation flow itself.

Keep activation tasks narrow

Good activation work is fast and deterministic. It should prepare the plugin to run, not try to do every expensive job immediately.

function vulnwp_setup_activate() {
	add_option( 'vulnwp_setup_version', '1.0.0', '', false );

	if ( ! wp_next_scheduled( 'vulnwp_daily_scan' ) ) {
		wp_schedule_event( time() + HOUR_IN_SECONDS, 'daily', 'vulnwp_daily_scan' );
	}
}

Scheduling a future task is usually better than doing heavy remote calls, long migrations, or report generation inside the activation request.

Flush rewrite rules only when structure changed

If activation introduces a custom post type, taxonomy, or custom rewrite rule, register that structure first and then flush once. Do not flush for unrelated plugins.

function vulnwp_setup_activate() {
	vulnwp_register_endpoint();
	flush_rewrite_rules();
}

That single flush is acceptable on activation because permalink structures changed. Doing the same thing on every page load is wasteful.

Watch variable scope

Activation callbacks do not magically inherit plugin file variables as globals. If a variable truly needs global scope, declare it explicitly everywhere it is used.

global $vulnwp_db_version;
$vulnwp_db_version = '3';

function vulnwp_setup_activate() {
	global $vulnwp_db_version;

	update_option( 'vulnwp_db_version', $vulnwp_db_version, false );
}

Production checklist

• Register the activation hook in the main plugin file.
• Keep the callback short and deterministic.
• Create only the options, roles, schedules, or rewrite state the plugin truly needs.
• Flush rewrite rules only when URL structures changed.
• Move expensive work to scheduled jobs or admin-driven upgrades.
• Test network activation separately if the plugin supports multisite.

Common mistakes

• Registering the hook inside another hook. Activation will never reach it correctly.
• Doing remote HTTP calls during activation. That makes activation slow and failure-prone.
• Flushing rewrite rules for no reason. It is only needed when routes changed.
• Assuming main-file variables are global. Activation scope is easy to misunderstand.
• Scheduling duplicate jobs. Always check whether an event already exists.

Related reading

If activation creates scheduled work, pair this with the cron event guide. If activation changes routes, use the rewrite rules article for the correct flush pattern.

References and further reading

• WordPress Code Reference: register_activation_hook()
• WordPress Plugin Handbook: Activation / Deactivation Hooks
• WordPress Code Reference: wp_next_scheduled()