root/trunk/wp-includes/functions.php

<?php
/**
 * Main WordPress API
 *
 * @package WordPress
 */

/**
 * Converts MySQL DATETIME field to user specified date format.
 *
 * If $dateformatstring has 'G' value, then gmmktime() function will be used to
 * make the time. If $dateformatstring is set to 'U', then mktime() function
 * will be used to make the time.
 *
 * The $translate will only be used, if it is set to true and it is by default
 * and if the $wp_locale object has the month and weekday set.
 *
 * @since 0.71
 *
 * @param string $dateformatstring Either 'G', 'U', or php date format.
 * @param string $mysqlstring Time from mysql DATETIME field.
 * @param bool $translate Optional. Default is true. Will switch format to locale.
 * @return string Date formated by $dateformatstring or locale (if available).
 */
function mysql2date( $dateformatstring, $mysqlstring, $translate = true ) {
    global $wp_locale;
    $m = $mysqlstring;
    if ( empty( $m ) )
        return false;

    if( 'G' == $dateformatstring ) {
        return gmmktime(
            (int) substr( $m, 11, 2 ), (int) substr( $m, 14, 2 ), (int) substr( $m, 17, 2 ),
            (int) substr( $m, 5, 2 ), (int) substr( $m, 8, 2 ), (int) substr( $m, 0, 4 )
        );
    }

    $i = mktime(
        (int) substr( $m, 11, 2 ), (int) substr( $m, 14, 2 ), (int) substr( $m, 17, 2 ),
        (int) substr( $m, 5, 2 ), (int) substr( $m, 8, 2 ), (int) substr( $m, 0, 4 )
    );

    if( 'U' == $dateformatstring )
        return $i;

    if ( -1 == $i || false == $i )
        $i = 0;

    if ( !empty( $wp_locale->month ) && !empty( $wp_locale->weekday ) && $translate ) {
        $datemonth = $wp_locale->get_month( date( 'm', $i ) );
        $datemonth_abbrev = $wp_locale->get_month_abbrev( $datemonth );
        $dateweekday = $wp_locale->get_weekday( date( 'w', $i ) );
        $dateweekday_abbrev = $wp_locale->get_weekday_abbrev( $dateweekday );
        $datemeridiem = $wp_locale->get_meridiem( date( 'a', $i ) );
        $datemeridiem_capital = $wp_locale->get_meridiem( date( 'A', $i ) );
        $dateformatstring = ' ' . $dateformatstring;
        $dateformatstring = preg_replace( "/([^\\\])D/", "\\1" . backslashit( $dateweekday_abbrev ), $dateformatstring );
        $dateformatstring = preg_replace( "/([^\\\])F/", "\\1" . backslashit( $datemonth ), $dateformatstring );
        $dateformatstring = preg_replace( "/([^\\\])l/", "\\1" . backslashit( $dateweekday ), $dateformatstring );
        $dateformatstring = preg_replace( "/([^\\\])M/", "\\1" . backslashit( $datemonth_abbrev ), $dateformatstring );
        $dateformatstring = preg_replace( "/([^\\\])a/", "\\1" . backslashit( $datemeridiem ), $dateformatstring );
        $dateformatstring = preg_replace( "/([^\\\])A/", "\\1" . backslashit( $datemeridiem_capital ), $dateformatstring );

        $dateformatstring = substr( $dateformatstring, 1, strlen( $dateformatstring ) -1 );
    }
    $j = @date( $dateformatstring, $i );

    /*
    if ( !$j ) // for debug purposes
        echo $i." ".$mysqlstring;
    */

    return $j;
}

/**
 * Retrieve the current time based on specified type.
 *
 * The 'mysql' type will return the time in the format for MySQL DATETIME field.
 * The 'timestamp' type will return the current timestamp.
 *
 * If the $gmt is set to either '1' or 'true', then both types will use the
 * GMT offset in the WordPress option to add the GMT offset to the time.
 *
 * @since 1.0.0
 *
 * @param string $type Either 'mysql' or 'timestamp'.
 * @param int|bool $gmt Optional. Whether to use $gmt offset. Default is false.
 * @return int|string String if $type is 'gmt', int if $type is 'timestamp'.
 */
function current_time( $type, $gmt = 0 ) {
    switch ( $type ) {
        case 'mysql':
            return ( $gmt ) ? gmdate( 'Y-m-d H:i:s' ) : gmdate( 'Y-m-d H:i:s', ( time() + ( get_option( 'gmt_offset' ) * 3600 ) ) );
            break;
        case 'timestamp':
            return ( $gmt ) ? time() : time() + ( get_option( 'gmt_offset' ) * 3600 );
            break;
    }
}

/**
 * Retrieve the date in localized format, based on timestamp.
 *
 * If the locale specifies the locale month and weekday, then the locale will
 * take over the format for the date. If it isn't, then the date format string
 * will be used instead.
 *
 * @since 0.71
 *
 * @param string $dateformatstring Format to display the date
 * @param int $unixtimestamp Unix timestamp
 * @return string The date, translated if locale specifies it.
 */
function date_i18n( $dateformatstring, $unixtimestamp = false, $gmt = false ) {
    global $wp_locale;
    $i = $unixtimestamp;
    // Sanity check for PHP 5.1.0-
    if ( false === $i || intval($i) < 0 ) {
        if ( ! $gmt )
            $i = current_time( 'timestamp' );
        else
            $i = time();
        // we should not let date() interfere with our
        // specially computed timestamp
        $gmt = true;
    }

    $datefunc = $gmt? 'gmdate' : 'date';

    if ( ( !empty( $wp_locale->month ) ) && ( !empty( $wp_locale->weekday ) ) ) {
        $datemonth = $wp_locale->get_month( $datefunc( 'm', $i ) );
        $datemonth_abbrev = $wp_locale->get_month_abbrev( $datemonth );
        $dateweekday = $wp_locale->get_weekday( $datefunc( 'w', $i ) );
        $dateweekday_abbrev = $wp_locale->get_weekday_abbrev( $dateweekday );
        $datemeridiem = $wp_locale->get_meridiem( $datefunc( 'a', $i ) );
        $datemeridiem_capital = $wp_locale->get_meridiem( $datefunc( 'A', $i ) );
        $dateformatstring = ' '.$dateformatstring;
        $dateformatstring = preg_replace( "/([^\\\])D/", "\\1" . backslashit( $dateweekday_abbrev ), $dateformatstring );
        $dateformatstring = preg_replace( "/([^\\\])F/", "\\1" . backslashit( $datemonth ), $dateformatstring );
        $dateformatstring = preg_replace( "/([^\\\])l/", "\\1" . backslashit( $dateweekday ), $dateformatstring );
        $dateformatstring = preg_replace( "/([^\\\])M/", "\\1" . backslashit( $datemonth_abbrev ), $dateformatstring );
        $dateformatstring = preg_replace( "/([^\\\])a/", "\\1" . backslashit( $datemeridiem ), $dateformatstring );
        $dateformatstring = preg_replace( "/([^\\\])A/", "\\1" . backslashit( $datemeridiem_capital ), $dateformatstring );

        $dateformatstring = substr( $dateformatstring, 1, strlen( $dateformatstring ) -1 );
    }
    $j = @$datefunc( $dateformatstring, $i );
    return $j;
}

/**
 * Convert number to format based on the locale.
 *
 * @since 2.3.0
 *
 * @param mixed $number The number to convert based on locale.
 * @param int $decimals Precision of the number of decimal places.
 * @return string Converted number in string format.
 */
function number_format_i18n( $number, $decimals = null ) {
    global $wp_locale;
    // let the user override the precision only
    $decimals = ( is_null( $decimals ) ) ? $wp_locale->number_format['decimals'] : intval( $decimals );

    return number_format( $number, $decimals, $wp_locale->number_format['decimal_point'], $wp_locale->number_format['thousands_sep'] );
}

/**
 * Convert number of bytes largest unit bytes will fit into.
 *
 * It is easier to read 1kB than 1024 bytes and 1MB than 1048576 bytes. Converts
 * number of bytes to human readable number by taking the number of that unit
 * that the bytes will go into it. Supports TB value.
 *
 * Please note that integers in PHP are limited to 32 bits, unless they are on
 * 64 bit architecture, then they have 64 bit size. If you need to place the
 * larger size then what PHP integer type will hold, then use a string. It will
 * be converted to a double, which should always have 64 bit length.
 *
 * Technically the correct unit names for powers of 1024 are KiB, MiB etc.
 * @link http://en.wikipedia.org/wiki/Byte
 *
 * @since 2.3.0
 *
 * @param int|string $bytes Number of bytes. Note max integer size for integers.
 * @param int $decimals Precision of number of decimal places.
 * @return bool|string False on failure. Number string on success.
 */
function size_format( $bytes, $decimals = null ) {
    $quant = array(
        // ========================= Origin ====
        'TB' => 1099511627776,  // pow( 1024, 4)
        'GB' => 1073741824,     // pow( 1024, 3)
        'MB' => 1048576,        // pow( 1024, 2)
        'kB' => 1024,           // pow( 1024, 1)
        'B ' => 1,              // pow( 1024, 0)
    );

    foreach ( $quant as $unit => $mag )
        if ( doubleval($bytes) >= $mag )
            return number_format_i18n( $bytes / $mag, $decimals ) . ' ' . $unit;

    return false;
}

/**
 * Get the week start and end from the datetime or date string from mysql.
 *
 * @since 0.71
 *
 * @param string $mysqlstring Date or datetime field type from mysql.
 * @param int $start_of_week Optional. Start of the week as an integer.
 * @return array Keys are 'start' and 'end'.
 */
function get_weekstartend( $mysqlstring, $start_of_week = '' ) {
    $my = substr( $mysqlstring, 0, 4 ); // Mysql string Year
    $mm = substr( $mysqlstring, 8, 2 ); // Mysql string Month
    $md = substr( $mysqlstring, 5, 2 ); // Mysql string day
    $day = mktime( 0, 0, 0, $md, $mm, $my ); // The timestamp for mysqlstring day.
    $weekday = date( 'w', $day ); // The day of the week from the timestamp
    $i = 86400; // One day
    if( !is_numeric($start_of_week) )
        $start_of_week = get_option( 'start_of_week' );

    if ( $weekday < $start_of_week )
        $weekday = 7 - $start_of_week - $weekday;

    while ( $weekday > $start_of_week ) {
        $weekday = date( 'w', $day );
        if ( $weekday < $start_of_week )
            $weekday = 7 - $start_of_week - $weekday;

        $day -= 86400;
        $i = 0;
    }
    $week['start'] = $day + 86400 - $i;
    $week['end'] = $week['start'] + 604799;
    return $week;
}

/**
 * Unserialize value only if it was serialized.
 *
 * @since 2.0.0
 *
 * @param string $original Maybe unserialized original, if is needed.
 * @return mixed Unserialized data can be any type.
 */
function maybe_unserialize( $original ) {
    if ( is_serialized( $original ) ) // don't attempt to unserialize data that wasn't serialized going in
        if ( false !== $gm = @unserialize( $original ) )
            return $gm;
    return $original;
}

/**
 * Check value to find if it was serialized.
 *
 * If $data is not an string, then returned value will always be false.
 * Serialized data is always a string.
 *
 * @since 2.0.5
 *
 * @param mixed $data Value to check to see if was serialized.
 * @return bool False if not serialized and true if it was.
 */
function is_serialized( $data ) {
    // if it isn't a string, it isn't serialized
    if ( !is_string( $data ) )
        return false;
    $data = trim( $data );
    if ( 'N;' == $data )
        return true;
    if ( !preg_match( '/^([adObis]):/', $data, $badions ) )
        return false;
    switch ( $badions[1] ) {
        case 'a' :
        case 'O' :
        case 's' :
            if ( preg_match( "/^{$badions[1]}:[0-9]+:.*[;}]\$/s", $data ) )
                return true;
            break;
        case 'b' :
        case 'i' :
        case 'd' :
            if ( preg_match( "/^{$badions[1]}:[0-9.E-]+;\$/", $data ) )
                return true;
            break;
    }
    return false;
}

/**
 * Check whether serialized data is of string type.
 *
 * @since 2.0.5
 *
 * @param mixed $data Serialized data
 * @return bool False if not a serialized string, true if it is.
 */
function is_serialized_string( $data ) {
    // if it isn't a string, it isn't a serialized string
    if ( !is_string( $data ) )
        return false;
    $data = trim( $data );
    if ( preg_match( '/^s:[0-9]+:.*;$/s', $data ) ) // this should fetch all serialized strings
        return true;
    return false;
}

/**
 * Retrieve option value based on setting name.
 *
 * If the option does not exist or does not have a value, then the return value
 * will be false. This is useful to check whether you need to install an option
 * and is commonly used during installation of plugin options and to test
 * whether upgrading is required.
 *
 * You can "short-circuit" the retrieval of the option from the database for
 * your plugin or core options that aren't protected. You can do so by hooking
 * into the 'pre_option_$option' with the $option being replaced by the option
 * name. You should not try to override special options, but you will not be
 * prevented from doing so.
 *
 * There is a second filter called 'option_$option' with the $option being
 * replaced with the option name. This gives the value as the only parameter.
 *
 * If the option was serialized, when the option was added and, or updated, then
 * it will be unserialized, when it is returned.
 *
 * @since 1.5.0
 * @package WordPress
 * @subpackage Option
 * @uses apply_filters() Calls 'pre_option_$optionname' false to allow
 *        overwriting the option value in a plugin.
 * @uses apply_filters() Calls 'option_$optionname' with the option name value.
 *
 * @param string $setting Name of option to retrieve. Should already be SQL-escaped
 * @return mixed Value set for the option.
 */
function get_option( $setting, $default = false ) {
    global $wpdb, $switched, $current_blog;

    $wpdb->hide_errors();
    // Allow plugins to short-circuit options.
    $pre = apply_filters( 'pre_option_' . $setting, false );
    if ( false !== $pre )
        return $pre;

    $value = _get_option_cache( $setting );
    if ( false === $value )
            return $default;

    // If home is not set use siteurl.
    if ( 'home' == $setting && '' == $value )
        return get_option( 'siteurl' );

    if ( in_array( $setting, array('siteurl', 'home', 'category_base', 'tag_base') ) )
        $value = untrailingslashit( $value );

    if (! unserialize($value) )
        $value = stripslashes( $value );

    return apply_filters( 'option_' . $setting, maybe_unserialize( $value ) );
}

/**
 * Protect 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
 * @package WordPress
 * @subpackage Option
 *
 * @param string $option Option name.
 */
function wp_protect_special_option( $option ) {
    $protected = array( 'alloptions', 'notoptions' );
    if ( in_array( $option, $protected ) )
        die( sprintf( __( '%s is a protected WP option and may not be modified' ), wp_specialchars( $option ) ) );
}

/**
 * Print option value after sanitizing for forms.
 *
 * @uses attribute_escape Sanitizes value.
 * @since 1.5.0
 * @package WordPress
 * @subpackage Option
 *
 * @param string $option Option name.
 */
function form_option( $option ) {
    echo attribute_escape (get_option( $option ) );
}

/**
 * Retrieve all autoload options or all options, if no autoloaded ones exist.
 *
 * This is different from wp_load_alloptions(), in this that function does not
 * cache all options and will retrieve all options from the database every time
 * it is called.
 *
 * @since 1.0.0
 * @package WordPress
 * @subpackage Option
 * @uses apply_filters() Calls 'pre_option_$optionname' hook with option value as parameter.
 * @uses apply_filters() Calls 'all_options' on options list.
 *
 * @return array List of all options.
 */
function get_alloptions() {
    global $wpdb;
    $show = $wpdb->hide_errors();
    if ( !$options = $wpdb->get_results( "SELECT option_name, option_value FROM $wpdb->options WHERE autoload = 'yes'" ) )
        $options = $wpdb->get_results( "SELECT option_name, option_value FROM $wpdb->options" );
    $wpdb->show_errors($show);

    foreach ( (array) $options as $option ) {
        // "When trying to design a foolproof system,
        //  never underestimate the ingenuity of the fools :)" -- Dougal
        if ( in_array( $option->option_name, array( 'siteurl', 'home', 'category_base', 'tag_base' ) ) )
            $option->option_value = untrailingslashit( $option->option_value );
        $value = maybe_unserialize( $option->option_value );
        $all_options->{$option->option_name} = apply_filters( 'pre_option_' . $option->option_name, $value );
    }
    return apply_filters( 'all_options', $all_options );
}

/**
 * Loads and caches all autoloaded options, if available or all options.
 *
 * This is different from get_alloptions(), in that this function will cache the
 * options and will return the cached options when called again.
 *
 * @since 2.2.0
 * @package WordPress
 * @subpackage Option
 *
 * @return array List all options.
 */
function wp_load_alloptions() {
    global $wpdb;
    global $_wp_alloptions;
    global $blog_id;

    if( !defined( 'WP_INSTALLING' ) ) {
        if ( !empty($_wp_alloptions[$blog_id]) )
            return $_wp_alloptions[$blog_id];

        $alloptions = wp_cache_get('alloptions', 'options');

        if ( false !== $alloptions ) {
            $_wp_alloptions[$blog_id] = $alloptions;
            return $alloptions;
        }

        $_wp_alloptions[$blog_id] = array();
    }

    $suppress = $wpdb->suppress_errors();
    // order by option_id asc in case there are duplicate values - this makes the most recent value overwrite the others in the array
    $alloptions_db = $wpdb->get_results( "SELECT option_name, option_value FROM $wpdb->options FORCE INDEX(PRIMARY) ORDER BY option_id ASC" );
    $wpdb->suppress_errors($suppress);
    foreach ( (array) $alloptions_db as $o )
        $_wp_alloptions[$blog_id][$o->option_name] = $o->option_value;

    wp_cache_set('alloptions', $_wp_alloptions[$blog_id], 'options');

    return $_wp_alloptions[$blog_id];
}

function _get_option_cache( $setting ) {
    global $_wp_alloptions;
    global $blog_id;
    
    wp_load_alloptions();

    if ( isset($_wp_alloptions[$blog_id][$setting]) )
        return $_wp_alloptions[$blog_id][$setting];

    return false;
}

function _set_option_cache( $setting, $value ) {
    global $_wp_alloptions;
    global $blog_id;

    wp_load_alloptions();

    $_wp_alloptions[$blog_id][$setting] = $value;

    wp_cache_delete('alloptions', 'options');
}

function _delete_option_cache( $setting ) {
    global $_wp_alloptions;
    global $blog_id;

    wp_load_alloptions();

    if ( isset($_wp_alloptions[$blog_id][$setting]) )
        unset($_wp_alloptions[$blog_id][$setting]);

    wp_cache_delete('alloptions', 'options');
}

/**
 * Update the value of an option that was already added.
 *
 * You do not need to serialize values, if the value needs to be serialize, then
 * it will be serialized before it is inserted into the database. Remember,
 * resources can not be serialized or added as an option.
 *
 * If the option does not exist, then the option will be added with the option
 * value, but you will not be able to set whether it is autoloaded. If you want
 * to set whether an option autoloaded, then you need to use the add_option().
 *
 * When the option is updated, then the filter named
 * 'update_option_$option_name', with the $option_name as the $option_name
 * parameter value, will be called. The hook should accept two parameters, the
 * first is the old parameter and the second is the new parameter.
 *
 * @since 1.0.0
 * @package WordPress
 * @subpackage Option
 *
 * @param string $option_name Option name. Expected to not be SQL-escaped
 * @param mixed $newvalue Option value.
 * @return bool False if value was not updated and true if value was updated.
 */
function update_option( $option_name, $newvalue ) {
    global $wpdb;

    wp_protect_special_option( $option_name );

    $safe_option_name = $wpdb->escape( $option_name );
    $newvalue = sanitize_option( $option_name, $newvalue );

    $oldvalue = get_option( $safe_option_name );

    $newvalue = apply_filters( 'pre_update_option_' . $option_name, $newvalue, $oldvalue );

    // If the new and old values are the same, no need to update.
    if ( $newvalue === $oldvalue )
        return false;

    if ( false === $oldvalue ) {
        add_option( $option_name, $newvalue );
        return true;
    }

    $_newvalue = $newvalue;
    $newvalue = maybe_serialize( $newvalue );

    _