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

Description

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

bool

True if the option was added, false otherwise.

Hooks fired · 4

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

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

   Filters the default value for an option.

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

   Fires before an option is added.

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

   Fires after a specific option has been added.

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

View on Trac ↗View on GitHub ↗

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

History

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