WordPress at a glance

add_option() WP 1.0.0

Adds a new option. Does nothing if this option already exists.

You do not need to serialize values. If the value needs to be serialized, it will be serialized automatically before inserting into the database.

You can create options without values and update the values later.

Hooks in function
Return

true/false. False if option was not added and true if option was added.

Usage

add_option( $option, $value, $deprecated, $autoload );
$option(string) (required)

Name of option to add. Expected to not be SQL-escaped.

It is recommended to use _ for words separation and avoid the use of UPPERCASE letters.

$value(mixed)
Option value. Must be serializable if non-scalar. Expected to not be SQL-escaped.
Default: ''
$deprecated(string)
Deprecated since 2.3.
Default: ''
$autoload(string/true/false)

Whether to load the option when WordPress starts up. Accepts 'no' to disable for legacy reasons.

The autoload is implemented with wp_load_alloptions() function (adds an option to the array of all autoload options, then puts the option from the array into the cache during the page generation).
Default: yes

Examples

#1 Add an option

Let's add an option my_option with value 255. Autoload for this option will be enabled.

<?php add_option( 'my_option', '255' ); ?>

Code of add option: wp-includes/option.php VER 5.1.1

<?php
function add_option( $option, $value = '', $deprecated = '', $autoload = 'yes' ) {
	global $wpdb;

	if ( ! empty( $deprecated ) ) {
		_deprecated_argument( __FUNCTION__, '2.3.0' );
	}

	$option = trim( $option );
	if ( empty( $option ) ) {
		return false;
	}

	wp_protect_special_option( $option );

	if ( is_object( $value ) ) {
		$value = clone $value;
	}

	$value = sanitize_option( $option, $value );

	// Make sure the option doesn't already exist. We can check the 'notoptions' cache before we ask for a db query
	$notoptions = wp_cache_get( 'notoptions', 'options' );
	if ( ! is_array( $notoptions ) || ! isset( $notoptions[ $option ] ) ) {
		/** This filter is documented in wp-includes/option.php */
		if ( apply_filters( "default_option_{$option}", false, $option, false ) !== get_option( $option ) ) {
			return false;
		}
	}

	$serialized_value = maybe_serialize( $value );
	$autoload         = ( 'no' === $autoload || false === $autoload ) ? 'no' : 'yes';

	/**
	 * Fires before an option is added.
	 *
	 * @since 2.9.0
	 *
	 * @param string $option Name of the option to add.
	 * @param mixed  $value  Value of the option.
	 */
	do_action( 'add_option', $option, $value );

	$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 ) );
	if ( ! $result ) {
		return false;
	}

	if ( ! wp_installing() ) {
		if ( 'yes' == $autoload ) {
			$alloptions            = wp_load_alloptions();
			$alloptions[ $option ] = $serialized_value;
			wp_cache_set( 'alloptions', $alloptions, 'options' );
		} else {
			wp_cache_set( $option, $serialized_value, 'options' );
		}
	}

	// This option exists now
	$notoptions = wp_cache_get( 'notoptions', 'options' ); // yes, again... we need it to be fresh
	if ( is_array( $notoptions ) && isset( $notoptions[ $option ] ) ) {
		unset( $notoptions[ $option ] );
		wp_cache_set( 'notoptions', $notoptions, 'options' );
	}

	/**
	 * Fires after a specific option has been added.
	 *
	 * The dynamic portion of the hook name, `$option`, refers to the option name.
	 *
	 * @since 2.5.0 As "add_option_{$name}"
	 * @since 3.0.0
	 *
	 * @param string $option Name of the option to add.
	 * @param mixed  $value  Value of the option.
	 */
	do_action( "add_option_{$option}", $option, $value );

	/**
	 * Fires after an option has been added.
	 *
	 * @since 2.9.0
	 *
	 * @param string $option Name of the added option.
	 * @param mixed  $value  Value of the option.
	 */
	do_action( 'added_option', $option, $value );
	return true;
}

Related Functions

From tag: Options API (settings)

More from category: Site Options (settings)

No comments
    Hello, !     Log In . Register