WordPress.org

Make WordPress Core

Ticket #5509: pluggable.phpdoc.r6582.diff

File pluggable.phpdoc.r6582.diff, 18.8 KB (added by darkdragon, 14 years ago)

Still incomplete phpdoc based off of 6582

  • 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}
    1025endif;
    1126
    1227if ( !function_exists('wp_set_current_user') ) :
     28/**
     29 * wp_set_current_user() - {@internal Missing Short Description}}
     30 *
     31 * {@internal Missing Long Description
     32 *              Documentation must describe why wp_set_current_user() would be override
     33 *              instead of set_current_user(). There is a reason and must look for it.
     34 *              If exists on the codex, then link to that instead.
     35 * }}
     36 *
     37 * @since 2.0.4
     38 * @global object $current_user The current user object which holds the user data.
     39 *
     40 * @param int $id User ID
     41 * @param string $name {@internal Missing Description}}
     42 * @return object {@internal Missing Description}}
     43 */
    1344function wp_set_current_user($id, $name = '') {
    1445        global $current_user;
    1546
     
    2758endif;
    2859
    2960if ( !function_exists('wp_get_current_user') ) :
     61/**
     62 * wp_get_current_user() - {@internal Missing Short Description}}
     63 *
     64 * {@internal Missing Long Description}}
     65 *
     66 * @since 2.0.4
     67 *
     68 * @return unknown {@internal Missing Description}}
     69 */
    3070function wp_get_current_user() {
    3171        global $current_user;
    3272
     
    3777endif;
    3878
    3979if ( !function_exists('get_currentuserinfo') ) :
     80/**
     81 * get_currentuserinfo() - Populate global variables with information about the currently logged in user
     82 *
     83 * {@internal Missing Long Description}}
     84 *
     85 * @since 0.71
     86 *
     87 * @return unknown {@internal Missing Description}}
     88 */
    4089function get_currentuserinfo() {
    4190        global $current_user;
    4291
     
    56105endif;
    57106
    58107if ( !function_exists('get_userdata') ) :
     108/**
     109 * get_userdata() - Get an object containing data about a user
     110 *
     111 * {@internal Missing Long Description}}
     112 *
     113 * @since 0.71
     114 *
     115 * @param unknown_type $user_id {@internal Missing Description}}
     116 * @return unknown {@internal Missing Description}}
     117 */
    59118function get_userdata( $user_id ) {
    60119        global $wpdb;
    61120
     
    82141endif;
    83142
    84143if ( !function_exists('update_user_cache') ) :
     144/**
     145 * update_user_cache() - Updates a users cache when overridden by a plugin
     146 *
     147 * Core function does nothing.
     148 *
     149 * @since 1.5
     150 *
     151 * @return bool Only returns true
     152 */
    85153function update_user_cache() {
    86154        return true;
    87155}
    88156endif;
    89157
    90158if ( !function_exists('get_userdatabylogin') ) :
     159/**
     160 * get_userdatabylogin() - Grabs some info about a user based on their login name
     161 *
     162 * {@internal Missing Long Description}}
     163 *
     164 * @since 0.71
     165 *
     166 * @param string $user_login {@internal Missing Description}}
     167 * @return unknown {@internal Missing Description}}
     168 */
    91169function get_userdatabylogin($user_login) {
    92170        global $wpdb;
    93171        $user_login = sanitize_user( $user_login );
     
    118196endif;
    119197
    120198if ( !function_exists('get_user_by_email') ) :
     199/**
     200 * get_user_by_email() - {@internal Missing Short Description}}
     201 *
     202 * {@internal Missing Long Description}}
     203 *
     204 * @since 2.5
     205 *
     206 * @param unknown_type $email {@internal Missing Description}}
     207 * @return unknown {@internal Missing Description}}
     208 */
    121209function get_user_by_email($email) {
    122210        global $wpdb;
    123211
     
    145233endif;
    146234
    147235if ( !function_exists( 'wp_mail' ) ) :
     236/**
     237 * wp_mail() - Function to send mail, similar to PHP's mail
     238 *
     239 * {@internal Missing Long Description}}
     240 *
     241 * @since 1.2.1
     242 *
     243 * @param string $to {@internal Missing Description}}
     244 * @param string $subject {@internal Missing Description}}
     245 * @param string $message {@internal Missing Description}}
     246 * @param string $headers {@internal Missing Description}}
     247 * @return unknown {@internal Missing Description}}
     248 */
    148249function wp_mail( $to, $subject, $message, $headers = '' ) {
    149250        // Compact the input, apply the filters, and extract them back out
    150251        extract( apply_filters( 'wp_mail', compact( 'to', 'subject', 'message', 'headers' ) ) );
     
    291392endif;
    292393
    293394if ( !function_exists('wp_login') ) :
     395/**
     396 * wp_login() - Checks a users login information and logs them in if it checks out
     397 *
     398 * {@internal Missing Long Description}}
     399 *
     400 * @since 1.2.2
     401 *
     402 * @param string $username {@internal Missing Description}}
     403 * @param string $password {@internal Missing Description}}
     404 * @param bool $deprecated {@internal Missing Description}}
     405 * @return unknown {@internal Missing Description}}
     406 */
    294407function wp_login($username, $password, $deprecated = '') {
    295408        global $error;
    296409
     
    325438endif;
    326439
    327440if ( !function_exists('wp_validate_auth_cookie') ) :
     441/**
     442 * wp_validate_auth_cookie() - {@internal Missing Short Description}}
     443 *
     444 * {@internal Missing Long Description}}
     445 *
     446 * @since 2.5
     447 *
     448 * @param unknown_type $cookie {@internal Missing Description}}
     449 * @return unknown {@internal Missing Description}}
     450 */
    328451function wp_validate_auth_cookie($cookie = '') {
    329452        if ( empty($cookie) ) {
    330453                if ( empty($_COOKIE[AUTH_COOKIE]) )
     
    358481endif;
    359482
    360483if ( !function_exists('wp_generate_auth_cookie') ) :
     484/**
     485 * wp_generate_auth_cookie() - {@internal Missing Short Description}}
     486 *
     487 * {@internal Missing Long Description}}
     488 *
     489 * @since 2.5
     490 *
     491 * @param unknown_type $user_id
     492 * @param unknown_type $expiration
     493 * @return unknown
     494 */
    361495function wp_generate_auth_cookie($user_id, $expiration) {
    362496        $user = get_userdata($user_id);
    363497
     
    371505endif;
    372506
    373507if ( !function_exists('wp_set_auth_cookie') ) :
     508/**
     509 * wp_set_auth_cookie() - {@internal Missing Short Description}}
     510 *
     511 * {@internal Missing Long Description}}
     512 *
     513 * @since 2.5
     514 *
     515 * @param unknown_type $user_id {@internal Missing Description}}
     516 * @param unknown_type $remember {@internal Missing Description}}
     517 */
    374518function wp_set_auth_cookie($user_id, $remember = false) {
    375519        if ( $remember ) {
    376520                $expiration = $expire = time() + 1209600;
     
    390534endif;
    391535
    392536if ( !function_exists('wp_clear_auth_cookie') ) :
     537/**
     538 * wp_clear_auth_cookie() - {@internal Missing Short Description}}
     539 *
     540 * {@internal Missing Long Description}}
     541 *
     542 * @since 2.5
     543 */
    393544function wp_clear_auth_cookie() {
    394545        setcookie(AUTH_COOKIE, ' ', time() - 31536000, COOKIEPATH, COOKIE_DOMAIN);
    395546        setcookie(AUTH_COOKIE, ' ', time() - 31536000, SITECOOKIEPATH, COOKIE_DOMAIN);
     
    403554endif;
    404555
    405556if ( !function_exists('is_user_logged_in') ) :
     557/**
     558 * is_user_logged_in() - Checks if the current visitor is a logged in user
     559 *
     560 * {@internal Missing Long Description}}
     561 *
     562 * @since 2.0.0
     563 *
     564 * @return bool {@internal Missing Description}}
     565 */
    406566function is_user_logged_in() {
    407567        $user = wp_get_current_user();
    408568
     
    414574endif;
    415575
    416576if ( !function_exists('auth_redirect') ) :
     577/**
     578 * auth_redirect() - Checks if a user is logged in, if not it redirects them to the login page
     579 *
     580 * {@internal Missing Long Description}}
     581 *
     582 * @since 1.5
     583 */
    417584function auth_redirect() {
    418585        // Checks if a user is logged in, if not redirects them to the login page
    419586        if ( (!empty($_COOKIE[AUTH_COOKIE]) &&
     
    428595endif;
    429596
    430597if ( !function_exists('check_admin_referer') ) :
     598/**
     599 * check_admin_referer() - Makes sure that a user was referred from another admin page, to avoid security exploits
     600 *
     601 * {@internal Missing Long Description}}
     602 *
     603 * @since 1.2.0
     604 *
     605 * @param unknown_type $action {@internal Missing Description}}
     606 */
    431607function check_admin_referer($action = -1) {
    432608        $adminurl = strtolower(get_option('siteurl')).'/wp-admin';
    433609        $referer = strtolower(wp_get_referer());
     
    440616}endif;
    441617
    442618if ( !function_exists('check_ajax_referer') ) :
     619/**
     620 * check_ajax_referer() - {@internal Missing Short Description}}
     621 *
     622 * {@internal Missing Long Description}}
     623 *
     624 * @since 2.0.4
     625 *
     626 * @param unknown_type $action {@internal Missing Description}}
     627 */
    443628function check_ajax_referer( $action = -1 ) {
    444629        $nonce = $_REQUEST['_ajax_nonce'] ? $_REQUEST['_ajax_nonce'] : $_REQUEST['_wpnonce'];
    445630        if ( !wp_verify_nonce( $nonce, $action ) ) {
     
    469654}
    470655endif;
    471656
    472 // Cookie safe redirect.  Works around IIS Set-Cookie bug.
    473 // http://support.microsoft.com/kb/q176113/
    474657if ( !function_exists('wp_redirect') ) :
     658/**
     659 * wp_redirect() - Redirects to another page, with a workaround for the IIS Set-Cookie bug
     660 *
     661 * @link http://support.microsoft.com/kb/q176113/
     662 * @since 1.5.1
     663 *
     664 * @param string $location {@internal Missing Description}}
     665 * @param int $status {@internal Missing Description}}
     666 * @return unknown {@internal Missing Description}}
     667 */
    475668function wp_redirect($location, $status = 302) {
    476669        global $is_IIS;
    477670
     
    494687
    495688if ( !function_exists('wp_sanitize_redirect') ) :
    496689/**
    497  * sanitizes a URL for use in a redirect
     690 * wp_sanitize_redirect() - Sanitizes a URL for use in a redirect
     691 *
     692 * @since 2.3
     693 *
    498694 * @return string redirect-sanitized URL
    499695 **/
    500696function wp_sanitize_redirect($location) {
     
    519715
    520716if ( !function_exists('wp_safe_redirect') ) :
    521717/**
    522  * performs a safe (local) redirect, using wp_redirect()
    523  * @return void
     718 * wp_safe_redirect() - Performs a safe (local) redirect, using wp_redirect()
     719 *
     720 * @since 2.3
     721 *
     722 * @return void Does not return anything
    524723 **/
    525724function wp_safe_redirect($location, $status = 302) {
    526725
     
    544743endif;
    545744
    546745if ( ! function_exists('wp_notify_postauthor') ) :
     746/**
     747 * wp_notify_postauthor() - Notify an author of a comment/trackback/pingback to one of their posts
     748 *
     749 * @since 1.0
     750 *
     751 * @param int $comment_id Comment ID
     752 * @param string $comment_type Optional. The comment type either 'comment' (default), 'trackback', or 'pingback'
     753 * @return bool False if user email does not exist. True on completion.
     754 */
    547755function wp_notify_postauthor($comment_id, $comment_type='') {
    548756        $comment = get_comment($comment_id);
    549757        $post    = get_post($comment->comment_post_ID);
     
    613821}
    614822endif;
    615823
    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
     824if ( !function_exists('wp_notify_moderator') ) :
     825/**
     826 * wp_notify_moderator() - Notifies the moderator of the blog about a new comment that is awaiting approval
     827 *
     828 * @since 1.0
     829 * @uses $wpdb
     830 *
     831 * @param int $comment_id Comment ID
     832 * @return bool Always returns true
    620833 */
    621 if ( !function_exists('wp_notify_moderator') ) :
    622834function wp_notify_moderator($comment_id) {
    623835        global $wpdb;
    624836
     
    658870endif;
    659871
    660872if ( !function_exists('wp_new_user_notification') ) :
     873/**
     874 * wp_new_user_notification() - Notify the blog admin of a new user, normally via email
     875 *
     876 * @since 2.0
     877 *
     878 * @param int $user_id User ID
     879 * @param string $plaintext_pass Optional. The user's plaintext password
     880 */
    661881function wp_new_user_notification($user_id, $plaintext_pass = '') {
    662882        $user = new WP_User($user_id);
    663883
     
    683903endif;
    684904
    685905if ( !function_exists('wp_verify_nonce') ) :
     906/**
     907 * wp_verify_nonce() - Verify that correct nonce was used with time limit
     908 *
     909 * The user is given an amount of time to use the token, so therefore, since
     910 * the UID and $action remain the same, the independent variable is the time.
     911 *
     912 * @since 2.0.4
     913 *
     914 * @param string $nonce Nonce that was used in the form to verify
     915 * @param string|int $action Should give context to what is taking place and be the same when nonce was created.
     916 * @return bool Whether the nonce check passed or failed.
     917 */
    686918function wp_verify_nonce($nonce, $action = -1) {
    687919        $user = wp_get_current_user();
    688920        $uid = (int) $user->id;
     
    697929endif;
    698930
    699931if ( !function_exists('wp_create_nonce') ) :
     932/**
     933 * wp_create_nonce() - Creates a random, one time use token
     934 *
     935 * @since 2.0.4
     936 *
     937 * @param string|int $action Scalar value to add context to the nonce.
     938 * @return string The one use form token
     939 */
    700940function wp_create_nonce($action = -1) {
    701941        $user = wp_get_current_user();
    702942        $uid = (int) $user->id;
     
    708948endif;
    709949
    710950if ( !function_exists('wp_salt') ) :
     951/**
     952 * wp_salt() - Get salt to add to hashes to help prevent attacks
     953 *
     954 * You can set the salt by defining two areas. One is in the database and
     955 * the other is in your wp-config.php file. The database location is defined
     956 * in the option named 'secret', but most likely will not need to be changed.
     957 *
     958 * The second, located in wp-config.php, is a constant named 'SECRET_KEY', but
     959 * is not required. If the constant is not defined then the database constants
     960 * will be used, since they are most likely given to be unique. However, given
     961 * that the salt will be added to the password and can be seen, the constant
     962 * is recommended to be set manually.
     963 *
     964 * <code>
     965 * define('SECRET_KEY', 'mAry1HadA15|\/|b17w55w1t3asSn09w');
     966 * </code>
     967 *
     968 * Attention: Do not use above example!
     969 *
     970 * Salting passwords helps against tools which has stored hashed values
     971 * of common dictionary strings. The added values makes it harder to crack
     972 * if given salt string is not weak.
     973 *
     974 * Salting only helps if the string is not predictable and should be
     975 * made up of various characters. Think of the salt as a password for
     976 * securing your passwords, but common among all of your passwords.
     977 * Therefore the salt should be as long as possible as as difficult as
     978 * possible, because you will not have to remember it.
     979 *
     980 * @since 2.5
     981 *
     982 * @return string Salt value from either 'SECRET_KEY' or 'secret' option
     983 */
    711984function wp_salt() {
    712985
    713986        $secret_key = '';
     
    7291002endif;
    7301003
    7311004if ( !function_exists('wp_hash') ) :
     1005/**
     1006 * wp_hash() - Get hash of given string
     1007 *
     1008 * @since 2.0.4
     1009 * @uses wp_salt() Get WordPress salt
     1010 *
     1011 * @param string $data Plain text to hash
     1012 * @return string Hash of $data
     1013 */
    7321014function wp_hash($data) {
    7331015        $salt = wp_salt();
    7341016
     
    7411023endif;
    7421024
    7431025if ( !function_exists('wp_hash_password') ) :
     1026/**
     1027 * wp_hash_password() - Create a hash (encrypt) of a plain text password
     1028 *
     1029 * For integration with other applications, this function can be
     1030 * overwritten to instead use the other package password checking
     1031 * algorithm.
     1032 *
     1033 * @since 2.5
     1034 * @global object $wp_hasher PHPass object
     1035 * @uses PasswordHash::HashPassword
     1036 *
     1037 * @param string $password Plain text user password to hash
     1038 * @return string The hash string of the password
     1039 */
    7441040function wp_hash_password($password) {
    7451041        global $wp_hasher;
    7461042
     
    7551051endif;
    7561052
    7571053if ( !function_exists('wp_check_password') ) :
     1054/**
     1055 * wp_check_password() - Checks the plaintext password against the encrypted Password
     1056 *
     1057 * Maintains compatibility between old version and the new cookie
     1058 * authentication protocol using PHPass library. The $hash parameter
     1059 * is the encrypted password and the function compares the plain text
     1060 * password when encypted similarly against the already encrypted
     1061 * password to see if they match.
     1062 *
     1063 * For integration with other applications, this function can be
     1064 * overwritten to instead use the other package password checking
     1065 * algorithm.
     1066 *
     1067 * @since 2.5
     1068 * @global object $wp_hasher PHPass object used for checking the password
     1069 *      against the $hash + $password
     1070 * @uses PasswordHash::CheckPassword
     1071 *
     1072 * @param string $password Plaintext user's password
     1073 * @param string $hash Hash of the user's password to check against.
     1074 * @return bool False, if the $password does not match the hashed password
     1075 */
    7581076function wp_check_password($password, $hash) {
    7591077        global $wp_hasher;
    7601078
     
    7751093
    7761094if ( !function_exists('wp_generate_password') ) :
    7771095/**
    778  * Generates a random password drawn from the defined set of characters
    779  * @return string the password
     1096 * wp_generate_password() - Generates a random password drawn from the defined set of characters
     1097 *
     1098 * @since 2.5
     1099 *
     1100 * @return string The random password
    7801101 **/
    7811102function wp_generate_password() {
    7821103        $chars = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
     
    7891110endif;
    7901111
    7911112if ( !function_exists('wp_set_password') ) :
     1113/**
     1114 * wp_set_password() - Updates the user's password with a new encrypted one
     1115 *
     1116 * For integration with other applications, this function can be
     1117 * overwritten to instead use the other package password checking
     1118 * algorithm.
     1119 *
     1120 * @since 2.5
     1121 * @uses $wpdb WordPress database object for queries
     1122 * @uses wp_hash_password() Used to encrypt the user's password before passing to the database
     1123 *
     1124 * @param string $password The plaintext new user password
     1125 * @param int $user_id User ID
     1126 */
    7921127function wp_set_password( $password, $user_id ) {
    7931128        global $wpdb;
    7941129
     
    7991134}
    8001135endif;
    8011136
    802 // Deprecated. Use wp_set_auth_cookie()
    8031137if ( !function_exists('wp_setcookie') ) :
     1138/**
     1139 * wp_setcookie() - Sets a cookie for a user who just logged in
     1140 *
     1141 * @since 1.5
     1142 * @deprecated Use wp_set_auth_cookie()
     1143 * @see wp_set_auth_cookie()
     1144 *
     1145 * @param string  $username The user's username
     1146 * @param string  $password Optional. The user's password
     1147 * @param bool $already_md5 Optional. Whether the password has already been through MD5
     1148 * @param string $home Optional. Will be used instead of COOKIEPATH if set
     1149 * @param string $siteurl Optional. Will be used instead of SITECOOKIEPATH if set
     1150 * @param bool $remember Optional. Remember that the user is logged in
     1151 */
    8041152function wp_setcookie($username, $password = '', $already_md5 = false, $home = '', $siteurl = '', $remember = false) {
    8051153        _deprecated_function( __FUNCTION__, '2.4', 'wp_set_auth_cookie()' );
    8061154        $user = get_userdatabylogin($username);
     
    8081156}
    8091157endif;
    8101158
    811 // Deprecated. Use wp_clear_auth_cookie()
    8121159if ( !function_exists('wp_clearcookie') ) :
     1160/**
     1161 * wp_clearcookie() - Clears the authentication cookie, logging the user out
     1162 *
     1163 * @since 1.5
     1164 * @deprecated Use wp_clear_auth_cookie()
     1165 * @see wp_clear_auth_cookie()
     1166 */
    8131167function wp_clearcookie() {
    8141168        _deprecated_function( __FUNCTION__, '2.4', 'wp_clear_auth_cookie()' );
    8151169        wp_clear_auth_cookie();
    8161170}
    8171171endif;
    8181172
    819 // Deprecated.  No alternative.
    8201173if ( !function_exists('wp_get_cookie_login') ):
     1174/**
     1175 * wp_get_cookie_login() - Gets the user cookie login
     1176 *
     1177 * This function is deprecated and should no longer be extended as it won't
     1178 * be used anywhere in WordPress. Also, plugins shouldn't use it either.
     1179 *
     1180 * @since 2.0.4
     1181 * @deprecated No alternative
     1182 *
     1183 * @return bool Always returns false
     1184 */
    8211185function wp_get_cookie_login() {
    8221186        _deprecated_function( __FUNCTION__, '2.4', '' );
    8231187        return false;