WP Merge to rev 8216

git-svn-id: http://svn.automattic.com/wordpress-mu/trunk@1344 7be80a69-a1ef-0310-a953-fb0f7c49ff36

1 files changed, 229 insertions, 39 deletions

diff --git a/wp-includes/functions.php b/wp-includes/functions.php
index bcf0b79..c488fdd 100644
--- a/wp-includes/functions.php
+++ b/wp-includes/functions.php
@@ -99,10 +99,26 @@ function current_time( $type, $gmt = 0 ) {
 	}
 }
 
-
+/**
+ * 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 ) {
 	global $wp_locale;
 	$i = $unixtimestamp;
+	// Sanity check for PHP 5.1.0-
+	if ( -1 == $i )
+		$i = false;
+	
 	if ( ( !empty( $wp_locale->month ) ) && ( !empty( $wp_locale->weekday ) ) ) {
 		$datemonth = $wp_locale->get_month( date( 'm', $i ) );
 		$datemonth_abbrev = $wp_locale->get_month_abbrev( $datemonth );
@@ -276,16 +292,29 @@ function is_serialized_string( $data ) {
 	return false;
 }
 
-/* Options functions */
-
 /**
  * Retrieve option value based on setting name.
  *
- * {@internal Missing Long Description}}
+ * 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.
  *
  * @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.
@@ -347,6 +376,21 @@ 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, $wp_queries;
 	$show = $wpdb->hide_errors();
@@ -357,7 +401,7 @@ function get_alloptions() {
 	foreach ( $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' ) ) )
+		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 );
@@ -365,7 +409,18 @@ function get_alloptions() {
 	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;
@@ -432,7 +487,26 @@ function _delete_option_cache( $setting ) {
 	wp_cache_delete('alloptions', 'options');
 }
 
-// expects $option_name to NOT be SQL-escaped
+/**
+ * Update the value of an option that was already added.
+ *
+ * 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;
 
@@ -464,9 +538,30 @@ function update_option( $option_name, $newvalue ) {
 	return false;
 }
 
-
-// thx Alex Stapleton, http://alex.vort-x.net/blog/
-// expects $name to NOT be SQL-escaped
+/**
+ * Add a new option.
+ *
+ * You can create options without values and then add values later. Does not
+ * check whether the option has already been added, but does check 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 and to not add options
+ * that were already added.
+ *
+ * The filter named 'add_option_$optionname', with the $optionname being
+ * replaced with the option's name, will be called. The hook should accept two
+ * parameters, the first is the option name, and the second is the value.
+ *
+ * @package WordPress
+ * @subpackage Option
+ * @since 1.0.0
+ * @link http://alex.vort-x.net/blog/ Thanks Alex Stapleton
+ *
+ * @param string $name Option name to add. Expects to NOT be SQL escaped.
+ * @param mixed $value Optional. Option value, can be anything.
+ * @param mixed $deprecated Optional. Description. Not used anymore.
+ * @param bool $autoload Optional. Default is enabled. Whether to load the option when WordPress starts up.
+ * @return null returns when finished.
+ */
 function add_option( $name, $value = '', $deprecated = '', $autoload = 'yes' ) {
 	global $wpdb;
 
@@ -484,11 +579,20 @@ function add_option( $name, $value = '', $deprecated = '', $autoload = 'yes' ) {
 
 	$wpdb->query( $wpdb->prepare( "INSERT INTO $wpdb->options (option_name, option_value, autoload) VALUES (%s, %s, %s)", $name, $value, $autoload ) );
 
-	do_action( "add_option_{$name}", $name, $value ); 
+	do_action( "add_option_{$name}", $name, $value );
 	return;
 }
 
-
+/**
+ * Removes option by name and prevents removal of protected WordPress options.
+ *
+ * @package WordPress
+ * @subpackage Option
+ * @since unknown
+ *
+ * @param string $name Option name to remove.
+ * @return bool True, if succeed. False, if failure.
+ */
 function delete_option( $name ) {
 	global $wpdb;
 
@@ -503,11 +607,15 @@ function delete_option( $name ) {
 		return false;
 	// expected_slashed ($name)
 	$wpdb->query( "DELETE FROM $wpdb->options WHERE option_name = '$name'" );
-
 	return true;
 }
 
-
+/**
+ * Serialize data, if needed.
+ *
+ * @param mixed $data Data that might be serialized.
+ * @return mixed A scalar data
+ */
 function maybe_serialize( $data ) {
 	if ( is_string( $data ) )
 		return $data;
@@ -571,7 +679,22 @@ function xmlrpc_removepostdata( $content ) {
 	return $content;
 }
 
-
+/**
+ * Open the file handle for debugging.
+ *
+ * This function is used for XMLRPC feature, but it is general purpose enough
+ * to be used in anywhere.
+ *
+ * @see fopen() for mode options.
+ * @package WordPress
+ * @subpackage Debug
+ * @since unknown
+ * @uses $debug Used for whether debugging is enabled.
+ *
+ * @param string $filename File path to debug file.
+ * @param string $mode Same as fopen() mode parameter.
+ * @return bool|resource File handle. False on failure.
+ */
 function debug_fopen( $filename, $mode ) {
 	global $debug;
 	if ( 1 == $debug ) {
@@ -582,14 +705,39 @@ function debug_fopen( $filename, $mode ) {
 	}
 }
 
-
+/**
+ * Write contents to the file used for debugging.
+ *
+ * Technically, this can be used to write to any file handle when the global
+ * $debug is set to 1 or true.
+ *
+ * @package WordPress
+ * @subpackage Debug
+ * @since unknown
+ * @uses $debug Used for whether debugging is enabled.
+ *
+ * @param resource $fp File handle for debugging file.
+ * @param string $string Content to write to debug file.
+ */
 function debug_fwrite( $fp, $string ) {
 	global $debug;
 	if ( 1 == $debug )
 		fwrite( $fp, $string );
 }
 
-
+/**
+ * Close the debugging file handle.
+ *
+ * Technically, this can be used to close any file handle when the global $debug
+ * is set to 1 or true.
+ *
+ * @package WordPress
+ * @subpackage Debug
+ * @since unknown
+ * @uses $debug Used for whether debugging is enabled.
+ *
+ * @param resource $fp Debug File handle.
+ */
 function debug_fclose( $fp ) {
 	global $debug;
 	if ( 1 == $debug )
@@ -758,19 +906,34 @@ function is_new_day() {
 		return 0;
 }
 
-
+/**
+ * Build URL query based on an associative and, or indexed array.
+ *
+ * This is a convenient function for easily building url queries. It sets the
+ * separator to '&' and uses _http_build_query() function.
+ *
+ * @see _http_build_query() Used to build the query
+ * @link http://us2.php.net/manual/en/function.http-build-query.php more on what
+ *		http_build_query() does.
+ *
+ * @since unknown
+ *
+ * @param array $data URL-encode key/value pairs.
+ * @return string URL encoded string
+ */
 function build_query( $data ) {
 	return _http_build_query( $data, NULL, '&', '', false );
 }
 
 /**
- * Retrieve a modified query string.
+ * Retrieve a modified URL query string.
  *
- * {@internal Missing Long Description}}
+ * You can rebuild the URL and append a new query variable to the URL query by
+ * using this function. You can also retrieve the full URL with query data.
  *
- * Adding a single key & value or an associative array.
- * Setting a key value to emptystring removes the key.
- * Omitting oldquery_or_uri uses the $_SERVER value.
+ * Adding a single key & value or an associative array. Setting a key value to
+ * emptystring removes the key. Omitting oldquery_or_uri uses the $_SERVER
+ * value.
  *
  * @since 1.5.0
  *
@@ -883,6 +1046,17 @@ function add_magic_quotes( $array ) {
 	return $array;
 }
 
+/**
+ * HTTP request for URI to retrieve content.
+ *
+ * Tries to retrieve the HTTP content with fopen first and then using cURL, if
+ * fopen can't be used.
+ *
+ * @since unknown
+ *
+ * @param string $uri URI/URL of web page to retrieve.
+ * @return string HTTP content.
+ */
 function wp_remote_fopen( $uri ) {
 	$timeout = 10;
 	$parsed_url = @parse_url( $uri );
@@ -994,7 +1168,17 @@ function get_status_header_desc( $code ) {
 		return '';
 }
 
-
+/**
+ * Set HTTP status header.
+ *
+ * @since unknown
+ * @uses apply_filters() Calls 'status_header' on status header string, HTTP
+ *		HTTP code, HTTP code description, and protocol string as separate
+ *		parameters.
+ *
+ * @param int $header HTTP status code
+ * @return null Does not return anything.
+ */
 function status_header( $header ) {
 	$text = get_status_header_desc( $header );
 
@@ -1292,10 +1476,9 @@ function wp_upload_dir( $time = NULL ) {
 
 	// $dir is absolute, $path is (maybe) relative to ABSPATH
 	$dir = path_join( ABSPATH, $upload_path );
-	$path = str_replace( ABSPATH, '', trim( $upload_path ) );
 
 	if ( !$url = get_option( 'upload_url_path' ) )
-		$url = trailingslashit( $siteurl ) . $path;
+		$url = WP_CONTENT_URL . '/uploads';
 
 	if ( defined('UPLOADS') ) {
 		$dir = ABSPATH . UPLOADS;
@@ -1789,7 +1972,6 @@ function wp_ob_end_flush_all() {
 	while ( @ob_end_flush() );
 }
 
-
 /**
  * Load the correct database class file.
  *
@@ -1808,7 +1990,6 @@ function require_wp_db() {
 		require_once( ABSPATH . WPINC . '/wp-db.php' );
 }
 
-
 /**
  * Load custom DB error or display WordPress DB error.
  *
@@ -1856,7 +2037,6 @@ function dead_db() {
 	die();
 }
 
-
 /**
  * Converts value to positive integer.
  *
@@ -1869,7 +2049,6 @@ function absint( $maybeint ) {
 	return abs( intval( $maybeint ) );
 }
 
-
 /**
  * Determines if the blog can be accessed over SSL.
  *
@@ -1903,7 +2082,6 @@ function url_is_accessable_via_ssl($url)
 	return false;
 }
 
-
 /**
  * Secure URL, if available or the given URL.
  *
@@ -1920,7 +2098,6 @@ function atom_service_url_filter($url)
 		return $url;
 }
 
-
 /**
  * Marks a function as deprecated and informs when it has been used.
  *
@@ -1958,7 +2135,6 @@ function _deprecated_function($function, $version, $replacement=null) {
 	}
 }
 
-
 /**
  * Marks a file as deprecated and informs when it has been used.
  *
@@ -1996,7 +2172,6 @@ function _deprecated_file($file, $version, $replacement=null) {
 	}
 }
 
-
 /**
  * Is the server running earlier than 1.5.0 version of lighttpd
  *
@@ -2010,7 +2185,6 @@ function is_lighttpd_before_150() {
 	return  'lighttpd' == $server_parts[0] && -1 == version_compare( $server_parts[1], '1.5.0' );
 }
 
-
 /**
  * Does the specified module exist in the apache config?
  *
@@ -2040,7 +2214,6 @@ function apache_mod_loaded($mod, $default = false) {
 	return $default;
 }
 
-
 /**
  * File validates against allowed set of defined rules.
  *
@@ -2071,7 +2244,6 @@ function validate_file( $file, $allowed_files = '' ) {
 	return 0;
 }
 
-
 /**
  * Determine if SSL is used.
  *
@@ -2083,7 +2255,6 @@ function is_ssl() {
 	return ( 'on' == strtolower($_SERVER['HTTPS']) ) ? true : false; 
 }
 
-
 /**
  * Whether SSL login should be forced.
  *
@@ -2104,7 +2275,6 @@ function force_ssl_login($force = '') {
 	return $forced;
 }
 
-
 /**
  * Whether to force SSL used for the Administration Panels.
  *
@@ -2125,4 +2295,24 @@ function force_ssl_admin($force = '') {
 	return $forced;
 }
 
+/**
+ * Guess the URL for the site.
+ *
+ * Will remove wp-admin links to retrieve only return URLs not in the wp-admin
+ * directory.
+ *
+ * @since 2.6
+ *
+ * @return string
+ */
+function wp_guess_url() {
+	if ( defined('WP_SITEURL') && '' != WP_SITEURL ) {
+		$url = WP_SITEURL;
+	} else {
+		$schema = ( isset($_SERVER['HTTPS']) && strtolower($_SERVER['HTTPS']) == 'on' ) ? 'https://' : 'http://';
+		$url = preg_replace('|/wp-admin/.*|i', '', $schema . $_SERVER['HTTP_HOST'] . $_SERVER['REQUEST_URI']);
+	}
+	return $url;
+}
+
 ?>