add_option

Advertisement

Summery Summery

Adds a new option.

Syntax Syntax

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

Description Description

You do not need to serialize values. If the value needs to be serialized, then it will be serialized before it is inserted into the database. Remember, resources cannot be serialized or added as an option.

You can create options without values and then update the values later. Existing options will not be updated and checks are performed to ensure that you aren’t adding a protected WordPress option. Care should be taken to not name options the same as the ones which are protected.

Parameters Parameters

$option

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

$value

(Optional) Option value. Must be serializable if non-scalar. Expected to not be SQL-escaped.

Default value: ''

$deprecated

(Optional) Description. Not used anymore.

Default value: ''

$autoload

(Optional) Whether to load the option when WordPress starts up. Default is enabled. Accepts 'no' to disable for legacy reasons.

Default value: 'yes'

Return Return

(bool) False if option was not added and true if option was added.

Source Source

File: wp-includes/option.php

	/**
	 * Fires after the value of a specific option has been successfully updated.
	 *
	 * The dynamic portion of the hook name, `$option`, refers to the option name.
	 *
	 * @since 2.0.1
	 * @since 4.4.0 The `$option` parameter was added.
	 *
	 * @param mixed  $old_value The old option value.
	 * @param mixed  $value     The new option value.
	 * @param string $option    Option name.
	 */
	do_action( "update_option_{$option}", $old_value, $value, $option );

	/**
	 * Fires after the value of an option has been successfully updated.
	 *
	 * @since 2.9.0
	 *
	 * @param string $option    Name of the updated option.
	 * @param mixed  $old_value The old option value.
	 * @param mixed  $value     The new option value.
	 */
	do_action( 'updated_option', $option, $old_value, $value );

	return true;
}

/**
 * Adds a new option.
 *
 * You do not need to serialize values. If the value needs to be serialized,
 * then it will be serialized before it is inserted into the database.
 * Remember, resources cannot be serialized or added as an option.
 *
 * You can create options without values and then update the values later.
 * Existing options will not be updated and checks are performed to ensure that you
 * aren't adding a protected WordPress option. Care should be taken to not name
 * options the same as the ones which are protected.
 *
 * @since 1.0.0
 *
 * @global wpdb $wpdb WordPress database abstraction object.
 *
 * @param string      $option     Name of the option to add. Expected to not be SQL-escaped.
 * @param mixed       $value      Optional. Option value. Must be serializable if non-scalar.
 *                                Expected to not be SQL-escaped.
 * @param string      $deprecated Optional. Description. Not used anymore.
 * @param string|bool $autoload   Optional. Whether to load the option when WordPress starts up.
 *                                Default is enabled. Accepts 'no' to disable for legacy reasons.
 * @return bool True if the option was added, false otherwise.
 */
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;
	}

	/*
	 * Until a proper _deprecated_option() function can be introduced,
	 * redirect requests to deprecated keys to the new, correct ones.
	 */
	$deprecated_keys = array(
		'blacklist_keys'    => 'disallowed_keys',
		'comment_whitelist' => 'comment_previously_approved',
	);

	if ( ! wp_installing() && isset( $deprecated_keys[ $option ] ) ) {
		_deprecated_argument(
			__FUNCTION__,
			'5.5.0',
			sprintf(
				/* translators: 1: Deprecated option key, 2: New option key. */
				__( 'The "%1$s" option key has been renamed to "%2$s".' ),
				$option,
				$deprecated_keys[ $option ]
			)
		);
		return add_option( $deprecated_keys[ $option ], $value, $deprecated, $autoload );
	}

	wp_protect_special_option( $option );

Advertisement

Changelog Changelog

Changelog
Version Description
1.0.0 Introduced.

Advertisement

Leave a Reply