WordPress.org

Make WordPress Core

Changeset 8606


Ignore:
Timestamp:
08/10/08 16:45:50 (6 years ago)
Author:
westi
Message:

phpdoc for general functions. See #5639 props jacobsantos.

File:
1 edited

Legend:

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

    r8600 r8606  
    8787 * @param string $type Either 'mysql' or 'timestamp'. 
    8888 * @param int|bool $gmt Optional. Whether to use $gmt offset. Default is false. 
    89  * @return unknown 
     89 * @return int|string String if $type is 'gmt', int if $type is 'timestamp'. 
    9090 */ 
    9191function current_time( $type, $gmt = 0 ) { 
     
    177177 * @param int|string $bytes Number of bytes. Note max integer size for integers. 
    178178 * @param int $decimals Precision of number of decimal places. 
    179  * @return unknown 
     179 * @return bool|string False on failure. Number string on success. 
    180180 */ 
    181181function size_format( $bytes, $decimals = null ) { 
     
    318318 * replaced with the option name. This gives the value as the only parameter. 
    319319 * 
     320 * If the option was serialized, when the option was added and, or updated, then 
     321 * it will be unserialized, when it is returned. 
     322 * 
    320323 * @since 1.5.0 
    321324 * @package WordPress 
     
    380383 * Protect WordPress special option from being modified. 
    381384 * 
    382  * Will die if $option is in protected list. 
     385 * Will die if $option is in protected list. Protected options are 'alloptions' 
     386 * and 'notoptions' options. 
    383387 * 
    384388 * @since 2.2.0 
     
    474478 * Update the value of an option that was already added. 
    475479 * 
     480 * You do not need to serialize values, if the value needs to be serialize, then 
     481 * it will be serialized before it is inserted into the database. Remember, 
     482 * resources can not be serialized or added as an option. 
     483 * 
    476484 * If the option does not exist, then the option will be added with the option 
    477485 * value, but you will not be able to set whether it is autoloaded. If you want 
     
    540548 * Add a new option. 
    541549 * 
     550 * You do not need to serialize values, if the value needs to be serialize, then 
     551 * it will be serialized before it is inserted into the database. Remember, 
     552 * resources can not be serialized or added as an option. 
     553 * 
    542554 * You can create options without values and then add values later. Does not 
    543555 * check whether the option has already been added, but does check that you 
     
    603615 * @package WordPress 
    604616 * @subpackage Option 
    605  * @since unknown 
     617 * @since 1.2.0 
    606618 * 
    607619 * @param string $name Option name to remove. 
     
    635647 * Serialize data, if needed. 
    636648 * 
     649 * @since 2.0.5 
     650 * 
    637651 * @param mixed $data Data that might be serialized. 
    638652 * @return mixed A scalar data 
     
    654668 * them at the bottom of the content with numbers. 
    655669 * 
    656  * @since unknown 
     670 * @since 0.71 
    657671 * 
    658672 * @param string $content Content to get links 
     
    686700 * @package WordPress 
    687701 * @subpackage XMLRPC 
    688  * @since unknown 
     702 * @since 0.71 
    689703 * 
    690704 * @global string $post_default_title Default XMLRPC post title. 
     
    714728 * @package WordPress 
    715729 * @subpackage XMLRPC 
    716  * @since unknown 
     730 * @since 0.71 
    717731 * 
    718732 * @global string $post_default_category Default XMLRPC post category. 
     
    737751 * @package WordPress 
    738752 * @subpackage XMLRPC 
    739  * @since unknown 
     753 * @since 0.71 
    740754 * 
    741755 * @param string $content XMLRPC XML Request content 
     
    758772 * @package WordPress 
    759773 * @subpackage Debug 
    760  * @since unknown 
     774 * @since 0.71 
    761775 * @uses $debug Used for whether debugging is enabled. 
    762776 * 
     
    783797 * @package WordPress 
    784798 * @subpackage Debug 
    785  * @since unknown 
     799 * @since 0.71 
    786800 * @uses $debug Used for whether debugging is enabled. 
    787801 * 
     
    803817 * @package WordPress 
    804818 * @subpackage Debug 
    805  * @since unknown 
     819 * @since 0.71 
    806820 * @uses $debug Used for whether debugging is enabled. 
    807821 * 
     
    814828} 
    815829 
     830/** 
     831 * {@internal Missing Short Description}} 
     832 * 
     833 * {@internal Missing Long Description}} 
     834 * 
     835 * @package WordPress 
     836 * @since 1.5.0 
     837 * 
     838 * @uses $wpdb 
     839 * 
     840 * @param string $content  
     841 * @param int $post_ID Post ID 
     842 */ 
    816843function do_enclose( $content, $post_ID ) { 
    817844    global $wpdb; 
     
    866893 * the file to that path. 
    867894 * 
    868  * @since unknown 
     895 * @since 2.5.0 
    869896 * 
    870897 * @param string $url 
     
    9841011 *      http_build_query() does. 
    9851012 * 
    986  * @since unknown 
     1013 * @since 2.3.0 
    9871014 * 
    9881015 * @param array $data URL-encode key/value pairs. 
     
    10971124 * 
    10981125 * @uses $wpdb Used to sanitize values 
     1126 * @since 0.71 
    10991127 * 
    11001128 * @param array $array Array to used to walk while sanitizing contents. 
     
    11201148 * fopen can't be used. 
    11211149 * 
    1122  * @since unknown 
     1150 * @since 1.5.1 
    11231151 * 
    11241152 * @param string $uri URI/URL of web page to retrieve. 
     
    12451273 * Set HTTP status header. 
    12461274 * 
    1247  * @since unknown 
     1275 * @since 2.0.0 
    12481276 * @uses apply_filters() Calls 'status_header' on status header string, HTTP 
    12491277 *      HTTP code, HTTP code description, and protocol string as separate 
     
    14591487 * Retrieve URL with nonce added to URL query. 
    14601488 * 
     1489 * @package WordPress 
     1490 * @subpackage Security 
    14611491 * @since 2.0.4 
    14621492 * 
     
    14701500} 
    14711501 
     1502/** 
     1503 * Retrieve or display nonce hidden field for forms. 
     1504 * 
     1505 * The nonce field is used to validate that the contents of the form came from 
     1506 * the location on the current site and not somewhere else. The nonce does not 
     1507 * offer absolute protection, but should protect against most cases. It is very 
     1508 * important to use nonce field in forms. 
     1509 * 
     1510 * If you set $echo to true and set $referer to true, then you will need to 
     1511 * retrieve the {@link wp_referer_field() wp referer field}. If you have the 
     1512 * $referer set to true and are echoing the nonce field, it will also echo the 
     1513 * referer field. 
     1514 * 
     1515 * The $action and $name are optional, but if you want to have better security, 
     1516 * it is strongly suggested to set those two parameters. It is easier to just 
     1517 * call the function without any parameters, because validation of the nonce 
     1518 * doesn't require any parameters, but since crackers know what the default is 
     1519 * it won't be difficult for them to find a way around your nonce and cause 
     1520 * damage. 
     1521 * 
     1522 * The input name will be whatever $name value you gave. The input value will be 
     1523 * the nonce creation value. 
     1524 * 
     1525 * @package WordPress 
     1526 * @subpackage Security 
     1527 * @since 2.0.4 
     1528 * 
     1529 * @param string $action Optional. Action name. 
     1530 * @param string $name Optional. Nonce name. 
     1531 * @param bool $referer Optional, default true. Whether to set the referer field for validation. 
     1532 * @param bool $echo Optional, default true. Whether to display or return hidden form field. 
     1533 * @return string Nonce field. 
     1534 */ 
    14721535function wp_nonce_field( $action = -1, $name = "_wpnonce", $referer = true , $echo = true ) { 
    14731536    $name = attribute_escape( $name ); 
     
    14821545} 
    14831546 
     1547/** 
     1548 * Retrieve or display referer hidden field for forms. 
     1549 * 
     1550 * The referer link is the current Request URI from the server super global. The 
     1551 * input name is '_wp_http_referer', in case you wanted to check manually. 
     1552 * 
     1553 * @package WordPress 
     1554 * @subpackage Security 
     1555 * @since 2.0.4 
     1556 * 
     1557 * @param bool $echo Whether to echo or return the referer field. 
     1558 * @return string Referer field. 
     1559 */ 
    14841560function wp_referer_field( $echo = true) { 
    14851561    $ref = attribute_escape( $_SERVER['REQUEST_URI'] ); 
     
    14911567} 
    14921568 
     1569/** 
     1570 * Retrieve or display original referer hidden field for forms. 
     1571 * 
     1572 * The input name is '_wp_original_http_referer' and will be either the same 
     1573 * value of {@link wp_referer_field()}, if that was posted already or it will 
     1574 * be the current page, if it doesn't exist. 
     1575 * 
     1576 * @package WordPress 
     1577 * @subpackage Security 
     1578 * @since 2.0.4 
     1579 * 
     1580 * @param bool $echo Whether to echo the original http referer 
     1581 * @param string $jump_back_to Optional, default is 'current'. Can be 'previous' or page you want to jump back to. 
     1582 * @return string Original referer field. 
     1583 */ 
    14931584function wp_original_referer_field( $echo = true, $jump_back_to = 'current' ) { 
    14941585    $jump_back_to = ( 'previous' == $jump_back_to ) ? wp_get_referer() : $_SERVER['REQUEST_URI']; 
     
    15001591} 
    15011592 
     1593/** 
     1594 * Retrieve referer from '_wp_http_referer', HTTP referer, or current page respectively. 
     1595 * 
     1596 * @package WordPress 
     1597 * @subpackage Security 
     1598 * @since 2.0.4 
     1599 * 
     1600 * @return string|bool False on failure. Referer URL on success. 
     1601 */ 
    15021602function wp_get_referer() { 
    15031603    $ref = ''; 
     
    15121612} 
    15131613 
    1514  
     1614/** 
     1615 * Retrieve original referer that was posted, if it exists. 
     1616 * 
     1617 * @package WordPress 
     1618 * @subpackage Security 
     1619 * @since 2.0.4 
     1620 * 
     1621 * @return string|bool False if no original referer or original referer if set. 
     1622 */ 
    15151623function wp_get_original_referer() { 
    15161624    if ( !empty( $_REQUEST['_wp_original_http_referer'] ) ) 
     
    15191627} 
    15201628 
     1629/** 
     1630 * Recursive directory creation based on full path. 
     1631 * 
     1632 * Will attempt to set permissions on folders. 
     1633 * 
     1634 * @since 2.0.1 
     1635 * 
     1636 * @param string $target Full path to attempt to create. 
     1637 * @return bool Whether the path was created or not. True if path already exists. 
     1638 */ 
    15211639function wp_mkdir_p( $target ) { 
    15221640    // from php.net/mkdir user contributed notes 
     
    15451663 * Test if a give filesystem path is absolute ('/foo/bar', 'c:\windows'). 
    15461664 * 
    1547  * @since unknown 
     1665 * @since 2.5.0 
    15481666 * 
    15491667 * @param string $path File path 
     
    15711689 * If the $path is absolute, then it the full path is returned. 
    15721690 * 
    1573  * @since unknown 
     1691 * @since 2.5.0 
    15741692 * 
    15751693 * @param string $base 
     
    15851703 
    15861704/** 
    1587  * Get an array containing the current upload directory's path and url, or an error message. 
    1588  * 
    1589  * {@internal Missing Long Description}} 
     1705 * Get an array containing the current upload directory's path and url. 
     1706 * 
     1707 * Checks the 'upload_path' option, which should be from the web root folder, 
     1708 * and if it isn't empty it will be used. If it is empty, then the path will be 
     1709 * 'WP_CONTENT_DIR/uploads'. If the 'UPLOADS' constant is defined, then it will 
     1710 * override the 'upload_path' option and 'WP_CONTENT_DIR/uploads' path. 
     1711 * 
     1712 * The upload URL path is set either by the 'upload_url_path' option or by using 
     1713 * the 'WP_CONTENT_URL' constant and appending '/uploads' to the path. 
     1714 * 
     1715 * If the 'uploads_use_yearmonth_folders' is set to true (checkbox if checked in 
     1716 * the administration settings panel), then the time will be used. The format 
     1717 * will be year first and then month. 
     1718 * 
     1719 * If the path couldn't be created, then an error will be returned with the key 
     1720 * 'error' containing the error message. The error suggests that the parent 
     1721 * directory is not writable by the server. 
     1722 * 
     1723 * On success, the returned array will have many indices: 
     1724 * 'path' - base directory and sub directory or full path to upload directory. 
     1725 * 'url' - base url and sub directory or absolute URL to upload directory. 
     1726 * 'subdir' - sub directory if uploads use year/month folders option is on. 
     1727 * 'basedir' - path without subdir. 
     1728 * 'baseurl' - URL path without subdir. 
     1729 * 'error' - set to false. 
    15901730 * 
    15911731 * @since 2.0.0 
    1592  * 
    1593  * @param unknown_type $time 
    1594  * @return unknown 
     1732 * @uses apply_filters() Calls 'upload_dir' on returned array. 
     1733 * 
     1734 * @param string $time Optional. Time formatted in 'yyyy/mm'. 
     1735 * @return array See above for description. 
    15951736 */ 
    15961737function wp_upload_dir( $time = null ) { 
     
    16481789 * Get a filename that is sanitized and unique for the given directory. 
    16491790 * 
    1650  * {@internal Missing Long Description}} 
     1791 * If the filename is not unique, then a number will be added to the filename 
     1792 * before the extension, and will continue adding numbers until the filename is 
     1793 * unique. 
     1794 * 
     1795 * The callback must accept two parameters, the first one is the directory and 
     1796 * the second is the filename. The callback must be a function. 
    16511797 * 
    16521798 * @since 2.5 
     
    16541800 * @param string $dir 
    16551801 * @param string $filename 
    1656  * @param string $unique_filename_callback Function name 
    1657  * @return unknown 
     1802 * @param string $unique_filename_callback Function name, must be a function. 
     1803 * @return string New filename, if given wasn't unique. 
    16581804 */ 
    16591805function wp_unique_filename( $dir, $filename, $unique_filename_callback = null ) { 
     
    16941840} 
    16951841 
     1842/** 
     1843 * Create a file in the upload folder with given content. 
     1844 * 
     1845 * If there is an error, then the key 'error' will exist with the error message. 
     1846 * If success, then the key 'file' will have the unique file path, the 'url' key 
     1847 * will have the link to the new file. and the 'error' key will be set to false. 
     1848 * 
     1849 * This function will not move an uploaded file to the upload folder. It will 
     1850 * create a new file with the content in $bits parameter. If you move the upload 
     1851 * file, read the content of the uploaded file, and then you can give the 
     1852 * filename and content to this function, which will add it to the upload 
     1853 * folder. 
     1854 * 
     1855 * The permissions will be set on the new file automatically by this function. 
     1856 * 
     1857 * @since 2.0.0 
     1858 * 
     1859 * @param string $name 
     1860 * @param null $deprecated Not used. Set to null. 
     1861 * @param mixed $bits File content 
     1862 * @param string $time Optional. Time formatted in 'yyyy/mm'. 
     1863 * @return array 
     1864 */ 
    16961865function wp_upload_bits( $name, $deprecated, $bits, $time = null ) { 
    16971866    if ( empty( $name ) ) 
     
    17371906 * 
    17381907 * @package WordPress 
    1739  * @since unknown 
     1908 * @since 2.5.0 
    17401909 * @uses apply_filters() Calls 'ext2type' hook on default supported types. 
    17411910 * 
     
    18502019 * extra text (the text after the underscore). 
    18512020 * 
     2021 * @package WordPress 
     2022 * @subpackage Security 
    18522023 * @since 2.0.4 
    18532024 * 
     
    19262097 * with the "Are you sure?" message. 
    19272098 * 
     2099 * @package WordPress 
     2100 * @subpackage Security 
    19282101 * @since 2.0.4 
    19292102 * 
     
    22522425 * defined globally by the inline code in wp-db.php. 
    22532426 * 
    2254  * @since 2.5 
     2427 * @since 2.5.0 
    22552428 * @global $wpdb WordPress Database Object 
    22562429 */ 
     
    22742447 * same. 
    22752448 * 
    2276  * @since 2.5 
     2449 * This function was backported to the the WordPress 2.3.2, but originally was 
     2450 * added in WordPress 2.5.0. 
     2451 * 
     2452 * @since 2.3.2 
    22772453 * @uses $wpdb 
    22782454 */ 
     
    23132489 * Converts value to positive integer. 
    23142490 * 
    2315  * @since 2.5 
     2491 * @since 2.5.0 
    23162492 * 
    23172493 * @param mixed $maybeint Data you wish to have convered to an absolute integer 
     
    23282504 * using the https in the siteurl. Requires cURL extension to work correctly. 
    23292505 * 
    2330  * @since 2.5 
     2506 * @since 2.5.0 
    23312507 * 
    23322508 * @return bool Whether or not SSL access is available 
     
    23582534 * Secure URL, if available or the given URL. 
    23592535 * 
    2360  * @since 2.5 
     2536 * @since 2.5.0 
    23612537 * 
    23622538 * @param string $url Complete URL path with transport. 
     
    23852561 * @package WordPress 
    23862562 * @package Debug 
    2387  * @since 2.5 
     2563 * @since 2.5.0 
    23882564 * @access private 
    23892565 * 
     
    24222598 * @package WordPress 
    24232599 * @package Debug 
    2424  * @since 2.5 
     2600 * @since 2.5.0 
    24252601 * @access private 
    24262602 * 
     
    24482624 * Is the server running earlier than 1.5.0 version of lighttpd 
    24492625 * 
    2450  * @since unknown 
     2626 * @since 2.5.0 
    24512627 * 
    24522628 * @return bool Whether the server is running lighttpd < 1.5.0 
     
    24612637 * Does the specified module exist in the apache config? 
    24622638 * 
    2463  * @since unknown 
     2639 * @since 2.5.0 
    24642640 * 
    24652641 * @param string $mod e.g. mod_rewrite 
     
    24952671 * files list. 
    24962672 * 
    2497  * @since 2.6 
     2673 * @since 1.2.0 
    24982674 * 
    24992675 * @param string $file File path. 
     
    25202696 * Determine if SSL is used. 
    25212697 * 
    2522  * @since 2.6 
     2698 * @since 2.6.0 
    25232699 * 
    25242700 * @return bool True if SSL, false if not used. 
     
    25312707 * Whether SSL login should be forced. 
    25322708 * 
    2533  * @since 2.6 
     2709 * @since 2.6.0 
    25342710 * 
    25352711 * @param string|bool $force Optional. 
     
    25512727 * Whether to force SSL used for the Administration Panels. 
    25522728 * 
    2553  * @since 2.6 
     2729 * @since 2.6.0 
    25542730 * 
    25552731 * @param string|bool $force 
     
    25742750 * directory. 
    25752751 * 
    2576  * @since 2.6 
     2752 * @since 2.6.0 
    25772753 * 
    25782754 * @return string 
Note: See TracChangeset for help on using the changeset viewer.