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 1124 (+54 into the body)

   Filters the default value for an option.

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

   Fires before an option is added.

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

   Fires after a specific option has been added.

4. 4
   do_action( added_option )actionline 1187 (+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 ↗

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