WordPress.org

Make WordPress Core

Changeset 13142


Ignore:
Timestamp:
02/14/10 07:21:15 (5 years ago)
Author:
nacin
Message:

More cleanups of the options/transients APIs. More inline documentation, better return values (always true on success, false on failure). Only call actions that are after wpdb delete/update operations if the operation was successful. See #10788

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/wp-includes/functions.php

    r13139 r13142  
    290290 
    291291/** 
    292  * Retrieve option value based on setting name. 
     292 * Retrieve option value based on name of option. 
    293293 * 
    294294 * If the option does not exist or does not have a value, then the return value 
     
    297297 * whether upgrading is required. 
    298298 * 
    299  * You can "short-circuit" the retrieval of the option from the database for 
    300  * your plugin or core options that aren't protected. You can do so by hooking 
    301  * into the 'pre_option_$option' with the $option being replaced by the option 
    302  * name. You should not try to override special options, but you will not be 
    303  * prevented from doing so. 
    304  * 
    305  * There is a second filter called 'option_$option' with the $option being 
    306  * replaced with the option name. This gives the value as the only parameter. 
    307  * 
    308  * If the option was serialized, when the option was added and, or updated, then 
    309  * it will be unserialized, when it is returned. 
     299 * If the option was serialized then it will be unserialized when it is returned. 
    310300 * 
    311301 * @since 1.5.0 
    312302 * @package WordPress 
    313303 * @subpackage Option 
    314  * @uses apply_filters() Calls 'pre_option_$option' false to allow 
    315  *      overwriting the option value in a plugin. 
    316  * @uses apply_filters() Calls 'option_$option' with the option value. 
     304 * @uses apply_filters() Calls 'pre_option_$option' before checking the option. 
     305 *  Any value other than false will "short-circuit" the retrieval of the option 
     306 *  and return the returned value. You should not try to override special options, 
     307 *  but you will not be prevented from doing so. 
     308 * @uses apply_filters() Calls 'option_$option', after checking the option, with 
     309 *  the option value. 
    317310 * 
    318311 * @param string $option Name of option to retrieve. Should already be SQL-escaped 
     
    389382    $protected = array( 'alloptions', 'notoptions' ); 
    390383    if ( in_array( $option, $protected ) ) 
    391         die( sprintf( __( '%s is a protected WP option and may not be modified' ), esc_html( $option ) ) ); 
     384        wp_die( sprintf( __( '%s is a protected WP option and may not be modified' ), esc_html( $option ) ) ); 
    392385} 
    393386 
     
    403396 */ 
    404397function form_option( $option ) { 
    405     echo esc_attr(get_option( $option ) ); 
     398    echo esc_attr( get_option( $option ) ); 
    406399} 
    407400 
     
    473466 * Update the value of an option that was already added. 
    474467 * 
    475  * You do not need to serialize values, if the value needs to be serialize, then 
     468 * You do not need to serialize values. If the value needs to be serialized, then 
    476469 * it will be serialized before it is inserted into the database. Remember, 
    477470 * resources can not be serialized or added as an option. 
     
    479472 * If the option does not exist, then the option will be added with the option 
    480473 * value, but you will not be able to set whether it is autoloaded. If you want 
    481  * to set whether an option autoloaded, then you need to use the add_option(). 
    482  * 
    483  * Before the option is updated, then the filter named 
    484  * 'pre_update_option_$option', with the $option as the $option 
    485  * parameter value, will be called. The hook should accept two parameters, the 
    486  * first is the new value and the second is the old value.  Whatever is 
    487  * returned will be used as the new value. 
    488  * 
    489  * After the value has been updated the action named 'update_option_$option' 
    490  * will be called.  This action receives two parameters the first being the old 
    491  * value and the second the new value. 
     474 * to set whether an option is autoloaded, then you need to use the add_option(). 
    492475 * 
    493476 * @since 1.0.0 
    494477 * @package WordPress 
    495478 * @subpackage Option 
     479 * 
     480 * @uses apply_filters() Calls 'pre_update_option_$option' hook to allow overwriting the 
     481 *  option value to be stored. 
     482 * @uses do_action() Calls 'update_option_$option' and 'updated_option' hooks on success. 
    496483 * 
    497484 * @param string $option Option name. Expected to not be SQL-escaped 
     
    504491    wp_protect_special_option( $option ); 
    505492 
    506     $safe_option_name = esc_sql( $option ); 
     493    $safe_option = esc_sql( $option ); 
    507494    $newvalue = sanitize_option( $option, $newvalue ); 
    508  
    509     $oldvalue = get_option( $safe_option_name ); 
    510  
     495    $oldvalue = get_option( $safe_option ); 
    511496    $newvalue = apply_filters( 'pre_update_option_' . $option, $newvalue, $oldvalue ); 
    512497 
     
    551536 * Add a new option. 
    552537 * 
    553  * You do not need to serialize values, if the value needs to be serialize, then 
     538 * You do not need to serialize values. If the value needs to be serialized, then 
    554539 * it will be serialized before it is inserted into the database. Remember, 
    555540 * resources can not be serialized or added as an option. 
     
    558543 * check whether the option has already been added, but does check that you 
    559544 * aren't adding a protected WordPress option. Care should be taken to not name 
    560  * options, the same as the ones which are protected and to not add options 
     545 * options the same as the ones which are protected and to not add options 
    561546 * that were already added. 
    562  * 
    563  * The filter named 'add_option_$option', with the $optionname being 
    564  * replaced with the option's name, will be called. The hook should accept two 
    565  * parameters, the first is the option name, and the second is the value. 
    566547 * 
    567548 * @package WordPress 
     
    569550 * @since 1.0.0 
    570551 * @link http://alex.vort-x.net/blog/ Thanks Alex Stapleton 
     552 * 
     553 * @uses do_action() Calls 'add_option_$option' and 'added_option' hooks on success. 
    571554 * 
    572555 * @param string $option Name of option to add. Expects to NOT be SQL escaped. 
     
    583566 
    584567    wp_protect_special_option( $option ); 
    585     $safe_name = esc_sql( $option ); 
     568    $safe_option = esc_sql( $option ); 
    586569    $value = sanitize_option( $option, $value ); 
    587570 
     
    589572    $notoptions = wp_cache_get( 'notoptions', 'options' ); 
    590573    if ( !is_array( $notoptions ) || !isset( $notoptions[$option] ) ) 
    591         if ( false !== get_option( $safe_name ) ) 
     574        if ( false !== get_option( $safe_option ) ) 
    592575            return; 
    593576 
     
    614597    $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, $value, $autoload ) ); 
    615598 
    616     do_action( "add_option_{$option}", $option, $value ); 
    617     do_action( 'added_option', $option, $value ); 
    618  
    619     return $result; 
     599    if ( $result ) { 
     600        do_action( "add_option_{$option}", $option, $value ); 
     601        do_action( 'added_option', $option, $value ); 
     602        return true; 
     603    } 
     604    return false; 
    620605} 
    621606 
     
    626611 * @subpackage Option 
    627612 * @since 1.2.0 
     613 * 
     614 * @uses do_action() Calls 'delete_option' hook before option is deleted. 
     615 * @uses do_action() Calls 'deleted_option' hook on success. 
    628616 * 
    629617 * @param string $option Name of option to remove. 
     
    654642        } 
    655643    } 
    656     do_action( 'deleted_option', $option ); 
    657     return true; 
     644    if ( $result ) { 
     645        do_action( 'deleted_option', $option ); 
     646        return true; 
     647    } 
     648    return false; 
    658649} 
    659650 
     
    686677 * If the transient does not exist or does not have a value, then the return value 
    687678 * will be false. 
     679 * 
     680 * @uses apply_filters() Calls 'pre_transient_$transient' hook before checking the transient. 
     681 *  Any value other than false will "short-circuit" the retrieval of the transient 
     682 *  and return the returned value. 
     683 * @uses apply_filters() Calls 'transient_$option' hook, after checking the transient, with 
     684 *  the transient value. 
    688685 * 
    689686 * @since 2.8.0 
     
    734731 * @package WordPress 
    735732 * @subpackage Transient 
     733 * 
     734 * @uses apply_filters() Calls 'pre_set_transient_$transient' hook to allow overwriting the 
     735 *  transient value to be stored. 
    736736 * 
    737737 * @param string $transient Transient name. Expected to not be SQL-escaped 
     
    33493349 * @since 2.8.0 
    33503350 * 
     3351 * @uses apply_filters() Calls 'pre_site_option_$option' before checking the option. 
     3352 *  Any value other than false will "short-circuit" the retrieval of the option 
     3353 *  and return the returned value. 
     3354 * @uses apply_filters() Calls 'site_option_$option', after checking the  option, with 
     3355 *  the option value. 
     3356 * 
    33513357 * @param string $option Name of option to retrieve. Should already be SQL-escaped 
    33523358 * @param mixed $default Optional value to return if option doesn't exist. Default false. 
     
    33923398 * @since 2.8.0 
    33933399 * 
     3400 * @uses apply_filters() Calls 'pre_add_site_option_$option' hook to allow overwriting the 
     3401 *  option value to be stored. 
     3402 * @uses do_action() Calls 'add_site_option_$option' and 'add_site_option' hooks on success. 
     3403 * 
    33943404 * @param string $option Name of option to add. Expects to not be SQL escaped. 
    33953405 * @param mixed $value Optional. Option value, can be anything. 
     
    34303440 * @subpackage Option 
    34313441 * @since 2.8.0 
     3442 * 
     3443 * @uses do_action() Calls 'pre_delete_site_option_$option' hook before option is deleted. 
     3444 * @uses do_action() Calls 'delete_site_option' and 'delete_site_option_$option' 
     3445 *  hooks on success. 
    34323446 * 
    34333447 * @param string $option Name of option to remove. Expected to be SQL-escaped. 
     
    34663480 * @subpackage Option 
    34673481 * 
     3482 * @uses apply_filters() Calls 'pre_update_site_option_$option' hook to allow overwriting the 
     3483 *  option value to be stored. 
     3484 * @uses do_action() Calls 'update_site_option_$option' and 'update_site_option' hooks on success. 
     3485 * 
    34683486 * @param string $option Name of option. Expected to not be SQL-escaped 
    34693487 * @param mixed $value Option value. 
     
    34933511    } 
    34943512 
    3495     do_action( "update_site_option_{$option}", $option, $value ); 
    3496     do_action( "update_site_option", $option, $value ); 
    3497     return $result; 
     3513    if ( $result ) { 
     3514        do_action( "update_site_option_{$option}", $option, $value ); 
     3515        do_action( "update_site_option", $option, $value ); 
     3516        return true; 
     3517    } 
     3518    return false; 
    34983519} 
    34993520 
     
    35303551 * @package WordPress 
    35313552 * @subpackage Transient 
     3553 * 
     3554 * @uses apply_filters() Calls 'pre_site_transient_$transient' hook before checking the transient. 
     3555 *  Any value other than false will "short-circuit" the retrieval of the transient 
     3556 *  and return the returned value. 
     3557 * @uses apply_filters() Calls 'site_transient_$option' hook, after checking the transient, with 
     3558 *  the transient value. 
    35323559 * 
    35333560 * @param string $transient Transient name. Expected to not be SQL-escaped 
Note: See TracChangeset for help on using the changeset viewer.