Make WordPress Core


Ignore:
Timestamp:
05/31/2021 11:59:16 PM (3 years ago)
Author:
azaozz
Message:

Docs: Improve documentation for get_option(). Clean up, clarify the returned types and the exceptions, and add few examples.

Props ReneHermi, johnbillion, azaozz
See #51278

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/option.php

    r49942 r51050  
    1010 * Retrieves an option value based on an option name.
    1111 *
    12  * If the option does not exist or does not have a value, then the return value
    13  * will be false. This is useful to check whether you need to install an option
    14  * and is commonly used during installation of plugin options and to test
    15  * whether upgrading is required.
    16  *
    17  * If the option was serialized then it will be unserialized when it is returned.
    18  *
    19  * Any scalar values will be returned as strings. You may coerce the return type of
    20  * a given option by registering an {@see 'option_$option'} filter callback.
     12 * If the option does not exist, and a default value is not provided,
     13 * boolean false is returned. This could be used to check whether you need
     14 * to initialize an option during installation of a plugin, however that
     15 * can be done better by using {@see add_option} which will not overwrite
     16 * existing options.
     17 *
     18 * Not initializing an option and using the boolean false as a return value
     19 * is a bad practice as it triggers an additional database query.
     20 *
     21 * The type of the returned value can be different from the type that was passed
     22 * when saving or updating the option. If the option value was serialized,
     23 * then it will be unserialized when it is returned. In this case the type will
     24 * be the same. For example, storing a non-scalar value like an array will
     25 * return the same array.
     26 *
     27 * In most cases non-string scalar and null values will be converted and returned
     28 * as string equivalents.
     29 *
     30 * Exceptions:
     31 * 1. When the option has not been saved in the database, the default value
     32 *    {@see get_option} is returned if provided. If not, boolean `false` is returned.
     33 * 2. When one of the Options API filters is used: {@see pre_option_{$option}},
     34 *    {@see default_option_{$option}}, and {@see option_{$option}}, the returned
     35 *    value may not match the expected type.
     36 * 3. When the option has just been saved in the database, and {@see get_option}
     37 *    is used right after, non-string scalar and null values are not converted to
     38 *    string equivalents and the original type is returned.
     39 *
     40 * Examples:
     41 *
     42 * When adding options like this: `add_option( 'my_option_name', 'value' );`
     43 * and then retrieving them with `get_option( 'my_option_name' )`, the returned
     44 * values will be:
     45 *
     46 * `false` returns `string(0) ""`
     47 * `true`  returns `string(1) "1"`
     48 * `0`     returns `string(1) "0"`
     49 * `1`     returns `string(1) "1"`
     50 * `'0'`   returns `string(1) "0"`
     51 * `'1'`   returns `string(1) "1"`
     52 * `null`  returns `string(0) ""`
     53 *
     54 * When adding options with non-scalar values like
     55 * `add_option( 'my_array', array( false, 'str', null ) );`, the returned value
     56 * will be identical to the original as it is serialized before saving
     57 * it in the database:
     58 *
     59 *    array(3) {
     60 *        [0] => bool(false)
     61 *        [1] => string(3) "str"
     62 *        [2] => NULL
     63 *    }
    2164 *
    2265 * @since 1.5.0
     
    2669 * @param string $option  Name of the option to retrieve. Expected to not be SQL-escaped.
    2770 * @param mixed  $default Optional. Default value to return if the option does not exist.
    28  * @return mixed Value set for the option. A value of any type may be returned, including
    29  *               array, boolean, float, integer, null, object, and string.
     71 * @return mixed Value of the option. A value of any type may be returned, including
     72 *               scalar (string, boolean, float, integer), null, array, object.
     73 *               Scalar and null values will be returned as strings as long as they originate
     74 *               from a database stored option value. If there is no option in the database,
     75 *               boolean `false` is returned.
    3076 */
    3177function get_option( $option, $default = false ) {
Note: See TracChangeset for help on using the changeset viewer.