Make WordPress Core


Ignore:
Timestamp:
06/16/2008 09:08:49 PM (16 years ago)
Author:
mdawaffe
Message:

crazyhorse: merge with trunk [8072:8102]

File:
1 edited

Legend:

Unmodified
Added
Removed
  • branches/crazyhorse/wp-includes/functions.php

    r8069 r8103  
    11<?php
    2 
     2/**
     3 * Main WordPress API
     4 *
     5 * @package WordPress
     6 */
     7
     8/**
     9 * Converts MySQL DATETIME field to user specified date format.
     10 *
     11 * If $dateformatstring has 'G' value, then gmmktime() function will be used to
     12 * make the time. If $dateformatstring is set to 'U', then mktime() function
     13 * will be used to make the time.
     14 *
     15 * The $translate will only be used, if it is set to true and it is by default
     16 * and if the $wp_locale object has the month and weekday set.
     17 *
     18 * @since 0.71
     19 *
     20 * @param string $dateformatstring Either 'G', 'U', or php date format.
     21 * @param string $mysqlstring Time from mysql DATETIME field.
     22 * @param bool $translate Optional. Default is true. Will switch format to locale.
     23 * @return string Date formated by $dateformatstring or locale (if available).
     24 */
    325function mysql2date( $dateformatstring, $mysqlstring, $translate = true ) {
    426    global $wp_locale;
     
    5274}
    5375
    54 
     76/**
     77 * Retrieve the current time based on specified type.
     78 *
     79 * The 'mysql' type will return the time in the format for MySQL DATETIME field.
     80 * The 'timestamp' type will return the current timestamp.
     81 *
     82 * If the $gmt is set to either '1' or 'true', then both types will use the
     83 * GMT offset in the WordPress option to add the GMT offset to the time.
     84 *
     85 * @since 1.0.0
     86 *
     87 * @param string $type Either 'mysql' or 'timestamp'.
     88 * @param int|bool $gmt Optional. Whether to use $gmt offset. Default is false.
     89 * @return unknown
     90 */
    5591function current_time( $type, $gmt = 0 ) {
    5692    switch ( $type ) {
     
    89125}
    90126
    91 
     127/**
     128 * Convert number to format based on the locale.
     129 *
     130 * @since 2.3.0
     131 *
     132 * @param mixed $number The number to convert based on locale.
     133 * @param int $decimals Precision of the number of decimal places.
     134 * @return string Converted number in string format.
     135 */
    92136function number_format_i18n( $number, $decimals = null ) {
    93137    global $wp_locale;
     
    98142}
    99143
    100 
     144/**
     145 * Convert number of bytes largest unit bytes will fit into.
     146 *
     147 * It is easier to read 1kB than 1024 bytes and 1MB than 1048576 bytes. Converts
     148 * number of bytes to human readable number by taking the number of that unit
     149 * that the bytes will go into it. Supports TB value.
     150 *
     151 * Please note that integers in PHP are limited to 32 bits, unless they are on
     152 * 64 bit architecture, then they have 64 bit size. If you need to place the
     153 * larger size then what PHP integer type will hold, then use a string. It will
     154 * be converted to a double, which should always have 64 bit length.
     155 *
     156 * Technically the correct unit names for powers of 1024 are KiB, MiB etc.
     157 * @link http://en.wikipedia.org/wiki/Byte
     158 *
     159 * @since 2.3.0
     160 *
     161 * @param int|string $bytes Number of bytes. Note max integer size for integers.
     162 * @param int $decimals Precision of number of decimal places.
     163 * @return unknown
     164 */
    101165function size_format( $bytes, $decimals = null ) {
    102     // technically the correct unit names for powers of 1024 are KiB, MiB etc
    103     // see http://en.wikipedia.org/wiki/Byte
    104166    $quant = array(
    105167        // ========================= Origin ====
     
    145207}
    146208
    147 
     209/**
     210 * Unserialize value only if it was serialized.
     211 *
     212 * @since 2.0.0
     213 *
     214 * @param string $original Maybe unserialized original, if is needed.
     215 * @return mixed Unserialized data can be any type.
     216 */
    148217function maybe_unserialize( $original ) {
    149218    if ( is_serialized( $original ) ) // don't attempt to unserialize data that wasn't serialized going in
     
    153222}
    154223
    155 
     224/**
     225 * Check value to find if it was serialized.
     226 *
     227 * If $data is not an string, then returned value will always be false.
     228 * Serialized data is always a string.
     229 *
     230 * @since 2.0.5
     231 *
     232 * @param mixed $data Value to check to see if was serialized.
     233 * @return bool False if not serialized and true if it was.
     234 */
    156235function is_serialized( $data ) {
    157236    // if it isn't a string, it isn't serialized
     
    180259}
    181260
    182 
     261/**
     262 * Check whether serialized data is of string type.
     263 *
     264 * @since 2.0.5
     265 *
     266 * @param mixed $data Serialized data
     267 * @return bool False if not a serialized string, true if it is.
     268 */
    183269function is_serialized_string( $data ) {
    184270    // if it isn't a string, it isn't a serialized string
     
    191277}
    192278
    193 
    194279/* Options functions */
    195280
    196 // expects $setting to already be SQL-escaped
     281/**
     282 * Retrieve option value based on setting name.
     283 *
     284 * {@internal Missing Long Description}}
     285 *
     286 * @since 1.5.0
     287 * @package WordPress
     288 * @subpackage Option
     289 *
     290 * @param string $setting Name of option to retrieve. Should already be SQL-escaped
     291 * @return mixed Value set for the option.
     292 */
    197293function get_option( $setting ) {
    198294    global $wpdb;
     
    244340}
    245341
    246 
     342/**
     343 * Protect WordPress special option from being modified.
     344 *
     345 * Will die if $option is in protected list.
     346 *
     347 * @since 2.2.0
     348 * @package WordPress
     349 * @subpackage Option
     350 *
     351 * @param string $option Option name.
     352 */
    247353function wp_protect_special_option( $option ) {
    248354    $protected = array( 'alloptions', 'notoptions' );
     
    251357}
    252358
     359/**
     360 * Print option value after sanitizing for forms.
     361 *
     362 * @uses attribute_escape Sanitizes value.
     363 * @since 1.5.0
     364 * @package WordPress
     365 * @subpackage Option
     366 *
     367 * @param string $option Option name.
     368 */
    253369function form_option( $option ) {
    254370    echo attribute_escape (get_option( $option ) );
     
    405521function maybe_serialize( $data ) {
    406522    if ( is_string( $data ) )
    407         $data = trim( $data );
     523        return $data;
    408524    elseif ( is_array( $data ) || is_object( $data ) )
    409525        return serialize( $data );
     
    537653}
    538654
    539 // perform a HTTP HEAD or GET request
    540 // if $file_path is a writable filename, this will do a GET request and write the file to that path
    541 // returns a list of HTTP headers
     655/**
     656 * Perform a HTTP HEAD or GET request.
     657 *
     658 * If $file_path is a writable filename, this will do a GET request and write
     659 * the file to that path.
     660 *
     661 * @since unknown
     662 *
     663 * @param string $url
     664 * @param string|bool $file_path Optional. File path to write request to.
     665 * @param int $red Optional. Number of Redirects. Stops at 5 redirects.
     666 * @return bool|string False on failure and string of headers if HEAD request.
     667 */
    542668function wp_get_http( $url, $file_path = false, $red = 1 ) {
    543669    global $wp_version;
     
    611737}
    612738
     739/**
     740 * Retrieve HTTP Headers from URL.
     741 *
     742 * @since 1.5.1
     743 *
     744 * @param string $url
     745 * @param int $red Optional. Number of redirects.
     746 * @return bool|string False on failure, headers on success.
     747 */
    613748function wp_get_http_headers( $url, $red = 1 ) {
    614749    return wp_get_http( $url, false, $red );
    615750}
    616751
    617 
     752/**
     753 * Whether today is a new day.
     754 *
     755 * {@internal Need to find out how this function is used.}}
     756 *
     757 * @since 0.71
     758 * @uses $day Today
     759 * @uses $previousday Previous day
     760 *
     761 * @return int 1 when new day, 0 if not a new day.
     762 */
    618763function is_new_day() {
    619764    global $day, $previousday;
     
    629774}
    630775
    631 
    632 /*
    633 add_query_arg: Returns a modified querystring by adding
    634 a single key & value or an associative array.
    635 Setting a key value to emptystring removes the key.
    636 Omitting oldquery_or_uri uses the $_SERVER value.
    637 
    638 Parameters:
    639 add_query_arg(newkey, newvalue, oldquery_or_uri) or
    640 add_query_arg(associative_array, oldquery_or_uri)
    641 */
     776/**
     777 * Retrieve a modified query string.
     778 *
     779 * {@internal Missing Long Description}}
     780 *
     781 * Adding a single key & value or an associative array.
     782 * Setting a key value to emptystring removes the key.
     783 * Omitting oldquery_or_uri uses the $_SERVER value.
     784 *
     785 * @since 1.5.0
     786 *
     787 * @param mixed $param1 Either newkey or an associative_array
     788 * @param mixed $param2 Either newvalue or oldquery or uri
     789 * @param mixed $param3 Optional. Old query or uri
     790 * @return unknown
     791 */
    642792function add_query_arg() {
    643793    $ret = '';
     
    705855}
    706856
    707 
    708 /*
    709 remove_query_arg: Returns a modified querystring by removing
    710 a single key or an array of keys.
    711 Omitting oldquery_or_uri uses the $_SERVER value.
    712 
    713 Parameters:
    714 remove_query_arg(removekey, [oldquery_or_uri]) or
    715 remove_query_arg(removekeyarray, [oldquery_or_uri])
    716 */
    717 
    718 function remove_query_arg( $key, $query=FALSE ) {
     857/**
     858 * Removes an item or list from the query string.
     859 *
     860 * @since 1.5.0
     861 *
     862 * @param string|array $key Query key or keys to remove.
     863 * @param bool $query When false uses the $_SERVER value.
     864 * @return unknown
     865 */
     866function remove_query_arg( $key, $query=false ) {
    719867    if ( is_array( $key ) ) { // removing multiple keys
    720868        foreach ( (array) $key as $k )
    721             $query = add_query_arg( $k, FALSE, $query );
     869            $query = add_query_arg( $k, false, $query );
    722870        return $query;
    723871    }
    724     return add_query_arg( $key, FALSE, $query );
    725 }
    726 
    727 
     872    return add_query_arg( $key, false, $query );
     873}
     874
     875/**
     876 * Walks the array while sanitizing the contents.
     877 *
     878 * @uses $wpdb Used to sanitize values
     879 *
     880 * @param array $array Array to used to walk while sanitizing contents.
     881 * @return array Sanitized $array.
     882 */
    728883function add_magic_quotes( $array ) {
    729884    global $wpdb;
     
    783938}
    784939
    785 
     940/**
     941 * Retrieve the description for the HTTP status.
     942 *
     943 * @since 2.3.0
     944 *
     945 * @param int $code HTTP status code.
     946 * @return string Empty string if not found, or description if found.
     947 */
    786948function get_status_header_desc( $code ) {
    787949    global $wp_header_to_desc;
     
    8631025}
    8641026
    865 
     1027/**
     1028 * Sets the headers to prevent caching for the different browsers.
     1029 *
     1030 * Different browsers support different nocache headers, so several headers must
     1031 * be sent so that all of them get the point that no caching should occur.
     1032 *
     1033 * @since 2.0.0
     1034 */
    8661035function nocache_headers() {
    8671036    // why are these @-silenced when other header calls aren't?
     
    8721041}
    8731042
    874 
     1043/**
     1044 * Set the headers for caching for 10 days with JavaScript content type.
     1045 *
     1046 * @since 2.1.0
     1047 */
    8751048function cache_javascript_headers() {
    8761049    $expiresOffset = 864000; // 10 days
     
    8801053}
    8811054
    882 
     1055/**
     1056 * Retrieve the number of database queries during the WordPress execution.
     1057 *
     1058 * @since 2.0.0
     1059 *
     1060 * @return int Number of database queries
     1061 */
    8831062function get_num_queries() {
    8841063    global $wpdb;
     
    8861065}
    8871066
    888 
     1067/**
     1068 * Whether input is yes or no. Must be 'y' to be true.
     1069 *
     1070 * @since 1.0.0
     1071 *
     1072 * @param string $yn Character string containing either 'y' or 'n'
     1073 * @return bool True if yes, false on anything else
     1074 */
    8891075function bool_from_yn( $yn ) {
    8901076    return ( strtolower( $yn ) == 'y' );
     
    9121098}
    9131099
    914 
     1100/**
     1101 * Load the RDF RSS 0.91 Feed template.
     1102 *
     1103 * @since 2.1.0
     1104 */
    9151105function do_feed_rdf() {
    9161106    load_template( ABSPATH . WPINC . '/feed-rdf.php' );
    9171107}
    9181108
    919 
     1109/**
     1110 * Load the RSS 1.0 Feed Template
     1111 *
     1112 * @since 2.1.0
     1113 */
    9201114function do_feed_rss() {
    9211115    load_template( ABSPATH . WPINC . '/feed-rss.php' );
    9221116}
    9231117
    924 
     1118/**
     1119 * Load either the RSS2 comment feed or the RSS2 posts feed.
     1120 *
     1121 * @since 2.1.0
     1122 *
     1123 * @param bool $for_comments True for the comment feed, false for normal feed.
     1124 */
    9251125function do_feed_rss2( $for_comments ) {
    9261126    if ( $for_comments )
     
    9301130}
    9311131
    932 
     1132/**
     1133 * Load either Atom comment feed or Atom posts feed.
     1134 *
     1135 * @since 2.1.0
     1136 *
     1137 * @param bool $for_comments True for the comment feed, false for normal feed.
     1138 */
    9331139function do_feed_atom( $for_comments ) {
    9341140    if ($for_comments)
     
    9381144}
    9391145
     1146/**
     1147 * Display the robot.txt file content.
     1148 *
     1149 * The echo content should be with usage of the permalinks or for creating the
     1150 * robot.txt file.
     1151 *
     1152 * @since 2.1.0
     1153 * @uses do_action() Calls 'do_robotstxt' hook for displaying robot.txt rules.
     1154 */
    9401155function do_robots() {
    9411156    header( 'Content-Type: text/plain; charset=utf-8' );
     
    15121727}
    15131728
    1514 
     1729/**
     1730 * Merge user defined arguments into defaults array.
     1731 *
     1732 * This function is used throughout WordPress to allow for both string or array
     1733 * to be merged into another array.
     1734 *
     1735 * @since 2.2.0
     1736 *
     1737 * @param string|array $args Value to merge with $defaults
     1738 * @param array $defaults Array that serves as the defaults.
     1739 * @return array Merged user defined values with defaults.
     1740 */
    15151741function wp_parse_args( $args, $defaults = '' ) {
    15161742    if ( is_object( $args ) )
     
    15261752}
    15271753
    1528 
     1754/**
     1755 * Determines if Widgets library should be loaded.
     1756 *
     1757 * Checks to make sure that the widgets library hasn't already been loaded. If
     1758 * it hasn't, then it will load the widgets library and run an action hook.
     1759 *
     1760 * @since 2.2.0
     1761 * @uses add_action() Calls '_admin_menu' hook with 'wp_widgets_add_menu' value.
     1762 */
    15291763function wp_maybe_load_widgets() {
    15301764    if ( !function_exists( 'dynamic_sidebar' ) ) {
     
    15341768}
    15351769
    1536 
     1770/**
     1771 * Append the Widgets menu to the themes main menu.
     1772 *
     1773 * @since 2.2.0
     1774 * @uses $submenu The administration submenu list.
     1775 */
    15371776function wp_widgets_add_menu() {
    15381777    global $submenu;
     
    15411780}
    15421781
    1543 
    1544 // For PHP 5.2, make sure all output buffers are flushed
    1545 // before our singletons our destroyed.
     1782/**
     1783 * Flush all output buffers for PHP 5.2.
     1784 *
     1785 * Make sure all output buffers are flushed before our singletons our destroyed.
     1786 *
     1787 * @since 2.2.0
     1788 */
    15461789function wp_ob_end_flush_all() {
    15471790    while ( @ob_end_flush() );
     
    15491792
    15501793
    1551 /*
    1552  * require_wp_db() - require_once the correct database class file.
    1553  *
    1554  * This function is used to load the database class file either at runtime or by wp-admin/setup-config.php
    1555  * We must globalise $wpdb to ensure that it is defined globally by the inline code in wp-db.php
    1556  *
    1557  * @global $wpdb
     1794/**
     1795 * Load the correct database class file.
     1796 *
     1797 * This function is used to load the database class file either at runtime or by
     1798 * wp-admin/setup-config.php We must globalise $wpdb to ensure that it is
     1799 * defined globally by the inline code in wp-db.php.
     1800 *
     1801 * @since 2.5
     1802 * @global $wpdb WordPress Database Object
    15581803 */
    15591804function require_wp_db() {
     
    15651810}
    15661811
     1812
     1813/**
     1814 * Load custom DB error or display WordPress DB error.
     1815 *
     1816 * If a file exists in the wp-content directory named db-error.php, then it will
     1817 * be loaded instead of displaying the WordPress DB error. If it is not found,
     1818 * then the WordPress DB error will be displayed instead.
     1819 *
     1820 * The WordPress DB error sets the HTTP status header to 500 to try to prevent
     1821 * search engines from caching the message. Custom DB messages should do the
     1822 * same.
     1823 *
     1824 * @since 2.5
     1825 * @uses $wpdb
     1826 */
    15671827function dead_db() {
    15681828    global $wpdb;
     
    15981858}
    15991859
    1600 /**
    1601  * Converts input to an absolute integer
     1860
     1861/**
     1862 * Converts value to positive integer.
     1863 *
     1864 * @since 2.5
     1865 *
    16021866 * @param mixed $maybeint data you wish to have convered to an absolute integer
    16031867 * @return int an absolute integer
     
    16071871}
    16081872
    1609 /**
    1610  * Determines if the blog can be accessed over SSL
    1611  * @return bool whether of not SSL access is available
     1873
     1874/**
     1875 * Determines if the blog can be accessed over SSL.
     1876 *
     1877 * Determines if blog can be accessed over SSL by using cURL to access the site
     1878 * using the https in the siteurl. Requires cURL extension to work correctly.
     1879 *
     1880 * @since 2.5
     1881 *
     1882 * @return bool Whether or not SSL access is available
    16121883 */
    16131884function url_is_accessable_via_ssl($url)
     
    16341905}
    16351906
     1907
     1908/**
     1909 * Secure URL, if available or the given URL.
     1910 *
     1911 * @since 2.5
     1912 *
     1913 * @param string $url Complete URL path with transport.
     1914 * @return string Secure or regular URL path.
     1915 */
    16361916function atom_service_url_filter($url)
    16371917{
    16381918    if ( url_is_accessable_via_ssl($url) )
    1639         return  preg_replace( '/^http:\/\//', 'https://',  $url );
     1919        return preg_replace( '/^http:\/\//', 'https://',  $url );
    16401920    else
    16411921        return $url;
    16421922}
    16431923
    1644 /**
    1645  * _deprecated_function() - Marks a function as deprecated and informs when it has been used.
    1646  *
    1647  * There is a hook deprecated_function_run that will be called that can be used to get the backtrace
    1648  * up to what file and function called the deprecated function.
    1649  *
    1650  * The current behavior is to trigger an user error if WP_DEBUG is defined and is true.
     1924
     1925/**
     1926 * Marks a function as deprecated and informs when it has been used.
     1927 *
     1928 * There is a hook deprecated_function_run that will be called that can be used
     1929 * to get the backtrace up to what file and function called the deprecated
     1930 * function.
     1931 *
     1932 * The current behavior is to trigger an user error if WP_DEBUG is defined and
     1933 * is true.
    16511934 *
    16521935 * This function is to be used in every function in depreceated.php
     
    16771960}
    16781961
    1679 /**
    1680  * _deprecated_file() - Marks a file as deprecated and informs when it has been used.
    1681  *
    1682  * There is a hook deprecated_file_included that will be called that can be used to get the backtrace
    1683  * up to what file and function included the deprecated file.
    1684  *
    1685  * The current behavior is to trigger an user error if WP_DEBUG is defined and is true.
     1962
     1963/**
     1964 * Marks a file as deprecated and informs when it has been used.
     1965 *
     1966 * There is a hook deprecated_file_included that will be called that can be used
     1967 * to get the backtrace up to what file and function included the deprecated
     1968 * file.
     1969 *
     1970 * The current behavior is to trigger an user error if WP_DEBUG is defined and
     1971 * is true.
    16861972 *
    16871973 * This function is to be used in every file that is depreceated
     
    17121998}
    17131999
    1714 /**
    1715  * is_lighttpd_before_150() - Is the server running earlier than 1.5.0 version of lighttpd
     2000
     2001/**
     2002 * Is the server running earlier than 1.5.0 version of lighttpd
     2003 *
     2004 * @since unknown
    17162005 *
    17172006 * @return bool Whether the server is running lighttpd < 1.5.0
     
    17232012}
    17242013
    1725 /**
    1726  * apache_mod_loaded() - Does the specified module exist in the apache config?
     2014
     2015/**
     2016 * Does the specified module exist in the apache config?
     2017 *
     2018 * @since unknown
    17272019 *
    17282020 * @param string $mod e.g. mod_rewrite
     
    17502042}
    17512043
     2044
     2045/**
     2046 * File validates against allowed set of defined rules.
     2047 *
     2048 * A return value of '1' means that the $file contains either '..' or './'. A
     2049 * return value of '2' means that the $file contains ':' after the first
     2050 * character. A return value of '3' means that the file is not in the allowed
     2051 * files list.
     2052 *
     2053 * @since 2.6
     2054 *
     2055 * @param string $file File path.
     2056 * @param array $allowed_files List of allowed files.
     2057 * @return int 0 means nothing is wrong, greater than 0 means something was wrong.
     2058 */
    17522059function validate_file( $file, $allowed_files = '' ) {
    17532060    if ( false !== strpos( $file, '..' ))
     
    17662073}
    17672074
     2075
     2076/**
     2077 * Determine if SSL is used.
     2078 *
     2079 * @since 2.6
     2080 *
     2081 * @return bool True if SSL, false if not used.
     2082 */
    17682083function is_ssl() {
    17692084    return ( 'on' == strtolower($_SERVER['HTTPS']) ) ? true : false;
    17702085}
    17712086
     2087
     2088/**
     2089 * Whether SSL login should be forced.
     2090 *
     2091 * @since 2.6
     2092 *
     2093 * @param string|bool $force Optional.
     2094 * @return bool True if forced, false if not forced.
     2095 */
    17722096function force_ssl_login($force = '') {
    17732097    static $forced;
    17742098
    17752099    if ( '' != $force ) {
    1776         $old_forcded = $forced;
     2100        $old_forced = $forced;
    17772101        $forced = $force;
    17782102        return $old_forced;
     
    17822106}
    17832107
     2108
     2109/**
     2110 * Whether to force SSL used for the Administration Panels.
     2111 *
     2112 * @since 2.6
     2113 *
     2114 * @param string|bool $force
     2115 * @return bool True if forced, false if not forced.
     2116 */
    17842117function force_ssl_admin($force = '') {
    17852118    static $forced;
    17862119
    17872120    if ( '' != $force ) {
    1788         $old_forcded = $forced;
     2121        $old_forced = $forced;
    17892122        $forced = $force;
    17902123        return $old_forced;
Note: See TracChangeset for help on using the changeset viewer.