[ Index ]

PHP Cross Reference of WordPress

title

Body

[close]

/wp-includes/ -> option.php (summary)

Option API

File Size: 2516 lines (77 kb)
Included or required: 1 time
Referenced: 0 times
Includes or requires: 0 files

Defines 35 functions

  get_option()
  wp_protect_special_option()
  form_option()
  wp_load_alloptions()
  wp_load_core_site_options()
  update_option()
  add_option()
  delete_option()
  delete_transient()
  get_transient()
  set_transient()
  delete_expired_transients()
  wp_user_settings()
  get_user_setting()
  set_user_setting()
  delete_user_setting()
  get_all_user_settings()
  wp_set_all_user_settings()
  delete_all_user_settings()
  get_site_option()
  add_site_option()
  delete_site_option()
  update_site_option()
  get_network_option()
  add_network_option()
  delete_network_option()
  update_network_option()
  delete_site_transient()
  get_site_transient()
  set_site_transient()
  register_initial_settings()
  register_setting()
  unregister_setting()
  get_registered_settings()
  filter_default_option()

Functions
Functions that are not part of a class:

get_option( $option, $default = false )   X-Ref
Retrieves an option value based on an option name.

If the option does not exist, and a default value is not provided,
boolean false is returned. This could be used to check whether you need
to initialize an option during installation of a plugin, however that
can be done better by using add_option() which will not overwrite
existing options.

Not initializing an option and using boolean `false` as a return value
is a bad practice as it triggers an additional database query.

The type of the returned value can be different from the type that was passed
when saving or updating the option. If the option value was serialized,
then it will be unserialized when it is returned. In this case the type will
be the same. For example, storing a non-scalar value like an array will
return the same array.

In most cases non-string scalar and null values will be converted and returned
as string equivalents.

Exceptions:

1. When the option has not been saved in the database, the `$default` value
is returned if provided. If not, boolean `false` is returned.
2. When one of the Options API filters is used: {@see 'pre_option_$option'},
{@see 'default_option_$option'}, or {@see 'option_$option'}, the returned
value may not match the expected type.
3. When the option has just been saved in the database, and get_option()
is used right after, non-string scalar and null values are not converted to
string equivalents and the original type is returned.

Examples:

When adding options like this: `add_option( 'my_option_name', 'value' )`
and then retrieving them with `get_option( 'my_option_name' )`, the returned
values will be:

- `false` returns `string(0) ""`
- `true`  returns `string(1) "1"`
- `0`     returns `string(1) "0"`
- `1`     returns `string(1) "1"`
- `'0'`   returns `string(1) "0"`
- `'1'`   returns `string(1) "1"`
- `null`  returns `string(0) ""`

When adding options with non-scalar values like
`add_option( 'my_array', array( false, 'str', null ) )`, the returned value
will be identical to the original as it is serialized before saving
it in the database:

array(3) {
[0] => bool(false)
[1] => string(3) "str"
[2] => NULL
}

since: 1.5.0
return: mixed Value of the option. A value of any type may be returned, including
param: string $option  Name of the option to retrieve. Expected to not be SQL-escaped.
param: mixed  $default Optional. Default value to return if the option does not exist.

wp_protect_special_option( $option )   X-Ref
Protects WordPress special option from being modified.

Will die if $option is in protected list. Protected options are 'alloptions'
and 'notoptions' options.

since: 2.2.0
param: string $option Option name.

form_option( $option )   X-Ref
Prints option value after sanitizing for forms.

since: 1.5.0
param: string $option Option name.

wp_load_alloptions( $force_cache = false )   X-Ref
Loads and caches all autoloaded options, if available or all options.

since: 2.2.0
since: 5.3.1 The `$force_cache` parameter was added.
return: array List of all options.
param: bool $force_cache Optional. Whether to force an update of the local cache

wp_load_core_site_options( $network_id = null )   X-Ref
Loads and caches certain often requested site options if is_multisite() and a persistent cache is not being used.

since: 3.0.0
param: int $network_id Optional site ID for which to query the options. Defaults to the current site.

update_option( $option, $value, $autoload = null )   X-Ref
Updates the value of an option that was already added.

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.

If the option does not exist, it will be created.
This function is designed to work with or without a logged-in user. In terms of security,
plugin developers should check the current user's capabilities before updating any options.

since: 1.0.0
since: 4.2.0 The `$autoload` parameter was added.
return: bool True if the value was updated, false otherwise.
param: string      $option   Name of the option to update. Expected to not be SQL-escaped.
param: mixed       $value    Option value. Must be serializable if non-scalar. Expected to not be SQL-escaped.
param: string|bool $autoload Optional. Whether to load the option when WordPress starts up. For existing options,

add_option( $option, $value = '', $deprecated = '', $autoload = 'yes' )   X-Ref
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
return: bool True if the option was added, false otherwise.
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.
param: string      $deprecated Optional. Description. Not used anymore.
param: string|bool $autoload   Optional. Whether to load the option when WordPress starts up.

delete_option( $option )   X-Ref
Removes option by name. Prevents removal of protected WordPress options.

since: 1.2.0
return: bool True if the option was deleted, false otherwise.
param: string $option Name of the option to delete. Expected to not be SQL-escaped.

delete_transient( $transient )   X-Ref
Deletes a transient.

since: 2.8.0
return: bool True if the transient was deleted, false otherwise.
param: string $transient Transient name. Expected to not be SQL-escaped.

get_transient( $transient )   X-Ref
Retrieves the value of a transient.

If the transient does not exist, does not have a value, or has expired,
then the return value will be false.

since: 2.8.0
return: mixed Value of transient.
param: string $transient Transient name. Expected to not be SQL-escaped.

set_transient( $transient, $value, $expiration = 0 )   X-Ref
Sets/updates the value of a transient.

You do not need to serialize values. If the value needs to be serialized,
then it will be serialized before it is set.

since: 2.8.0
return: bool True if the value was set, false otherwise.
param: string $transient  Transient name. Expected to not be SQL-escaped.
param: mixed  $value      Transient value. Must be serializable if non-scalar.
param: int    $expiration Optional. Time until expiration in seconds. Default 0 (no expiration).

delete_expired_transients( $force_db = false )   X-Ref
Deletes all expired transients.

The multi-table delete syntax is used to delete the transient record
from table a, and the corresponding transient_timeout record from table b.

since: 4.9.0
param: bool $force_db Optional. Force cleanup to run against the database even when an external object cache is used.

wp_user_settings()   X-Ref
Saves and restores user interface settings stored in a cookie.

Checks if the current user-settings cookie is updated and stores it. When no
cookie exists (different browser used), adds the last saved cookie restoring
the settings.

since: 2.7.0

get_user_setting( $name, $default = false )   X-Ref
Retrieves user interface setting value based on setting name.

since: 2.7.0
return: mixed The last saved user setting or the default value/false if it doesn't exist.
param: string       $name    The name of the setting.
param: string|false $default Optional. Default value to return when $name is not set. Default false.

set_user_setting( $name, $value )   X-Ref
Adds or updates user interface setting.

Both $name and $value can contain only ASCII letters, numbers, hyphens, and underscores.

This function has to be used before any output has started as it calls setcookie().

since: 2.8.0
return: bool|null True if set successfully, false otherwise.
param: string $name  The name of the setting.
param: string $value The value for the setting.

delete_user_setting( $names )   X-Ref
Deletes user interface settings.

Deleting settings would reset them to the defaults.

This function has to be used before any output has started as it calls setcookie().

since: 2.7.0
return: bool|null True if deleted successfully, false otherwise.
param: string $names The name or array of names of the setting to be deleted.

get_all_user_settings()   X-Ref
Retrieves all user interface settings.

since: 2.7.0
return: array The last saved user settings or empty array.

wp_set_all_user_settings( $user_settings )   X-Ref
Private. Sets all user interface settings.

since: 2.8.0
return: bool|null True if set successfully, false if the current user could not be found.
param: array $user_settings User settings.

delete_all_user_settings()   X-Ref
Deletes the user settings of the current user.

since: 2.7.0

get_site_option( $option, $default = false, $deprecated = true )   X-Ref
Retrieve an option value for the current network based on name of option.

since: 2.8.0
since: 4.4.0 The `$use_cache` parameter was deprecated.
since: 4.4.0 Modified into wrapper for get_network_option()
return: mixed Value set for the option.
param: string $option     Name of the option to retrieve. Expected to not be SQL-escaped.
param: mixed  $default    Optional. Value to return if the option doesn't exist. Default false.
param: bool   $deprecated Whether to use cache. Multisite only. Always set to true.

add_site_option( $option, $value )   X-Ref
Adds a new option for the current network.

Existing options will not be updated. Note that prior to 3.3 this wasn't the case.

since: 2.8.0
since: 4.4.0 Modified into wrapper for add_network_option()
return: bool True if the option was added, false otherwise.
param: string $option Name of the option to add. Expected to not be SQL-escaped.
param: mixed  $value  Option value, can be anything. Expected to not be SQL-escaped.

delete_site_option( $option )   X-Ref
Removes a option by name for the current network.

since: 2.8.0
since: 4.4.0 Modified into wrapper for delete_network_option()
return: bool True if the option was deleted, false otherwise.
param: string $option Name of the option to delete. Expected to not be SQL-escaped.

update_site_option( $option, $value )   X-Ref
Updates the value of an option that was already added for the current network.

since: 2.8.0
since: 4.4.0 Modified into wrapper for update_network_option()
return: bool True if the value was updated, false otherwise.
param: string $option Name of the option. Expected to not be SQL-escaped.
param: mixed  $value  Option value. Expected to not be SQL-escaped.

get_network_option( $network_id, $option, $default = false )   X-Ref
Retrieves a network's option value based on the option name.

since: 4.4.0
return: mixed Value set for the option.
param: int    $network_id ID of the network. Can be null to default to the current network ID.
param: string $option     Name of the option to retrieve. Expected to not be SQL-escaped.
param: mixed  $default    Optional. Value to return if the option doesn't exist. Default false.

add_network_option( $network_id, $option, $value )   X-Ref
Adds a new network option.

Existing options will not be updated.

since: 4.4.0
return: bool True if the option was added, false otherwise.
param: int    $network_id ID of the network. Can be null to default to the current network ID.
param: string $option     Name of the option to add. Expected to not be SQL-escaped.
param: mixed  $value      Option value, can be anything. Expected to not be SQL-escaped.

delete_network_option( $network_id, $option )   X-Ref
Removes a network option by name.

since: 4.4.0
return: bool True if the option was deleted, false otherwise.
param: int    $network_id ID of the network. Can be null to default to the current network ID.
param: string $option     Name of the option to delete. Expected to not be SQL-escaped.

update_network_option( $network_id, $option, $value )   X-Ref
Updates the value of a network option that was already added.

since: 4.4.0
return: bool True if the value was updated, false otherwise.
param: int    $network_id ID of the network. Can be null to default to the current network ID.
param: string $option     Name of the option. Expected to not be SQL-escaped.
param: mixed  $value      Option value. Expected to not be SQL-escaped.

delete_site_transient( $transient )   X-Ref
Deletes a site transient.

since: 2.9.0
return: bool True if the transient was deleted, false otherwise.
param: string $transient Transient name. Expected to not be SQL-escaped.

get_site_transient( $transient )   X-Ref
Retrieves the value of a site transient.

If the transient does not exist, does not have a value, or has expired,
then the return value will be false.

since: 2.9.0
return: mixed Value of transient.
param: string $transient Transient name. Expected to not be SQL-escaped.

set_site_transient( $transient, $value, $expiration = 0 )   X-Ref
Sets/updates the value of a site transient.

You do not need to serialize values. If the value needs to be serialized,
then it will be serialized before it is set.

since: 2.9.0
return: bool True if the value was set, false otherwise.
param: string $transient  Transient name. Expected to not be SQL-escaped. Must be
param: mixed  $value      Transient value. Expected to not be SQL-escaped.
param: int    $expiration Optional. Time until expiration in seconds. Default 0 (no expiration).

register_initial_settings()   X-Ref
Registers default settings available in WordPress.

The settings registered here are primarily useful for the REST API, so this
does not encompass all settings available in WordPress.

since: 4.7.0

register_setting( $option_group, $option_name, $args = array()   X-Ref
Registers a setting and its data.

since: 2.7.0
since: 3.0.0 The `misc` option group was deprecated.
since: 3.5.0 The `privacy` option group was deprecated.
since: 4.7.0 `$args` can be passed to set flags on the setting, similar to `register_meta()`.
since: 5.5.0 `$new_whitelist_options` was renamed to `$new_allowed_options`.
param: string $option_group A settings group name. Should correspond to an allowed option key name.
param: string $option_name The name of an option to sanitize and save.
param: array  $args {

unregister_setting( $option_group, $option_name, $deprecated = '' )   X-Ref
Unregisters a setting.

since: 2.7.0
since: 4.7.0 `$sanitize_callback` was deprecated. The callback from `register_setting()` is now used instead.
since: 5.5.0 `$new_whitelist_options` was renamed to `$new_allowed_options`.
param: string   $option_group The settings group name used during registration.
param: string   $option_name  The name of the option to unregister.
param: callable $deprecated   Optional. Deprecated.

get_registered_settings()   X-Ref
Retrieves an array of registered settings.

since: 4.7.0
return: array List of registered settings, keyed by option name.

filter_default_option( $default, $option, $passed_default )   X-Ref
Filters the default value for the option.

For settings which register a default setting in `register_setting()`, this
function is added as a filter to `default_option_{$option}`.

since: 4.7.0
return: mixed Filtered default value.
param: mixed  $default        Existing default value to return.
param: string $option         Option name.
param: bool   $passed_default Was `get_option()` passed a default value?



Generated: Tue Mar 19 01:00:02 2024 Cross-referenced by PHPXref 0.7.1