delete_option( string $option ): bool

Compatibility

Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.

Parameters

$optionstring

Name of the option to delete. Expected to not be SQL-escaped.

Return value

bool

True if the option was deleted, false otherwise.

Code examples

Every example is editable and runs in a real WordPress booted in your browser by WordPress Playground. Press Run, then edit the code: clicking away re-runs it. Nothing is sent anywhere until you do.

add_option( 'my_plugin_settings', array( 'enabled' => true, 'threshold' => 10 ) );

$deleted = delete_option( 'my_plugin_settings' );

printf( 'delete_option() returned: %s' . "\n", $deleted ? 'true' : 'false' );

$value = get_option( 'my_plugin_settings', 'default (not found)' );
printf( 'get_option() now returns: %s', esc_html( is_array( $value ) ? print_r( $value, true ) : $value ) );

add_option( 'my_feature_flag', '1' );

add_action( 'delete_option_my_feature_flag', function ( $option ) {
	printf( 'Fired delete_option_%s just before removal.' . "\n", esc_html( $option ) );
} );

$result = delete_option( 'my_feature_flag' );

printf( 'Deletion result: %s', $result ? 'true' : 'false' );

Common problems and fixes · 4

• Why does delete_option keep returning false even though I'm sure the option exists?
• Why did my code die with a 'protected WP option' message when I called delete_option?
• Does delete_option clear the object cache right away or just the database row?
• Why doesn't my delete_option_{$option} callback fire during install?

Alternatives and related functions

update_option

When you want to change an option's value without ever removing the row, since update_option() will create it if it doesn't exist yet.

add_option

When you only want to set a value the first time and leave an existing option untouched.

delete_site_option

When the setting is a network-wide option in a multisite install rather than a single site's option.

delete_transient

When the value you're removing was stored as a transient rather than a permanent option, since transients use a separate storage and expiration mechanism.

Performance profile

How much work a call to delete_option() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.

Cost class

Heavy

Reaches the database via ->get_row().

Scaling

Constant

No loop in the body: the same number of instructions runs whatever you pass in.

Instructions

7–87

Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 94.

Plugin surface

3 hooks

Third-party callbacks on 'delete_option', 'delete_option_{$option}', 'deleted_option' run inside this call, and their cost is not bounded by anything here.

Called by

34

34 places in core call this, so the cost is paid more often than your own code shows.

What it touches

• optionoption read or writedelete_option()this function does it
• hookthird-party callbacksdo_action()called directly
• cacheobject cachewp_cache_set()called directly
• sqldatabase query->get_row()called directly

Further down the call graph this can also reach serialize, query and transient. Those are the worst case, several calls deep and usually down an error path, not what a normal call pays.

What one call costs · 10 distinct outcomes

One number would be a lie: the work depends on which branch runs. These are every distinct cost delete_option() can have, taken from its control-flow graph on PHP 8.5.

Hooks and filters fired · 3

3 hooks fire while delete_option() runs, in this order:

1. 1
   do_action( delete_option )actionline 1228 (+26 into the body)

   Fires immediately before an option is deleted.

2. 2
   do_action( delete_option_{$option} )actionline 1265 (+63 into the body)

   Fires after a specific option has been deleted.

3. 3
   do_action( deleted_option )actionline 1274 (+72 into the body)

   Fires after an option has been deleted.

Uses · 8

• wp_protect_special_option()Protects WordPress special option from being modified.
• do_action()Calls the callback functions that have been added to an action hook.
• wp_installing()Checks or sets whether WordPress is in "installation" mode.
• wp_autoload_values_to_autoload()Returns the values that trigger autoloading from the options table.
• wp_load_alloptions()Loads and caches all autoloaded options, if available or all options.
• wp_cache_set()Saves the data to the cache.
• wp_cache_delete()Removes the cache contents matching key and group.
• wp_cache_get()Retrieves the cache contents from the cache by key and group.

Used by · 34

• Twenty_Eleven_Ephemera_Widget::update()Updates widget settings.
• WP_Paused_Extensions_Storage::delete()Forgets a previously recorded extension error.
• WP_Paused_Extensions_Storage::delete_all()Remove all paused extensions.
• WP_REST_Settings_Controller::update_item()Updates settings for the settings object.
• WP_Recovery_Mode_Email_Service::clear_rate_limit()Clears the rate limit, allowing a new recovery mode email to be sent immediately.
• WP_Site_Icon::delete_attachment_data()Deletes the Site Icon when the image file is deleted.
• WP_Theme::get_allowed_on_site()Returns array of stylesheet names of themes allowed on the site.
• WP_Upgrader::release_lock()Releases an upgrader lock.
• WP_Widget::get_settings()Retrieves the settings for all instances of the widget class.
• _delete_attachment_theme_mod()Checks an attachment being deleted to see if it's a header or background image.
• _delete_site_logo_on_remove_custom_logo()Deletes the site_logo when the custom_logo theme mod is removed.
• _delete_site_logo_on_remove_theme_mods()Deletes the site logo when all theme mods are being removed.

Source code

View on Trac ↗View on GitHub ↗

1202function delete_option( $option ) {1203	global $wpdb;1204 1205	if ( is_scalar( $option ) ) {1206		$option = trim( $option );1207	}1208 1209	if ( empty( $option ) ) {1210		return false;1211	}1212 1213	wp_protect_special_option( $option );1214 1215	// Get the ID, if no ID then return.1216	$row = $wpdb->get_row( $wpdb->prepare( "SELECT autoload FROM $wpdb->options WHERE option_name = %s", $option ) );1217	if ( is_null( $row ) ) {1218		return false;1219	}1220 1221	/**1222	 * Fires immediately before an option is deleted.1223	 *1224	 * @since 2.9.01225	 *1226	 * @param string $option Name of the option to delete.1227	 */1228	do_action( 'delete_option', $option );1229 1230	$result = $wpdb->delete( $wpdb->options, array( 'option_name' => $option ) );1231 1232	if ( ! wp_installing() ) {1233		if ( in_array( $row->autoload, wp_autoload_values_to_autoload(), true ) ) {1234			$alloptions = wp_load_alloptions( true );1235 1236			if ( is_array( $alloptions ) && isset( $alloptions[ $option ] ) ) {1237				unset( $alloptions[ $option ] );1238				wp_cache_set( 'alloptions', $alloptions, 'options' );1239			}1240		} else {1241			wp_cache_delete( $option, 'options' );1242		}1243 1244		$notoptions = wp_cache_get( 'notoptions', 'options' );1245 1246		if ( ! is_array( $notoptions ) ) {1247			$notoptions = array();1248		}1249		$notoptions[ $option ] = true;1250 1251		wp_cache_set( 'notoptions', $notoptions, 'options' );1252	}1253 1254	if ( $result ) {1255 1256		/**1257		 * Fires after a specific option has been deleted.1258		 *1259		 * The dynamic portion of the hook name, `$option`, refers to the option name.1260		 *1261		 * @since 3.0.01262		 *1263		 * @param string $option Name of the deleted option.1264		 */1265		do_action( "delete_option_{$option}", $option );1266 1267		/**1268		 * Fires after an option has been deleted.1269		 *1270		 * @since 2.9.01271		 *1272		 * @param string $option Name of the deleted option.1273		 */1274		do_action( 'deleted_option', $option );1275 1276		return true;1277	}1278 1279	return false;1280}

Changelog

Introduced in 1.2.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 6.9.7 tag, from src/wp-includes/option.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.

Corrections

Something wrong on this page? Report it and it gets fixed in the next regeneration.