WordPress.org

Make WordPress Core

Ticket #5509: pluggable.phpdoc.r6597.diff

File pluggable.phpdoc.r6597.diff, 15.1 KB (added by darkdragon, 14 years ago)

Just finished documention for pluggable functions, based off of r6597

  • pluggable.php

     
    11<?php
     2/**
     3 * These functions can be replaced via plugins. They are loaded after
     4 * plugins are loaded.
     5 *
     6 * @package WordPress
     7 */
    28
    3         /* These functions can be replaced via plugins.  They are loaded after
    4          plugins are loaded. */
    5 
    69if ( !function_exists('set_current_user') ) :
     10/**
     11 * set_current_user() - Populates global user information for any user
     12 *
     13 * Set $id to null and specify a name if you do not know a user's ID
     14 *
     15 * @since 2.0.1
     16 * @see wp_set_current_user() An alias of wp_set_current_user()
     17 *
     18 * @param int|null $id User ID.
     19 * @param string $name Optional. The user's username
     20 * @return object returns wp_set_current_user()
     21 */
    722function set_current_user($id, $name = '') {
    823        return wp_set_current_user($id, $name);
    924}
     
    3752endif;
    3853
    3954if ( !function_exists('get_currentuserinfo') ) :
     55/**
     56 * get_currentuserinfo() - Populate global variables with information about the currently logged in user
     57 *
     58 * {@internal Missing Long Description}}
     59 *
     60 * @since 0.71
     61 *
     62 * @return unknown {@internal Missing Description}}
     63 */
    4064function get_currentuserinfo() {
    4165        global $current_user;
    4266
     
    5680endif;
    5781
    5882if ( !function_exists('get_userdata') ) :
     83/**
     84 * get_userdata() - Get an object containing data about a user
     85 *
     86 * {@internal Missing Long Description}}
     87 *
     88 * @since 0.71
     89 *
     90 * @param unknown_type $user_id {@internal Missing Description}}
     91 * @return unknown {@internal Missing Description}}
     92 */
    5993function get_userdata( $user_id ) {
    6094        global $wpdb;
    6195
     
    82116endif;
    83117
    84118if ( !function_exists('update_user_cache') ) :
     119/**
     120 * update_user_cache() - Updates a users cache when overridden by a plugin
     121 *
     122 * Core function does nothing.
     123 *
     124 * @since 1.5
     125 *
     126 * @return bool Only returns true
     127 */
    85128function update_user_cache() {
    86129        return true;
    87130}
    88131endif;
    89132
    90133if ( !function_exists('get_userdatabylogin') ) :
     134/**
     135 * get_userdatabylogin() - Grabs some info about a user based on their login name
     136 *
     137 * {@internal Missing Long Description}}
     138 *
     139 * @since 0.71
     140 *
     141 * @param string $user_login {@internal Missing Description}}
     142 * @return unknown {@internal Missing Description}}
     143 */
    91144function get_userdatabylogin($user_login) {
    92145        global $wpdb;
    93146        $user_login = sanitize_user( $user_login );
     
    145198endif;
    146199
    147200if ( !function_exists( 'wp_mail' ) ) :
     201/**
     202 * wp_mail() - Function to send mail, similar to PHP's mail
     203 *
     204 * {@internal Missing Long Description}}
     205 *
     206 * @since 1.2.1
     207 *
     208 * @param string $to {@internal Missing Description}}
     209 * @param string $subject {@internal Missing Description}}
     210 * @param string $message {@internal Missing Description}}
     211 * @param string $headers {@internal Missing Description}}
     212 * @return unknown {@internal Missing Description}}
     213 */
    148214function wp_mail( $to, $subject, $message, $headers = '' ) {
    149215        // Compact the input, apply the filters, and extract them back out
    150216        extract( apply_filters( 'wp_mail', compact( 'to', 'subject', 'message', 'headers' ) ) );
     
    291357endif;
    292358
    293359if ( !function_exists('wp_login') ) :
     360/**
     361 * wp_login() - Checks a users login information and logs them in if it checks out
     362 *
     363 * {@internal Missing Long Description}}
     364 *
     365 * @since 1.2.2
     366 *
     367 * @param string $username {@internal Missing Description}}
     368 * @param string $password {@internal Missing Description}}
     369 * @param bool $deprecated {@internal Missing Description}}
     370 * @return unknown {@internal Missing Description}}
     371 */
    294372function wp_login($username, $password, $deprecated = '') {
    295373        global $error;
    296374
     
    403481endif;
    404482
    405483if ( !function_exists('is_user_logged_in') ) :
     484/**
     485 * is_user_logged_in() - Checks if the current visitor is a logged in user
     486 *
     487 * {@internal Missing Long Description}}
     488 *
     489 * @since 2.0.0
     490 *
     491 * @return bool {@internal Missing Description}}
     492 */
    406493function is_user_logged_in() {
    407494        $user = wp_get_current_user();
    408495
     
    414501endif;
    415502
    416503if ( !function_exists('auth_redirect') ) :
     504/**
     505 * auth_redirect() - Checks if a user is logged in, if not it redirects them to the login page
     506 *
     507 * {@internal Missing Long Description}}
     508 *
     509 * @since 1.5
     510 */
    417511function auth_redirect() {
    418512        // Checks if a user is logged in, if not redirects them to the login page
    419513        if ( (!empty($_COOKIE[AUTH_COOKIE]) &&
     
    428522endif;
    429523
    430524if ( !function_exists('check_admin_referer') ) :
     525/**
     526 * check_admin_referer() - Makes sure that a user was referred from another admin page, to avoid security exploits
     527 *
     528 * {@internal Missing Long Description}}
     529 *
     530 * @since 1.2.0
     531 *
     532 * @param unknown_type $action {@internal Missing Description}}
     533 */
    431534function check_admin_referer($action = -1) {
    432535        $adminurl = strtolower(get_option('siteurl')).'/wp-admin';
    433536        $referer = strtolower(wp_get_referer());
     
    469572}
    470573endif;
    471574
    472 // Cookie safe redirect.  Works around IIS Set-Cookie bug.
    473 // http://support.microsoft.com/kb/q176113/
    474575if ( !function_exists('wp_redirect') ) :
     576/**
     577 * wp_redirect() - Redirects to another page, with a workaround for the IIS Set-Cookie bug
     578 *
     579 * @link http://support.microsoft.com/kb/q176113/
     580 * @since 1.5.1
     581 *
     582 * @param string $location {@internal Missing Description}}
     583 * @param int $status {@internal Missing Description}}
     584 * @return unknown {@internal Missing Description}}
     585 */
    475586function wp_redirect($location, $status = 302) {
    476587        global $is_IIS;
    477588
     
    494605
    495606if ( !function_exists('wp_sanitize_redirect') ) :
    496607/**
    497  * sanitizes a URL for use in a redirect
     608 * wp_sanitize_redirect() - Sanitizes a URL for use in a redirect
     609 *
     610 * @since 2.3
     611 *
    498612 * @return string redirect-sanitized URL
    499613 **/
    500614function wp_sanitize_redirect($location) {
     
    519633
    520634if ( !function_exists('wp_safe_redirect') ) :
    521635/**
    522  * performs a safe (local) redirect, using wp_redirect()
    523  * @return void
     636 * wp_safe_redirect() - Performs a safe (local) redirect, using wp_redirect()
     637 *
     638 * @since 2.3
     639 *
     640 * @return void Does not return anything
    524641 **/
    525642function wp_safe_redirect($location, $status = 302) {
    526643
     
    544661endif;
    545662
    546663if ( ! function_exists('wp_notify_postauthor') ) :
     664/**
     665 * wp_notify_postauthor() - Notify an author of a comment/trackback/pingback to one of their posts
     666 *
     667 * @since 1.0
     668 *
     669 * @param int $comment_id Comment ID
     670 * @param string $comment_type Optional. The comment type either 'comment' (default), 'trackback', or 'pingback'
     671 * @return bool False if user email does not exist. True on completion.
     672 */
    547673function wp_notify_postauthor($comment_id, $comment_type='') {
    548674        $comment = get_comment($comment_id);
    549675        $post    = get_post($comment->comment_post_ID);
     
    613739}
    614740endif;
    615741
    616 /* wp_notify_moderator
    617    notifies the moderator of the blog (usually the admin)
    618    about a new comment that waits for approval
    619    always returns true
     742if ( !function_exists('wp_notify_moderator') ) :
     743/**
     744 * wp_notify_moderator() - Notifies the moderator of the blog about a new comment that is awaiting approval
     745 *
     746 * @since 1.0
     747 * @uses $wpdb
     748 *
     749 * @param int $comment_id Comment ID
     750 * @return bool Always returns true
    620751 */
    621 if ( !function_exists('wp_notify_moderator') ) :
    622752function wp_notify_moderator($comment_id) {
    623753        global $wpdb;
    624754
     
    658788endif;
    659789
    660790if ( !function_exists('wp_new_user_notification') ) :
     791/**
     792 * wp_new_user_notification() - Notify the blog admin of a new user, normally via email
     793 *
     794 * @since 2.0
     795 *
     796 * @param int $user_id User ID
     797 * @param string $plaintext_pass Optional. The user's plaintext password
     798 */
    661799function wp_new_user_notification($user_id, $plaintext_pass = '') {
    662800        $user = new WP_User($user_id);
    663801
     
    683821endif;
    684822
    685823if ( !function_exists('wp_verify_nonce') ) :
     824/**
     825 * wp_verify_nonce() - Verify that correct nonce was used with time limit
     826 *
     827 * The user is given an amount of time to use the token, so therefore, since
     828 * the UID and $action remain the same, the independent variable is the time.
     829 *
     830 * @since 2.0.4
     831 *
     832 * @param string $nonce Nonce that was used in the form to verify
     833 * @param string|int $action Should give context to what is taking place and be the same when nonce was created.
     834 * @return bool Whether the nonce check passed or failed.
     835 */
    686836function wp_verify_nonce($nonce, $action = -1) {
    687837        $user = wp_get_current_user();
    688838        $uid = (int) $user->id;
     
    697847endif;
    698848
    699849if ( !function_exists('wp_create_nonce') ) :
     850/**
     851 * wp_create_nonce() - Creates a random, one time use token
     852 *
     853 * @since 2.0.4
     854 *
     855 * @param string|int $action Scalar value to add context to the nonce.
     856 * @return string The one use form token
     857 */
    700858function wp_create_nonce($action = -1) {
    701859        $user = wp_get_current_user();
    702860        $uid = (int) $user->id;
     
    708866endif;
    709867
    710868if ( !function_exists('wp_salt') ) :
     869/**
     870 * wp_salt() - Get salt to add to hashes to help prevent attacks
     871 *
     872 * You can set the salt by defining two areas. One is in the database and
     873 * the other is in your wp-config.php file. The database location is defined
     874 * in the option named 'secret', but most likely will not need to be changed.
     875 *
     876 * The second, located in wp-config.php, is a constant named 'SECRET_KEY', but
     877 * is not required. If the constant is not defined then the database constants
     878 * will be used, since they are most likely given to be unique. However, given
     879 * that the salt will be added to the password and can be seen, the constant
     880 * is recommended to be set manually.
     881 *
     882 * <code>
     883 * define('SECRET_KEY', 'mAry1HadA15|\/|b17w55w1t3asSn09w');
     884 * </code>
     885 *
     886 * Attention: Do not use above example!
     887 *
     888 * Salting passwords helps against tools which has stored hashed values
     889 * of common dictionary strings. The added values makes it harder to crack
     890 * if given salt string is not weak.
     891 *
     892 * Salting only helps if the string is not predictable and should be
     893 * made up of various characters. Think of the salt as a password for
     894 * securing your passwords, but common among all of your passwords.
     895 * Therefore the salt should be as long as possible as as difficult as
     896 * possible, because you will not have to remember it.
     897 *
     898 * @since 2.5
     899 *
     900 * @return string Salt value from either 'SECRET_KEY' or 'secret' option
     901 */
    711902function wp_salt() {
    712903
    713904        $secret_key = '';
     
    729920endif;
    730921
    731922if ( !function_exists('wp_hash') ) :
     923/**
     924 * wp_hash() - Get hash of given string
     925 *
     926 * @since 2.0.4
     927 * @uses wp_salt() Get WordPress salt
     928 *
     929 * @param string $data Plain text to hash
     930 * @return string Hash of $data
     931 */
    732932function wp_hash($data) {
    733933        $salt = wp_salt();
    734934
     
    741941endif;
    742942
    743943if ( !function_exists('wp_hash_password') ) :
     944/**
     945 * wp_hash_password() - Create a hash (encrypt) of a plain text password
     946 *
     947 * For integration with other applications, this function can be
     948 * overwritten to instead use the other package password checking
     949 * algorithm.
     950 *
     951 * @since 2.5
     952 * @global object $wp_hasher PHPass object
     953 * @uses PasswordHash::HashPassword
     954 *
     955 * @param string $password Plain text user password to hash
     956 * @return string The hash string of the password
     957 */
    744958function wp_hash_password($password) {
    745959        global $wp_hasher;
    746960
     
    755969endif;
    756970
    757971if ( !function_exists('wp_check_password') ) :
     972/**
     973 * wp_check_password() - Checks the plaintext password against the encrypted Password
     974 *
     975 * Maintains compatibility between old version and the new cookie
     976 * authentication protocol using PHPass library. The $hash parameter
     977 * is the encrypted password and the function compares the plain text
     978 * password when encypted similarly against the already encrypted
     979 * password to see if they match.
     980 *
     981 * For integration with other applications, this function can be
     982 * overwritten to instead use the other package password checking
     983 * algorithm.
     984 *
     985 * @since 2.5
     986 * @global object $wp_hasher PHPass object used for checking the password
     987 *      against the $hash + $password
     988 * @uses PasswordHash::CheckPassword
     989 *
     990 * @param string $password Plaintext user's password
     991 * @param string $hash Hash of the user's password to check against.
     992 * @return bool False, if the $password does not match the hashed password
     993 */
    758994function wp_check_password($password, $hash) {
    759995        global $wp_hasher;
    760996
     
    7751011
    7761012if ( !function_exists('wp_generate_password') ) :
    7771013/**
    778  * Generates a random password drawn from the defined set of characters
    779  * @return string the password
     1014 * wp_generate_password() - Generates a random password drawn from the defined set of characters
     1015 *
     1016 * @since 2.5
     1017 *
     1018 * @return string The random password
    7801019 **/
    7811020function wp_generate_password() {
    7821021        $chars = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
     
    7891028endif;
    7901029
    7911030if ( !function_exists('wp_set_password') ) :
     1031/**
     1032 * wp_set_password() - Updates the user's password with a new encrypted one
     1033 *
     1034 * For integration with other applications, this function can be
     1035 * overwritten to instead use the other package password checking
     1036 * algorithm.
     1037 *
     1038 * @since 2.5
     1039 * @uses $wpdb WordPress database object for queries
     1040 * @uses wp_hash_password() Used to encrypt the user's password before passing to the database
     1041 *
     1042 * @param string $password The plaintext new user password
     1043 * @param int $user_id User ID
     1044 */
    7921045function wp_set_password( $password, $user_id ) {
    7931046        global $wpdb;
    7941047
     
    7991052}
    8001053endif;
    8011054
    802 // Deprecated. Use wp_set_auth_cookie()
    8031055if ( !function_exists('wp_setcookie') ) :
     1056/**
     1057 * wp_setcookie() - Sets a cookie for a user who just logged in
     1058 *
     1059 * @since 1.5
     1060 * @deprecated Use wp_set_auth_cookie()
     1061 * @see wp_set_auth_cookie()
     1062 *
     1063 * @param string  $username The user's username
     1064 * @param string  $password Optional. The user's password
     1065 * @param bool $already_md5 Optional. Whether the password has already been through MD5
     1066 * @param string $home Optional. Will be used instead of COOKIEPATH if set
     1067 * @param string $siteurl Optional. Will be used instead of SITECOOKIEPATH if set
     1068 * @param bool $remember Optional. Remember that the user is logged in
     1069 */
    8041070function wp_setcookie($username, $password = '', $already_md5 = false, $home = '', $siteurl = '', $remember = false) {
    8051071        _deprecated_function( __FUNCTION__, '2.4', 'wp_set_auth_cookie()' );
    8061072        $user = get_userdatabylogin($username);
     
    8081074}
    8091075endif;
    8101076
    811 // Deprecated. Use wp_clear_auth_cookie()
    8121077if ( !function_exists('wp_clearcookie') ) :
     1078/**
     1079 * wp_clearcookie() - Clears the authentication cookie, logging the user out
     1080 *
     1081 * @since 1.5
     1082 * @deprecated Use wp_clear_auth_cookie()
     1083 * @see wp_clear_auth_cookie()
     1084 */
    8131085function wp_clearcookie() {
    8141086        _deprecated_function( __FUNCTION__, '2.4', 'wp_clear_auth_cookie()' );
    8151087        wp_clear_auth_cookie();
    8161088}
    8171089endif;
    8181090
    819 // Deprecated.  No alternative.
    8201091if ( !function_exists('wp_get_cookie_login') ):
     1092/**
     1093 * wp_get_cookie_login() - Gets the user cookie login
     1094 *
     1095 * This function is deprecated and should no longer be extended as it won't
     1096 * be used anywhere in WordPress. Also, plugins shouldn't use it either.
     1097 *
     1098 * @since 2.0.4
     1099 * @deprecated No alternative
     1100 *
     1101 * @return bool Always returns false
     1102 */
    8211103function wp_get_cookie_login() {
    8221104        _deprecated_function( __FUNCTION__, '2.4', '' );
    8231105        return false;