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 1227 (+26 into the body)

   Fires immediately before an option is deleted.

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

   Fires after a specific option has been deleted.

3. 3
   do_action( deleted_option )actionline 1273 (+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 ↗

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

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 7.1.0 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.