add_option( string $option, mixed $value = '', string $deprecated = '', bool|null $autoload = null ): bool

Description

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 add. Expected to not be SQL-escaped.

$valuemixedoptional

Option value. Must be serializable if non-scalar.
Expected to not be SQL-escaped.Default: ''

$deprecatedstringoptional

Description. Not used anymore.Default: ''

$autoloadbool|nulloptional

Whether to load the option when WordPress starts up.
Accepts a boolean, or null to leave the decision up to default heuristics in WordPress. For backward compatibility 'yes' and 'no' are also accepted, though using these values is deprecated.
Autoloading too many options can lead to performance problems, especially if the options are not frequently used. For options which are accessed across several places in the frontend, it is recommended to autoload them, by using true.
For options which are accessed only on few specific URLs, it is recommended to not autoload them, by using false.
Default is null, which means WordPress will determine the autoload value.Default: null

Return value

bool

True if the option was added, false otherwise.

Performance profile

How much work a call to add_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 ->query().

Scaling

Constant

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

Instructions

12–134

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

Plugin surface

4 hooks

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

Called by

9

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

What it touches

• optionoption read or writeadd_option()this function does it
• cacheobject cachewp_cache_get()called directly
• hookthird-party callbacksapply_filters()called directly
• serializeserialisationmaybe_serialize()called directly
• sqldatabase query->query()called directly

Further down the call graph this can also reach 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 · 64 distinct outcomes

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

Hooks and filters fired · 4

4 hooks fire while add_option() runs, in this order:

1. 1
   apply_filters( default_option_{$option} )filterline 1115 (+54 into the body)

   Filters the default value for an option.

2. 2
   do_action( add_option )actionline 1132 (+71 into the body)

   Fires before an option is added.

3. 3
   do_action( add_option_{$option} )actionline 1168 (+107 into the body)

   Fires after a specific option has been added.

4. 4
   do_action( added_option )actionline 1178 (+117 into the body)

   Fires after an option has been added.

Uses · 15

• _deprecated_argument()Marks a function argument as deprecated and inform when it has been used.
• wp_installing()Checks or sets whether WordPress is in "installation" mode.
• __()Retrieves the translation of $text.
• add_option()Adds a new option.
• wp_protect_special_option()Protects WordPress special option from being modified.
• sanitize_option()Sanitizes various option values based on the nature of the option.
• wp_cache_get()Retrieves the cache contents from the cache by key and group.
• apply_filters()Calls the callback functions that have been added to a filter hook.
• get_option()Retrieves an option value based on an option name.
• maybe_serialize()Serializes data, if needed.
• wp_determine_option_autoload_value()Determines the appropriate autoload value for an option based on input.
• do_action()Calls the callback functions that have been added to an action hook.

Used by · 9

• add_blog_option()Adds a new option for a given blog ID.
• add_network_option()Adds a new network option.
• add_option()Adds a new option.
• set_transient()Sets/updates the value of a transient.
• switch_theme()Switches the theme.
• update_option()Updates the value of an option that was already added.
• upgrade_110()Execute changes made in WordPress 1.2.
• upgrade_340()Execute changes made in WordPress 3.4.
• upgrade_630()Executes changes made in WordPress 6.3.0.

Source code

View on Trac ↗View on GitHub ↗

1061function add_option( $option, $value = '', $deprecated = '', $autoload = null ) {1062	global $wpdb;1063 1064	if ( ! empty( $deprecated ) ) {1065		_deprecated_argument( __FUNCTION__, '2.3.0' );1066	}1067 1068	if ( is_scalar( $option ) ) {1069		$option = trim( $option );1070	}1071 1072	if ( empty( $option ) ) {1073		return false;1074	}1075 1076	/*1077	 * Until a proper _deprecated_option() function can be introduced,1078	 * redirect requests to deprecated keys to the new, correct ones.1079	 */1080	$deprecated_keys = array(1081		'blacklist_keys'    => 'disallowed_keys',1082		'comment_whitelist' => 'comment_previously_approved',1083	);1084 1085	if ( isset( $deprecated_keys[ $option ] ) && ! wp_installing() ) {1086		_deprecated_argument(1087			__FUNCTION__,1088			'5.5.0',1089			sprintf(1090				/* translators: 1: Deprecated option key, 2: New option key. */1091				__( 'The "%1$s" option key has been renamed to "%2$s".' ),1092				$option,1093				$deprecated_keys[ $option ]1094			)1095		);1096		return add_option( $deprecated_keys[ $option ], $value, $deprecated, $autoload );1097	}1098 1099	wp_protect_special_option( $option );1100 1101	if ( is_object( $value ) ) {1102		$value = clone $value;1103	}1104 1105	$value = sanitize_option( $option, $value );1106 1107	/*1108	 * Make sure the option doesn't already exist.1109	 * We can check the 'notoptions' cache before we ask for a DB query.1110	 */1111	$notoptions = wp_cache_get( 'notoptions', 'options' );1112 1113	if ( ! is_array( $notoptions ) || ! isset( $notoptions[ $option ] ) ) {1114		/** This filter is documented in wp-includes/option.php */1115		if ( apply_filters( "default_option_{$option}", false, $option, false ) !== get_option( $option ) ) {1116			return false;1117		}1118	}1119 1120	$serialized_value = maybe_serialize( $value );1121 1122	$autoload = wp_determine_option_autoload_value( $option, $value, $serialized_value, $autoload );1123 1124	/**1125	 * Fires before an option is added.1126	 *1127	 * @since 2.9.01128	 *1129	 * @param string $option Name of the option to add.1130	 * @param mixed  $value  Value of the option.1131	 */1132	do_action( 'add_option', $option, $value );1133 1134	$result = $wpdb->query( $wpdb->prepare( "INSERT INTO `$wpdb->options` (`option_name`, `option_value`, `autoload`) VALUES (%s, %s, %s) ON DUPLICATE KEY UPDATE `option_name` = VALUES(`option_name`), `option_value` = VALUES(`option_value`), `autoload` = VALUES(`autoload`)", $option, $serialized_value, $autoload ) );1135	if ( ! $result ) {1136		return false;1137	}1138 1139	if ( ! wp_installing() ) {1140		if ( in_array( $autoload, wp_autoload_values_to_autoload(), true ) ) {

Changelog

Introduced in 1.0.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.7.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.