WordPress.org

Make WordPress Core

Changeset 8598


Ignore:
Timestamp:
08/09/08 04:51:51 (6 years ago)
Author:
ryan
Message:

phpdoc for functions.php. Props jacobsantos. fixes #5639

File:
1 edited

Legend:

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

    r8589 r8598  
    119119    if ( -1 == $i ) 
    120120        $i = false; 
    121      
     121 
    122122    if ( ( !empty( $wp_locale->month ) ) && ( !empty( $wp_locale->weekday ) ) ) { 
    123123        $datemonth = $wp_locale->get_month( date( 'm', $i ) ); 
     
    196196} 
    197197 
    198  
     198/** 
     199 * Get the week start and end from the datetime or date string from mysql. 
     200 * 
     201 * @since 0.71 
     202 * 
     203 * @param string $mysqlstring Date or datetime field type from mysql. 
     204 * @param int $start_of_week Optional. Start of the week as an integer. 
     205 * @return array Keys are 'start' and 'end'. 
     206 */ 
    199207function get_weekstartend( $mysqlstring, $start_of_week = '' ) { 
    200     $my = substr( $mysqlstring, 0, 4 ); 
    201     $mm = substr( $mysqlstring, 8, 2 ); 
    202     $md = substr( $mysqlstring, 5, 2 ); 
    203     $day = mktime( 0, 0, 0, $md, $mm, $my ); 
    204     $weekday = date( 'w', $day ); 
    205     $i = 86400; 
     208    $my = substr( $mysqlstring, 0, 4 ); // Mysql string Year 
     209    $mm = substr( $mysqlstring, 8, 2 ); // Mysql string Month 
     210    $md = substr( $mysqlstring, 5, 2 ); // Mysql string day 
     211    $day = mktime( 0, 0, 0, $md, $mm, $my ); // The timestamp for mysqlstring day. 
     212    $weekday = date( 'w', $day ); // The day of the week from the timestamp 
     213    $i = 86400; // One day 
    206214    if( !is_numeric($start_of_week) ) 
    207215        $start_of_week = get_option( 'start_of_week' ); 
     
    416424 */ 
    417425function get_alloptions() { 
    418     global $wpdb, $wp_queries; 
     426    global $wpdb; 
    419427    $show = $wpdb->hide_errors(); 
    420428    if ( !$options = $wpdb->get_results( "SELECT option_name, option_value FROM $wpdb->options WHERE autoload = 'yes'" ) ) 
     
    640648} 
    641649 
    642  
     650/** 
     651 * Strip HTML and put links at the bottom of stripped content. 
     652 * 
     653 * Searches for all of the links, strips them out of the content, and places 
     654 * them at the bottom of the content with numbers. 
     655 * 
     656 * @since unknown 
     657 * 
     658 * @param string $content Content to get links 
     659 * @return string HTML stripped out of content with links at the bottom. 
     660 */ 
    643661function make_url_footnote( $content ) { 
    644662    preg_match_all( '/<a(.+?)href=\"(.+?)\"(.*?)>(.+?)<\/a>/', $content, $matches ); 
     
    660678} 
    661679 
    662  
     680/** 
     681 * Retrieve post title from XMLRPC XML. 
     682 * 
     683 * If the title element is not part of the XML, then the default post title from 
     684 * the $post_default_title will be used instead. 
     685 * 
     686 * @package WordPress 
     687 * @subpackage XMLRPC 
     688 * @since unknown 
     689 * 
     690 * @global string $post_default_title Default XMLRPC post title. 
     691 * 
     692 * @param string $content XMLRPC XML Request content 
     693 * @return string Post title 
     694 */ 
    663695function xmlrpc_getposttitle( $content ) { 
    664696    global $post_default_title; 
     
    673705} 
    674706 
    675  
     707/** 
     708 * Retrieve the post category or categories from XMLRPC XML. 
     709 * 
     710 * If the category element is not found, then the default post category will be 
     711 * used. The return type then would be what $post_default_category. If the 
     712 * category is found, then it will always be an array. 
     713 * 
     714 * @package WordPress 
     715 * @subpackage XMLRPC 
     716 * @since unknown 
     717 * 
     718 * @global string $post_default_category Default XMLRPC post category. 
     719 * 
     720 * @param string $content XMLRPC XML Request content 
     721 * @return string|array List of categories or category name. 
     722 */ 
    676723function xmlrpc_getpostcategory( $content ) { 
    677724    global $post_default_category; 
     
    685732} 
    686733 
    687  
     734/** 
     735 * XMLRPC XML content without title and category elements. 
     736 * 
     737 * @package WordPress 
     738 * @subpackage XMLRPC 
     739 * @since unknown 
     740 * 
     741 * @param string $content XMLRPC XML Request content 
     742 * @return string XMLRPC XML Request content without title and category elements. 
     743 */ 
    688744function xmlrpc_removepostdata( $content ) { 
    689745    $content = preg_replace( '/<title>(.+?)<\/title>/si', '', $content ); 
     
    904960 * Whether today is a new day. 
    905961 * 
    906  * {@internal Need to find out how this function is used.}} 
    907  * 
    908962 * @since 0.71 
    909963 * @uses $day Today 
     
    936990 */ 
    937991function build_query( $data ) { 
    938     return _http_build_query( $data, NULL, '&', '', false ); 
     992    return _http_build_query( $data, null, '&', '', false ); 
    939993} 
    940994 
     
    9541008 * @param mixed $param2 Either newvalue or oldquery or uri 
    9551009 * @param mixed $param3 Optional. Old query or uri 
    956  * @return unknown 
     1010 * @return string New URL query string. 
    9571011 */ 
    9581012function add_query_arg() { 
     
    10281082 * @param string|array $key Query key or keys to remove. 
    10291083 * @param bool $query When false uses the $_SERVER value. 
    1030  * @return unknown 
     1084 * @return string New URL query string. 
    10311085 */ 
    10321086function remove_query_arg( $key, $query=false ) { 
     
    11061160} 
    11071161 
    1108  
     1162/** 
     1163 * Setup the WordPress query. 
     1164 * 
     1165 * @since 2.0.0 
     1166 * 
     1167 * @param string $query_vars Default WP_Query arguments. 
     1168 */ 
    11091169function wp( $query_vars = '' ) { 
    11101170    global $wp, $wp_query, $wp_the_query; 
     
    12641324} 
    12651325 
    1266  
     1326/** 
     1327 * Loads the feed template from the use of an action hook. 
     1328 * 
     1329 * If the feed action does not have a hook, then the function will die with a 
     1330 * message telling the visitor that the feed is not valid. 
     1331 * 
     1332 * It is better to only have one hook for each feed. 
     1333 * 
     1334 * @since 2.1.0 
     1335 * @uses $wp_query Used to tell if the use a comment feed. 
     1336 * @uses do_action() Calls 'do_feed_$feed' hook, if a hook exists for the feed. 
     1337 */ 
    12671338function do_feed() { 
    12681339    global $wp_query; 
     
    13541425} 
    13551426 
    1356  
     1427/** 
     1428 * Test whether blog is already installed. 
     1429 * 
     1430 * The cache will be checked first. If you have a cache plugin, which saves the 
     1431 * cache values, then this will work. If you use the default WordPress cache, 
     1432 * and the database goes away, then you might have problems. 
     1433 * 
     1434 * Checks for the option siteurl for whether WordPress is installed. 
     1435 * 
     1436 * @since 2.1.0 
     1437 * @uses $wpdb 
     1438 * 
     1439 * @return bool Whether blog is already installed. 
     1440 */ 
    13571441function is_blog_installed() { 
    13581442    global $wpdb; 
    13591443 
    1360     // Check cache first.  If options table goes away and we have true cached, oh well. 
     1444    // Check cache first. If options table goes away and we have true cached, oh well. 
    13611445    if ( wp_cache_get('is_blog_installed') ) 
    13621446        return true; 
     
    13721456} 
    13731457 
    1374  
     1458/** 
     1459 * Retrieve URL with nonce added to URL query. 
     1460 * 
     1461 * @since 2.0.4 
     1462 * 
     1463 * @param string $actionurl URL to add nonce action 
     1464 * @param string $action Optional. Nonce action name 
     1465 * @return string URL with nonce action added. 
     1466 */ 
    13751467function wp_nonce_url( $actionurl, $action = -1 ) { 
    13761468    $actionurl = str_replace( '&amp;', '&', $actionurl ); 
    13771469    return wp_specialchars( add_query_arg( '_wpnonce', wp_create_nonce( $action ), $actionurl ) ); 
    13781470} 
    1379  
    13801471 
    13811472function wp_nonce_field( $action = -1, $name = "_wpnonce", $referer = true , $echo = true ) { 
     
    13911482} 
    13921483 
    1393  
    13941484function wp_referer_field( $echo = true) { 
    13951485    $ref = attribute_escape( $_SERVER['REQUEST_URI'] ); 
     
    14101500} 
    14111501 
    1412  
    14131502function wp_get_referer() { 
    14141503    $ref = ''; 
     
    14291518    return false; 
    14301519} 
    1431  
    14321520 
    14331521function wp_mkdir_p( $target ) { 
     
    14541542} 
    14551543 
    1456 // Test if a give filesystem path is absolute ('/foo/bar', 'c:\windows') 
     1544/** 
     1545 * Test if a give filesystem path is absolute ('/foo/bar', 'c:\windows'). 
     1546 * 
     1547 * @since unknown 
     1548 * 
     1549 * @param string $path File path 
     1550 * @return bool True if path is absolute, false is not absolute. 
     1551 */ 
    14571552function path_is_absolute( $path ) { 
    14581553    // this is definitive if true but fails if $path does not exist or contains a symbolic link 
     
    14711566} 
    14721567 
    1473 // Join two filesystem paths together (e.g. 'give me $path relative to $base') 
     1568/** 
     1569 * Join two filesystem paths together (e.g. 'give me $path relative to $base'). 
     1570 * 
     1571 * If the $path is absolute, then it the full path is returned. 
     1572 * 
     1573 * @since unknown 
     1574 * 
     1575 * @param string $base 
     1576 * @param string $path 
     1577 * @return string The path with the base or absolute path. 
     1578 */ 
    14741579function path_join( $base, $path ) { 
    14751580    if ( path_is_absolute($path) ) 
     
    14791584} 
    14801585 
    1481 // Returns an array containing the current upload directory's path and url, or an error message. 
    1482 function wp_upload_dir( $time = NULL ) { 
     1586/** 
     1587 * Get an array containing the current upload directory's path and url, or an error message. 
     1588 * 
     1589 * {@internal Missing Long Description}} 
     1590 * 
     1591 * @since 2.0.0 
     1592 * 
     1593 * @param unknown_type $time 
     1594 * @return unknown 
     1595 */ 
     1596function wp_upload_dir( $time = null ) { 
    14831597    $siteurl = get_option( 'siteurl' ); 
    14841598    $upload_path = get_option( 'upload_path' ); 
     
    15311645} 
    15321646 
    1533 // return a filename that is sanitized and unique for the given directory 
    1534 function wp_unique_filename( $dir, $filename, $unique_filename_callback = NULL ) { 
     1647/** 
     1648 * Get a filename that is sanitized and unique for the given directory. 
     1649 * 
     1650 * {@internal Missing Long Description}} 
     1651 * 
     1652 * @since 2.5 
     1653 * 
     1654 * @param string $dir 
     1655 * @param string $filename 
     1656 * @param string $unique_filename_callback Function name 
     1657 * @return unknown 
     1658 */ 
     1659function wp_unique_filename( $dir, $filename, $unique_filename_callback = null ) { 
    15351660    $filename = strtolower( $filename ); 
    15361661    // separate the filename into a name and extension 
     
    15381663    $ext = $info['extension']; 
    15391664    $name = basename($filename, ".{$ext}"); 
    1540      
     1665 
    15411666    // edge case: if file is named '.ext', treat as an empty name 
    15421667    if( $name === ".$ext" ) 
     
    15691694} 
    15701695 
    1571 function wp_upload_bits( $name, $deprecated, $bits, $time = NULL ) { 
     1696function wp_upload_bits( $name, $deprecated, $bits, $time = null ) { 
    15721697    if ( empty( $name ) ) 
    15731698        return array( 'error' => __( "Empty filename" ) ); 
     
    16081733} 
    16091734 
     1735/** 
     1736 * Retrieve the file type based on the extension name. 
     1737 * 
     1738 * @package WordPress 
     1739 * @since unknown 
     1740 * @uses apply_filters() Calls 'ext2type' hook on default supported types. 
     1741 * 
     1742 * @param string $ext The extension to search. 
     1743 * @return string|null The file type, example: audio, video, document, spreadsheet, etc. Null if not found. 
     1744 */ 
    16101745function wp_ext2type( $ext ) { 
    16111746    $ext2type = apply_filters('ext2type', array( 
     
    16241759} 
    16251760 
     1761/** 
     1762 * Retrieve the file type from the file name. 
     1763 * 
     1764 * You can optionally define the mime array, if needed. 
     1765 * 
     1766 * @since 2.0.4 
     1767 * 
     1768 * @param string $filename File name or path. 
     1769 * @param array $mimes Optional. Key is the file extension with value as the mime type. 
     1770 * @return array Values with extension first and mime type. 
     1771 */ 
    16261772function wp_check_filetype( $filename, $mimes = null ) { 
    16271773    // Accepted MIME types are set here as PCRE unless provided. 
     
    16881834} 
    16891835 
     1836/** 
     1837 * Retrieve nonce action "Are you sure" message. 
     1838 * 
     1839 * The action is split by verb and noun. The action format is as follows: 
     1840 * verb-action_extra. The verb is before the first dash and has the format of 
     1841 * letters and no spaces and numbers. The noun is after the dash and before the 
     1842 * underscore, if an underscore exists. The noun is also only letters. 
     1843 * 
     1844 * The filter will be called for any action, which is not defined by WordPress. 
     1845 * You may use the filter for your plugin to explain nonce actions to the user, 
     1846 * when they get the "Are you sure?" message. The filter is in the format of 
     1847 * 'explain_nonce_$verb-$noun' with the $verb replaced by the found verb and the 
     1848 * $noun replaced by the found noun. The two parameters that are given to the 
     1849 * hook are the localized "Are you sure you want to do this?" message with the 
     1850 * extra text (the text after the underscore). 
     1851 * 
     1852 * @since 2.0.4 
     1853 * 
     1854 * @param string $action Nonce action. 
     1855 * @return string Are you sure message. 
     1856 */ 
    16901857function wp_explain_nonce( $action ) { 
    16911858    if ( $action !== -1 && preg_match( '/([a-z]+)-([a-z]+)(_(.+))?/', $action, $matches ) ) { 
     
    17531920} 
    17541921 
    1755  
     1922/** 
     1923 * Display "Are You Sure" message to confirm the action being taken. 
     1924 * 
     1925 * If the action has the nonce explain message, then it will be displayed along 
     1926 * with the "Are you sure?" message. 
     1927 * 
     1928 * @since 2.0.4 
     1929 * 
     1930 * @param string $action The nonce action. 
     1931 */ 
    17561932function wp_nonce_ays( $action ) { 
    17571933    $title = __( 'WordPress Failure Notice' ); 
     
    17621938} 
    17631939 
    1764  
     1940/** 
     1941 * Kill WordPress execution and display HTML message with error message. 
     1942 * 
     1943 * Call this function complements the die() PHP function. The difference is that 
     1944 * HTML will be displayed to the user. It is recommended to use this function 
     1945 * only, when the execution should not continue any further. It is not 
     1946 * recommended to call this function very often and try to handle as many errors 
     1947 * as possible siliently. 
     1948 * 
     1949 * @since 2.0.4 
     1950 * 
     1951 * @param string $message Error message. 
     1952 * @param string $title Error title. 
     1953 */ 
    17651954function wp_die( $message, $title = '' ) { 
    17661955    global $wp_locale; 
     
    18322021} 
    18332022 
    1834  
     2023/** 
     2024 * Retrieve the WordPress home page URL. 
     2025 * 
     2026 * If the constant named 'WP_HOME' exists, then it willl be used and returned by 
     2027 * the function. This can be used to counter the redirection on your local 
     2028 * development environment. 
     2029 * 
     2030 * @access private 
     2031 * @package WordPress 
     2032 * @since 2.2.0 
     2033 * 
     2034 * @param string $url URL for the home location 
     2035 * @return string Homepage location. 
     2036 */ 
    18352037function _config_wp_home( $url = '' ) { 
    18362038    if ( defined( 'WP_HOME' ) ) 
     
    18392041} 
    18402042 
    1841  
     2043/** 
     2044 * Retrieve the WordPress site URL. 
     2045 * 
     2046 * If the constant named 'WP_SITEURL' is defined, then the value in that 
     2047 * constant will always be returned. This can be used for debugging a site on 
     2048 * your localhost while not having to change the database to your URL. 
     2049 * 
     2050 * @access private 
     2051 * @package WordPress 
     2052 * @since 2.2.0 
     2053 * 
     2054 * @param string $url URL to set the WordPress site location. 
     2055 * @return string The WordPress Site URL 
     2056 */ 
    18422057function _config_wp_siteurl( $url = '' ) { 
    18432058    if ( defined( 'WP_SITEURL' ) ) 
     
    18462061} 
    18472062 
    1848  
     2063/** 
     2064 * Set the localized direction for MCE plugin. 
     2065 * 
     2066 * Will only set the direction to 'rtl', if the WordPress locale has the text 
     2067 * direction set to 'rtl'. 
     2068 * 
     2069 * Fills in the 'directionality', 'plugins', and 'theme_advanced_button1' array 
     2070 * keys. These keys are then returned in the $input array. 
     2071 * 
     2072 * @access private 
     2073 * @package WordPress 
     2074 * @subpackage MCE 
     2075 * @since 2.1.0 
     2076 * 
     2077 * @param array $input MCE plugin array. 
     2078 * @return array Direction set for 'rtl', if needed by locale. 
     2079 */ 
    18492080function _mce_set_direction( $input ) { 
    18502081    global $wp_locale; 
     
    18592090} 
    18602091 
    1861  
     2092/** 
     2093 * Convert smiley code to the icon graphic file equivalent. 
     2094 * 
     2095 * You can turn off smilies, by going to the write setting screen and unchecking 
     2096 * the box, or by setting 'use_smilies' option to false or removing the option. 
     2097 * 
     2098 * Plugins may override the default smiley list by setting the $wpsmiliestrans 
     2099 * to an array, with the key the code the blogger types in and the value the 
     2100 * image file. 
     2101 * 
     2102 * The $wp_smiliessearch global is for the regular expression array and is 
     2103 * set each time the function is called. The $wp_smiliesreplace is the full 
     2104 * replacement. Supposely, the $wp_smiliessearch array is looped over using 
     2105 * preg_replace() or just setting the array of $wp_smiliessearch along with the 
     2106 * array of $wp_smiliesreplace in the search and replace parameters of 
     2107 * preg_replace(), which would be faster and less overhead. Either way, both are 
     2108 * used with preg_replace() and can be defined after the function is called. 
     2109 * 
     2110 * The full list of smilies can be found in the function and won't be listed in 
     2111 * the description. Probably should create a Codex page for it, so that it is 
     2112 * available. 
     2113 * 
     2114 * @global array $wpsmiliestrans 
     2115 * @global array $wp_smiliesreplace 
     2116 * @global array $wp_smiliessearch 
     2117 * @since 2.2.0 
     2118 */ 
    18622119function smilies_init() { 
    18632120    global $wpsmiliestrans, $wp_smiliessearch, $wp_smiliesreplace; 
     
    20572314 * 
    20582315 * @since 2.5 
    2059  *  
    2060  * @param mixed $maybeint data you wish to have convered to an absolute integer 
    2061  * @return int an absolute integer 
     2316 * 
     2317 * @param mixed $maybeint Data you wish to have convered to an absolute integer 
     2318 * @return int An absolute integer 
    20622319 */ 
    20632320function absint( $maybeint ) { 
     
    20782335{ 
    20792336    if (in_array('curl', get_loaded_extensions())) { 
    2080          $ssl = preg_replace( '/^http:\/\//', 'https://',  $url ); 
    2081  
    2082          $ch = curl_init(); 
    2083          curl_setopt($ch, CURLOPT_URL, $ssl); 
    2084          curl_setopt($ch, CURLOPT_FAILONERROR, true); 
    2085          curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); 
    2086          curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); 
    2087  
    2088          curl_exec($ch); 
    2089  
    2090          $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); 
    2091          curl_close ($ch); 
    2092  
    2093          if ($status == 200 || $status == 401) { 
    2094              return true; 
    2095          } 
     2337        $ssl = preg_replace( '/^http:\/\//', 'https://',  $url ); 
     2338 
     2339        $ch = curl_init(); 
     2340        curl_setopt($ch, CURLOPT_URL, $ssl); 
     2341        curl_setopt($ch, CURLOPT_FAILONERROR, true); 
     2342        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); 
     2343        curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); 
     2344 
     2345        curl_exec($ch); 
     2346 
     2347        $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); 
     2348        curl_close ($ch); 
     2349 
     2350        if ($status == 200 || $status == 401) { 
     2351            return true; 
     2352        } 
    20962353    } 
    20972354    return false; 
     
    21352392 * 
    21362393 * @param string $function The function that was called 
    2137  * @param string $version The version of WordPress that depreceated the function 
     2394 * @param string $version The version of WordPress that deprecated the function 
    21382395 * @param string $replacement Optional. The function that should have been called 
    21392396 */ 
     
    21722429 * 
    21732430 * @param string $file The file that was included 
    2174  * @param string $version The version of WordPress that depreceated the function 
     2431 * @param string $version The version of WordPress that deprecated the function 
    21752432 * @param string $replacement Optional. The function that should have been called 
    21762433 */ 
Note: See TracChangeset for help on using the changeset viewer.