add_option()向wp_option表添加选项/值对

目录

描述

译文

这是一种向选项数据库表中添加有名称的选项/值对的安全方法。如果所需选项已存在,add_option()不添加内容。选项被保存后,可通过get_option()来访问选项,通过update_option()来修改选项,还可以通过delete_option()删除该选项。

在INSERT语句前,add_option的值被$wpdb->escape 跳过。

WP 2.3系列版本或更高版本的用法

WP 2.3系列中,$description参数已经停用,wp_option表中也删除了该参数的值。用法相同,但不再使用第二个参数。

该函数在早期版本中的用法见下文

/* ----------------------------------
 * wordpress之魂 © http://wphun.com
 * ---------------------------------- */
<?php add_option($name, $value = , $deprecated = , $autoload = 'yes'); ?>

WP 2.3系列版本或更高版本中该函数的示例

/* ----------------------------------
 * wordpress之魂 © http://wphun.com
 * ---------------------------------- */
<?php add_option("myhack_extraction_length", '255', , 'yes'); ?>

WP 2.3系列版本或更高版本中该函数的参数

$name

(字符串)(必需)需要添加的选项名称。用下划线隔开单词;不要使用大写字母——参数值会被存入数据库

默认值:None

$value

(字符串)(可选)当前选项名称的值。限制在2到32个字节内

默认值:Empty

$deprecated

(字符串)(可选)不再使用

默认值:Empty

$autoload

(字符串)(可选)当前选项是否需要被wp_load_alloptions函数自动加载(加载每个页面时将选项放在对象缓存中)?有效值:yes或no。

默认值:yes

$description停用前该函数的用法

/* ----------------------------------
 * wordpress之魂 © http://wphun.com
 * ---------------------------------- */
In the last versions of wordpress (2.3.X) 
the parameter $description is deprecated and remove the values from 
the wp_options table.The usage its the same but the seccond parameter its unused.WP 2.3.X or newer 
<?php add_option($name, $value = , $deprecated = , $autoload = 'yes'); ?>
<?php add_option($name, $value = , $description = , $autoload = 'yes'); ?>

原文

A safe way of adding a named option/value pair to the options database table. It does nothing if the option already exists. After the option is saved, it can be accessed with get_option(), changed with update_option(), and deleted with delete_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. You can create options without values and then add values later.

Calling add_option first checks whether the option has already been added, and returns false if an option with the same name exists. Next, it checks to make sure the option name is not one of the protected names alloptions or notoptions, and dies with an error message if attempting to overwrite a protected option. If the option name is not protected, and does not already exist, the option will be created.

Note: add_option uses get_option to determine whether the option already exists, and since get_option returns false as the default value, if you set an option to false in the database (e.g. via update_option($option_name, false)), then a subsequent call to add_option will change the value, because it will seem to add_option that the option does not exist.

vs. update_option()

If you are trying to ensure that a given option is created, use update_option() instead, which bypasses the option name check and updates the option with the desired value whether or not it exists.

NB: you cannot specify autoload='no' if you use update_option(). If you need to specify autoload='no', and you are not sure whether the option already exists, then call delete_option() first before calling add_option().

add_option() 描述

用法

<?php add_option$option$value$deprecated$autoload ); ?>

add_option() 用法

参数

$option

(string) (必填) Name of the option to be added. Must not exceed 64 characters. Use underscores to separate words, and do not use uppercase—this is going to be placed into the database.

默认值: None

$value

(mixed) (可选) Value for this option name. Limited to 2^32 bytes of data

默认值: Empty string

$deprecated

(string) (可选) Deprecated in WordPress Version 2.3.

默认值: Empty string

$autoload

(string) (可选) Should this option be automatically loaded by the function wp_load_alloptions() (puts options into object cache on each page load)? Valid values: yes or no.

默认值: yes

add_option() 参数

历史

添加于 版本: 1.0.0

add_option() 历史

源文件

add_option() 函数的代码位于 wp-includes/option.php.

/* ----------------------------------
 * wordpress之魂 © http://wphun.com
 * ---------------------------------- */
/**
 * Add 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 can not 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
 *
 * @param string         $option      Name of 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 False if option was not added and true if option was added.
 */
function add_option( $option, $value = '', $deprecated = '', $autoload = 'yes' ) {
	global $wpdb;

	if ( !empty( $deprecated ) )
		_deprecated_argument( __FUNCTION__, '2.3' );

	$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 ) !== 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 ( ! defined( '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;
}

add_option() 源文件

相关