WordPress.org
Get WordPress

Make WordPress Core

Changeset 8606


Ignore:
Timestamp:
08/10/2008 04:45:50 PM (16 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.