| [ Index ] |
PHP Cross Reference of WordPress Trunk (Updated Daily) |
[Source view] [Print] [Project Stats]
Option API
| File Size: | 3207 lines (102 kb) |
| Included or required: | 1 time |
| Referenced: | 0 times |
| Includes or requires: | 0 files |
| get_option( $option, $default_value = 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` 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 } param: string $option Name of the option to retrieve. Expected to not be SQL-escaped. param: mixed $default_value Optional. Default value to return if the option does not exist. return: mixed Value of the option. A value of any type may be returned, including |
| wp_prime_option_caches( $options ) X-Ref |
| Primes specific options into the cache with a single database query. Only options that do not already exist in cache will be loaded. param: string[] $options An array of option names to be loaded. |
| wp_prime_option_caches_by_group( $option_group ) X-Ref |
| Primes the cache of all options registered with a specific option group. param: string $option_group The option group to load options for. |
| get_options( $options ) X-Ref |
| Retrieves multiple options. Options are loaded as necessary first in order to use a single database query at most. param: string[] $options An array of option names to retrieve. return: array An array of key-value pairs for the requested options. |
| wp_set_option_autoload_values( array $options ) X-Ref |
| Sets the autoload values for multiple options in the database. Autoloading too many options can lead to performance problems, especially if the options are not frequently used. This function allows modifying the autoload value for multiple options without changing the actual option value. This is for example recommended for plugin activation and deactivation hooks, to ensure any options exclusively used by the plugin which are generally autoloaded can be set to not autoload when the plugin is inactive. param: array $options Associative array of option names and their autoload values to set. The option names are return: array Associative array of all provided $options as keys and boolean values for whether their autoload value |
| wp_set_options_autoload( array $options, $autoload ) X-Ref |
| Sets the autoload value for multiple options in the database. This is a wrapper for {@see wp_set_option_autoload_values()}, which can be used to set different autoload values for each option at once. param: string[] $options List of option names. Expected to not be SQL-escaped. param: bool $autoload Autoload value to control whether to load the options when WordPress starts up. return: array Associative array of all provided $options as keys and boolean values for whether their autoload value |
| wp_set_option_autoload( $option, $autoload ) X-Ref |
| Sets the autoload value for an option in the database. This is a wrapper for {@see wp_set_option_autoload_values()}, which can be used to set the autoload value for multiple options at once. param: string $option Name of the option. Expected to not be SQL-escaped. param: bool $autoload Autoload value to control whether to load the option when WordPress starts up. return: bool True if the autoload value was modified, false otherwise. |
| 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. param: string $option Option name. |
| form_option( $option ) X-Ref |
| Prints option value after sanitizing for forms. param: string $option Option name. |
| wp_load_alloptions( $force_cache = false ) X-Ref |
| Loads and caches all autoloaded options, if available or all options. param: bool $force_cache Optional. Whether to force an update of the local cache return: array List of all options. |
| wp_prime_site_option_caches( array $options ) X-Ref |
| Primes specific network options for the current network into the cache with a single database query. Only network options that do not already exist in cache will be loaded. If site is not multisite, then call wp_prime_option_caches(). param: string[] $options An array of option names to be loaded. |
| wp_prime_network_option_caches( $network_id, array $options ) X-Ref |
| Primes specific network options into the cache with a single database query. Only network options that do not already exist in cache will be loaded. If site is not multisite, then call wp_prime_option_caches(). param: int $network_id ID of the network. Can be null to default to the current network ID. param: string[] $options An array of option names to be loaded. |
| wp_load_core_site_options( $network_id = null ) X-Ref |
| Loads and primes caches of certain often requested network options if is_multisite(). param: int $network_id Optional. Network ID of network for which to prime network options cache. Defaults to current network. |
| 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. 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: bool|null $autoload Optional. Whether to load the option when WordPress starts up. return: bool True if the value was updated, false otherwise. |
| add_option( $option, $value = '', $deprecated = '', $autoload = null ) 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. 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: bool|null $autoload Optional. Whether to load the option when WordPress starts up. return: bool True if the option was added, false otherwise. |
| delete_option( $option ) X-Ref |
| Removes an option by name. Prevents removal of protected WordPress options. param: string $option Name of the option to delete. Expected to not be SQL-escaped. return: bool True if the option was deleted, false otherwise. |
| wp_determine_option_autoload_value( $option, $value, $serialized_value, $autoload ) X-Ref |
| Determines the appropriate autoload value for an option based on input. This function checks the provided autoload value and returns a standardized value ('on', 'off', 'auto-on', 'auto-off', or 'auto') based on specific conditions. If no explicit autoload value is provided, the function will check for certain heuristics around the given option. It will return `auto-on` to indicate autoloading, `auto-off` to indicate not autoloading, or `auto` if no clear decision could be made. param: string $option The name of the option. param: mixed $value The value of the option to check its autoload value. param: mixed $serialized_value The serialized value of the option to check its autoload value. param: bool|null $autoload The autoload value to check. return: string Returns the original $autoload value if explicit, or 'auto-on', 'auto-off', |
| wp_filter_default_autoload_value_via_option_size( $autoload, $option, $value, $serialized_value ) X-Ref |
| Filters the default autoload value to disable autoloading if the option value is too large. param: bool|null $autoload The default autoload value to set. param: string $option The passed option name. param: mixed $value The passed option value to be saved. param: mixed $serialized_value The passed option value to be saved, in serialized form. return: bool|null Potentially modified $default. |
| delete_transient( $transient ) X-Ref |
| Deletes a transient. param: string $transient Transient name. Expected to not be SQL-escaped. return: bool True if the transient was deleted, false otherwise. |
| 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. param: string $transient Transient name. Expected to not be SQL-escaped. return: mixed Value of transient. |
| 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. 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). return: bool True if the value was set, false otherwise. |
| delete_expired_transients( $force_db = false ) X-Ref |
| Deletes all expired transients. Note that this function won't do anything if an external object cache is in use. The multi-table delete syntax is used to delete the transient record from table a, and the corresponding transient_timeout record from table b. 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. |
| get_user_setting( $name, $default_value = false ) X-Ref |
| Retrieves user interface setting value based on setting name. param: string $name The name of the setting. param: string|false $default_value Optional. Default value to return when $name is not set. Default false. return: mixed The last saved user setting or the default value/false if it doesn't exist. |
| 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()`. param: string $name The name of the setting. param: string $value The value for the setting. return: bool|null True if set successfully, false otherwise. |
| 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()`. param: string $names The name or array of names of the setting to be deleted. return: bool|null True if deleted successfully, false otherwise. |
| get_all_user_settings() X-Ref |
| Retrieves all user interface settings. 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. param: array $user_settings User settings. return: bool|null True if set successfully, false if the current user could not be found. |
| delete_all_user_settings() X-Ref |
| Deletes the user settings of the current user. |
| get_site_option( $option, $default_value = false, $deprecated = true ) X-Ref |
| Retrieve an option value for the current network based on name of option. param: string $option Name of the option to retrieve. Expected to not be SQL-escaped. param: mixed $default_value 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. return: mixed Value set for the option. |
| 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. 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. return: bool True if the option was added, false otherwise. |
| delete_site_option( $option ) X-Ref |
| Removes an option by name for the current network. param: string $option Name of the option to delete. Expected to not be SQL-escaped. return: bool True if the option was deleted, false otherwise. |
| update_site_option( $option, $value ) X-Ref |
| Updates the value of an option that was already added for the current network. param: string $option Name of the option. Expected to not be SQL-escaped. param: mixed $value Option value. Expected to not be SQL-escaped. return: bool True if the value was updated, false otherwise. |
| get_network_option( $network_id, $option, $default_value = false ) X-Ref |
| Retrieves a network's option value based on the option name. 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_value Optional. Value to return if the option doesn't exist. Default false. return: mixed Value set for the option. |
| add_network_option( $network_id, $option, $value ) X-Ref |
| Adds a new network option. Existing options will not be updated. 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. return: bool True if the option was added, false otherwise. |
| delete_network_option( $network_id, $option ) X-Ref |
| Removes a network option by name. 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. return: bool True if the option was deleted, false otherwise. |
| update_network_option( $network_id, $option, $value ) X-Ref |
| Updates the value of a network option that was already added. 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. return: bool True if the value was updated, false otherwise. |
| delete_site_transient( $transient ) X-Ref |
| Deletes a site transient. param: string $transient Transient name. Expected to not be SQL-escaped. return: bool True if the transient was deleted, false otherwise. |
| 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. param: string $transient Transient name. Expected to not be SQL-escaped. return: mixed Value of transient. |
| 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. 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). return: bool True if the value was set, false otherwise. |
| 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. |
| register_setting( $option_group, $option_name, $args = array() X-Ref |
| Registers a setting and its data. 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. 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. return: array List of registered settings, keyed by option name. |
| filter_default_option( $default_value, $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}`. param: mixed $default_value Existing default value to return. param: string $option Option name. param: bool $passed_default Was `get_option()` passed a default value? return: mixed Filtered default value. |
| wp_autoload_values_to_autoload() X-Ref |
| Returns the values that trigger autoloading from the options table. return: string[] The values that trigger autoloading. |
| Generated : Tue Dec 24 08:20:01 2024 | Cross-referenced by PHPXref |