Index: functions.php =================================================================== --- functions.php (revision 8088) +++ functions.php (working copy) @@ -1,5 +1,27 @@ 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 unknown + */ function size_format( $bytes, $decimals = null ) { - // technically the correct unit names for powers of 1024 are KiB, MiB etc - // see http://en.wikipedia.org/wiki/Byte $quant = array( // ========================= Origin ==== 'TB' => 1099511627776, // pow( 1024, 4) @@ -144,7 +206,14 @@ 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 ) ) @@ -152,7 +221,17 @@ 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 ) ) @@ -179,7 +258,14 @@ 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 ) ) @@ -190,10 +276,20 @@ return false; } - /* Options functions */ -// expects $setting to already be SQL-escaped +/** + * Retrieve option value based on setting name. + * + * {@internal Missing Long Description}} + * + * @since 1.5.0 + * @package WordPress + * @subpackage Option + * + * @param string $setting Name of option to retrieve. Should already be SQL-escaped + * @return mixed Value set for the option. + */ function get_option( $setting ) { global $wpdb; @@ -243,13 +339,33 @@ return apply_filters( 'option_' . $setting, maybe_unserialize( $value ) ); } - +/** + * Protect WordPress special option from being modified. + * + * Will die if $option is in protected list. + * + * @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 ) ); } @@ -536,9 +652,19 @@ } } -// perform a HTTP HEAD or GET request -// if $file_path is a writable filename, this will do a GET request and write the file to that path -// returns a list of HTTP headers +/** + * Perform a HTTP HEAD or GET request. + * + * If $file_path is a writable filename, this will do a GET request and write + * the file to that path. + * + * @since unknown + * + * @param string $url + * @param string|bool $file_path Optional. File path to write request to. + * @param int $red Optional. Number of Redirects. Stops at 5 redirects. + * @return bool|string False on failure and string of headers if HEAD request. + */ function wp_get_http( $url, $file_path = false, $red = 1 ) { global $wp_version; @set_time_limit( 60 ); @@ -610,11 +736,30 @@ return $headers; } +/** + * Retrieve HTTP Headers from URL. + * + * @since 1.5.1 + * + * @param string $url + * @param int $red Optional. Number of redirects. + * @return bool|string False on failure, headers on success. + */ function wp_get_http_headers( $url, $red = 1 ) { return wp_get_http( $url, false, $red ); } - +/** + * Whether today is a new day. + * + * {@internal Need to find out how this function is used.}} + * + * @since 0.71 + * @uses $day Today + * @uses $previousday Previous day + * + * @return int 1 when new day, 0 if not a new day. + */ function is_new_day() { global $day, $previousday; if ( $day != $previousday ) @@ -628,17 +773,22 @@ return _http_build_query( $data, NULL, '&', '', false ); } - -/* -add_query_arg: Returns a modified querystring by 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. - -Parameters: -add_query_arg(newkey, newvalue, oldquery_or_uri) or -add_query_arg(associative_array, oldquery_or_uri) -*/ +/** + * Retrieve a modified query string. + * + * {@internal Missing Long Description}} + * + * 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 + * + * @param mixed $param1 Either newkey or an associative_array + * @param mixed $param2 Either newvalue or oldquery or uri + * @param mixed $param3 Optional. Old query or uri + * @return unknown + */ function add_query_arg() { $ret = ''; if ( is_array( func_get_arg(0) ) ) { @@ -704,27 +854,32 @@ return $ret; } - -/* -remove_query_arg: Returns a modified querystring by removing -a single key or an array of keys. -Omitting oldquery_or_uri uses the $_SERVER value. - -Parameters: -remove_query_arg(removekey, [oldquery_or_uri]) or -remove_query_arg(removekeyarray, [oldquery_or_uri]) -*/ - -function remove_query_arg( $key, $query=FALSE ) { +/** + * Removes an item or list from the query string. + * + * @since 1.5.0 + * + * @param string|array $key Query key or keys to remove. + * @param bool $query When false uses the $_SERVER value. + * @return unknown + */ +function remove_query_arg( $key, $query=false ) { if ( is_array( $key ) ) { // removing multiple keys foreach ( (array) $key as $k ) - $query = add_query_arg( $k, FALSE, $query ); + $query = add_query_arg( $k, false, $query ); return $query; } - return add_query_arg( $key, FALSE, $query ); + return add_query_arg( $key, false, $query ); } - +/** + * Walks the array while sanitizing the contents. + * + * @uses $wpdb Used to sanitize values + * + * @param array $array Array to used to walk while sanitizing contents. + * @return array Sanitized $array. + */ function add_magic_quotes( $array ) { global $wpdb; @@ -782,7 +937,14 @@ $wp_the_query = $wp_query; } - +/** + * Retrieve the description for the HTTP status. + * + * @since 2.3.0 + * + * @param int $code HTTP status code. + * @return string Empty string if not found, or description if found. + */ function get_status_header_desc( $code ) { global $wp_header_to_desc; @@ -862,7 +1024,14 @@ return @header( $status_header ); } - +/** + * Sets the headers to prevent caching for the different browsers. + * + * Different browsers support different nocache headers, so several headers must + * be sent so that all of them get the point that no caching should occur. + * + * @since 2.0.0 + */ function nocache_headers() { // why are these @-silenced when other header calls aren't? @header( 'Expires: Wed, 11 Jan 1984 05:00:00 GMT' ); @@ -871,7 +1040,11 @@ @header( 'Pragma: no-cache' ); } - +/** + * Set the headers for caching for 10 days with JavaScript content type. + * + * @since 2.1.0 + */ function cache_javascript_headers() { $expiresOffset = 864000; // 10 days header( "Content-Type: text/javascript; charset=" . get_bloginfo( 'charset' ) ); @@ -879,13 +1052,26 @@ header( "Expires: " . gmdate( "D, d M Y H:i:s", time() + $expiresOffset ) . " GMT" ); } - +/** + * Retrieve the number of database queries during the WordPress execution. + * + * @since 2.0.0 + * + * @return int Number of database queries + */ function get_num_queries() { global $wpdb; return $wpdb->num_queries; } - +/** + * Whether input is yes or no. Must be 'y' to be true. + * + * @since 1.0.0 + * + * @param string $yn Character string containing either 'y' or 'n' + * @return bool True if yes, false on anything else + */ function bool_from_yn( $yn ) { return ( strtolower( $yn ) == 'y' ); } @@ -911,17 +1097,31 @@ do_action( $hook, $wp_query->is_comment_feed ); } - +/** + * Load the RDF RSS 0.91 Feed template. + * + * @since 2.1.0 + */ function do_feed_rdf() { load_template( ABSPATH . WPINC . '/feed-rdf.php' ); } - +/** + * Load the RSS 1.0 Feed Template + * + * @since 2.1.0 + */ function do_feed_rss() { load_template( ABSPATH . WPINC . '/feed-rss.php' ); } - +/** + * Load either the RSS2 comment feed or the RSS2 posts feed. + * + * @since 2.1.0 + * + * @param bool $for_comments True for the comment feed, false for normal feed. + */ function do_feed_rss2( $for_comments ) { if ( $for_comments ) load_template( ABSPATH . WPINC . '/feed-rss2-comments.php' ); @@ -929,7 +1129,13 @@ load_template( ABSPATH . WPINC . '/feed-rss2.php' ); } - +/** + * Load either Atom comment feed or Atom posts feed. + * + * @since 2.1.0 + * + * @param bool $for_comments True for the comment feed, false for normal feed. + */ function do_feed_atom( $for_comments ) { if ($for_comments) load_template( ABSPATH . WPINC . '/feed-atom-comments.php'); @@ -937,6 +1143,15 @@ load_template( ABSPATH . WPINC . '/feed-atom.php' ); } +/** + * Display the robot.txt file content. + * + * The echo content should be with usage of the permalinks or for creating the + * robot.txt file. + * + * @since 2.1.0 + * @uses do_action() Calls 'do_robotstxt' hook for displaying robot.txt rules. + */ function do_robots() { header( 'Content-Type: text/plain; charset=utf-8' ); @@ -1511,7 +1726,18 @@ } } - +/** + * Merge user defined arguments into defaults array. + * + * This function is used throughout WordPress to allow for both string or array + * to be merged into another array. + * + * @since 2.2.0 + * + * @param string|array $args Value to merge with $defaults + * @param array $defaults Array that serves as the defaults. + * @return array Merged user defined values with defaults. + */ function wp_parse_args( $args, $defaults = '' ) { if ( is_object( $args ) ) $r = get_object_vars( $args ); @@ -1525,7 +1751,15 @@ return $r; } - +/** + * Determines if Widgets library should be loaded. + * + * Checks to make sure that the widgets library hasn't already been loaded. If + * it hasn't, then it will load the widgets library and run an action hook. + * + * @since 2.2.0 + * @uses add_action() Calls '_admin_menu' hook with 'wp_widgets_add_menu' value. + */ function wp_maybe_load_widgets() { if ( !function_exists( 'dynamic_sidebar' ) ) { require_once( ABSPATH . WPINC . '/widgets.php' ); @@ -1533,28 +1767,39 @@ } } - +/** + * Append the Widgets menu to the themes main menu. + * + * @since 2.2.0 + * @uses $submenu The administration submenu list. + */ function wp_widgets_add_menu() { global $submenu; $submenu['themes.php'][7] = array( __( 'Widgets' ), 'switch_themes', 'widgets.php' ); ksort( $submenu['themes.php'], SORT_NUMERIC ); } - -// For PHP 5.2, make sure all output buffers are flushed -// before our singletons our destroyed. +/** + * Flush all output buffers for PHP 5.2. + * + * Make sure all output buffers are flushed before our singletons our destroyed. + * + * @since 2.2.0 + */ function wp_ob_end_flush_all() { while ( @ob_end_flush() ); } -/* - * require_wp_db() - require_once the correct database class file. +/** + * Load the correct database class file. * - * This function is used to load the database class file either at runtime or by wp-admin/setup-config.php - * We must globalise $wpdb to ensure that it is defined globally by the inline code in wp-db.php + * This function is used to load the database class file either at runtime or by + * wp-admin/setup-config.php We must globalise $wpdb to ensure that it is + * defined globally by the inline code in wp-db.php. * - * @global $wpdb + * @since 2.5 + * @global $wpdb WordPress Database Object */ function require_wp_db() { global $wpdb; @@ -1564,6 +1809,21 @@ require_once( ABSPATH . WPINC . '/wp-db.php' ); } + +/** + * Load custom DB error or display WordPress DB error. + * + * If a file exists in the wp-content directory named db-error.php, then it will + * be loaded instead of displaying the WordPress DB error. If it is not found, + * then the WordPress DB error will be displayed instead. + * + * The WordPress DB error sets the HTTP status header to 500 to try to prevent + * search engines from caching the message. Custom DB messages should do the + * same. + * + * @since 2.5 + * @uses $wpdb + */ function dead_db() { global $wpdb; @@ -1597,8 +1857,12 @@ die(); } + /** - * Converts input to an absolute integer + * Converts value to positive integer. + * + * @since 2.5 + * * @param mixed $maybeint data you wish to have convered to an absolute integer * @return int an absolute integer */ @@ -1606,9 +1870,16 @@ return abs( intval( $maybeint ) ); } + /** - * Determines if the blog can be accessed over SSL - * @return bool whether of not SSL access is available + * Determines if the blog can be accessed over SSL. + * + * Determines if blog can be accessed over SSL by using cURL to access the site + * using the https in the siteurl. Requires cURL extension to work correctly. + * + * @since 2.5 + * + * @return bool Whether or not SSL access is available */ function url_is_accessable_via_ssl($url) { @@ -1633,21 +1904,33 @@ return false; } + +/** + * Secure URL, if available or the given URL. + * + * @since 2.5 + * + * @param string $url Complete URL path with transport. + * @return string Secure or regular URL path. + */ function atom_service_url_filter($url) { if ( url_is_accessable_via_ssl($url) ) - return preg_replace( '/^http:\/\//', 'https://', $url ); + return preg_replace( '/^http:\/\//', 'https://', $url ); else return $url; } + /** - * _deprecated_function() - Marks a function as deprecated and informs when it has been used. + * Marks a function as deprecated and informs when it has been used. * - * There is a hook deprecated_function_run that will be called that can be used to get the backtrace - * up to what file and function called the deprecated function. + * There is a hook deprecated_function_run that will be called that can be used + * to get the backtrace up to what file and function called the deprecated + * function. * - * The current behavior is to trigger an user error if WP_DEBUG is defined and is true. + * The current behavior is to trigger an user error if WP_DEBUG is defined and + * is true. * * This function is to be used in every function in depreceated.php * @@ -1676,13 +1959,16 @@ } } + /** - * _deprecated_file() - Marks a file as deprecated and informs when it has been used. + * Marks a file as deprecated and informs when it has been used. * - * There is a hook deprecated_file_included that will be called that can be used to get the backtrace - * up to what file and function included the deprecated file. + * There is a hook deprecated_file_included that will be called that can be used + * to get the backtrace up to what file and function included the deprecated + * file. * - * The current behavior is to trigger an user error if WP_DEBUG is defined and is true. + * The current behavior is to trigger an user error if WP_DEBUG is defined and + * is true. * * This function is to be used in every file that is depreceated * @@ -1711,9 +1997,12 @@ } } + /** - * is_lighttpd_before_150() - Is the server running earlier than 1.5.0 version of lighttpd + * Is the server running earlier than 1.5.0 version of lighttpd * + * @since unknown + * * @return bool Whether the server is running lighttpd < 1.5.0 */ function is_lighttpd_before_150() { @@ -1722,9 +2011,12 @@ return 'lighttpd' == $server_parts[0] && -1 == version_compare( $server_parts[1], '1.5.0' ); } + /** - * apache_mod_loaded() - Does the specified module exist in the apache config? + * Does the specified module exist in the apache config? * + * @since unknown + * * @param string $mod e.g. mod_rewrite * @param bool $default The default return value if the module is not found * @return bool @@ -1749,6 +2041,21 @@ return $default; } + +/** + * File validates against allowed set of defined rules. + * + * A return value of '1' means that the $file contains either '..' or './'. A + * return value of '2' means that the $file contains ':' after the first + * character. A return value of '3' means that the file is not in the allowed + * files list. + * + * @since 2.6 + * + * @param string $file File path. + * @param array $allowed_files List of allowed files. + * @return int 0 means nothing is wrong, greater than 0 means something was wrong. + */ function validate_file( $file, $allowed_files = '' ) { if ( false !== strpos( $file, '..' )) return 1; @@ -1765,10 +2072,27 @@ return 0; } + +/** + * Determine if SSL is used. + * + * @since 2.6 + * + * @return bool True if SSL, false if not used. + */ function is_ssl() { return ( 'on' == strtolower($_SERVER['HTTPS']) ) ? true : false; } + +/** + * Whether SSL login should be forced. + * + * @since 2.6 + * + * @param string|bool $force Optional. + * @return bool True if forced, false if not forced. + */ function force_ssl_login($force = '') { static $forced; @@ -1781,6 +2105,15 @@ return $forced; } + +/** + * Whether to force SSL used for the Administration Panels. + * + * @since 2.6 + * + * @param string|bool $force + * @return bool True if forced, false if not forced. + */ function force_ssl_admin($force = '') { static $forced; @@ -1793,4 +2126,4 @@ return $forced; } -?> +?> \ No newline at end of file