WordPress.org

Make WordPress Core

Ticket #5509: pluggable.phpdoc.r6473.diff

File pluggable.phpdoc.r6473.diff, 15.5 KB (added by darkdragon, 14 years ago)

Incomplete documentation for pluggables.php based off of r6473

  • 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() - {@internal Missing Short Description}}
     12 *
     13 * {@internal Missing Long Description
     14 *              Documentation must describe why set_current_user() would be override
     15 *              instead of wp_set_current_user(). There is a reason and must look for it.
     16 *              If exists on the codex, then link to that instead.
     17 * }}
     18 *
     19 * @since 2.0.1
     20 * @see wp_set_current_user() An alias of wp_set_current_user()
     21 *
     22 * @param int $id
     23 * @param string $name
     24 * @return object returns wp_set_current_user()
     25 */
    726function set_current_user($id, $name = '') {
    827        return wp_set_current_user($id, $name);
    928}
    1029endif;
    1130
    1231if ( !function_exists('wp_set_current_user') ) :
     32/**
     33 * wp_set_current_user() - {@internal Missing Short Description}}
     34 *
     35 * {@internal Missing Long Description
     36 *              Documentation must describe why wp_set_current_user() would be override
     37 *              instead of set_current_user(). There is a reason and must look for it.
     38 *              If exists on the codex, then link to that instead.
     39 * }}
     40 *
     41 * @since
     42 * @global object $current_user The current user object which holds the user data.
     43 *
     44 * @param int $id
     45 * @param string $name
     46 * @return object
     47 */
    1348function wp_set_current_user($id, $name = '') {
    1449        global $current_user;
    1550
     
    2762endif;
    2863
    2964if ( !function_exists('wp_get_current_user') ) :
     65/**
     66 * wp_get_current_user() -
     67 *
     68 * @since
     69 *
     70 * @return unknown
     71 */
    3072function wp_get_current_user() {
    3173        global $current_user;
    3274
     
    3779endif;
    3880
    3981if ( !function_exists('get_currentuserinfo') ) :
     82/**
     83 * get_currentuserinfo() -
     84 *
     85 * @since
     86 *
     87 * @return unknown
     88 */
    4089function get_currentuserinfo() {
    4190        global $current_user;
    4291
     
    56105endif;
    57106
    58107if ( !function_exists('get_userdata') ) :
     108/**
     109 * get_userdata() -
     110 *
     111 * @since
     112 *
     113 * @param unknown_type $user_id
     114 * @return unknown
     115 */
    59116function get_userdata( $user_id ) {
    60117        global $wpdb;
    61118
     
    82139endif;
    83140
    84141if ( !function_exists('update_user_cache') ) :
     142/**
     143 * update_user_cache() -
     144 *
     145 * @since
     146 *
     147 * @return bool Only returns true
     148 */
    85149function update_user_cache() {
    86150        return true;
    87151}
    88152endif;
    89153
    90154if ( !function_exists('get_userdatabylogin') ) :
     155/**
     156 * get_userdatabylogin() -
     157 *
     158 * @since
     159 *
     160 * @param unknown_type $user_login
     161 * @return unknown
     162 */
    91163function get_userdatabylogin($user_login) {
    92164        global $wpdb;
    93165        $user_login = sanitize_user( $user_login );
     
    118190endif;
    119191
    120192if ( !function_exists('get_user_by_email') ) :
     193/**
     194 * get_user_by_email() -
     195 *
     196 * @since
     197 *
     198 * @param unknown_type $email
     199 * @return unknown
     200 */
    121201function get_user_by_email($email) {
    122202        global $wpdb;
    123203
     
    145225endif;
    146226
    147227if ( !function_exists( 'wp_mail' ) ) :
     228/**
     229 * wp_mail() -
     230 *
     231 * @since
     232 *
     233 * @param unknown_type $to
     234 * @param unknown_type $subject
     235 * @param unknown_type $message
     236 * @param unknown_type $headers
     237 * @return unknown
     238 */
    148239function wp_mail( $to, $subject, $message, $headers = '' ) {
    149240        // Compact the input, apply the filters, and extract them back out
    150241        extract( apply_filters( 'wp_mail', compact( 'to', 'subject', 'message', 'headers' ) ) );
     
    291382endif;
    292383
    293384if ( !function_exists('wp_login') ) :
     385/**
     386 * wp_login() -
     387 *
     388 * @since
     389 *
     390 * @param unknown_type $username
     391 * @param unknown_type $password
     392 * @param unknown_type $deprecated
     393 * @return unknown
     394 */
    294395function wp_login($username, $password, $deprecated = false) {
    295396        global $wpdb, $error;
    296397
     
    325426endif;
    326427
    327428if ( !function_exists('wp_validate_auth_cookie') ) :
     429/**
     430 * wp_validate_auth_cookie() -
     431 *
     432 * @since
     433 *
     434 * @param unknown_type $cookie
     435 * @return unknown
     436 */
    328437function wp_validate_auth_cookie($cookie = '') {
    329438        if ( empty($cookie) ) {
    330439                if ( empty($_COOKIE[AUTH_COOKIE]) )
     
    358467endif;
    359468
    360469if ( !function_exists('wp_set_auth_cookie') ) :
     470/**
     471 * wp_set_auth_cookie() -
     472 *
     473 * @since
     474 *
     475 * @param unknown_type $user_id
     476 * @param unknown_type $remember
     477 */
    361478function wp_set_auth_cookie($user_id, $remember = false) {
    362479        $user = get_userdata($user_id);
    363480
     
    380497endif;
    381498
    382499if ( !function_exists('wp_clear_auth_cookie') ) :
     500/**
     501 * wp_clear_auth_cookie() -
     502 *
     503 * @since
     504 *
     505 */
    383506function wp_clear_auth_cookie() {
    384507        setcookie(AUTH_COOKIE, ' ', time() - 31536000, COOKIEPATH, COOKIE_DOMAIN);
    385508        setcookie(AUTH_COOKIE, ' ', time() - 31536000, SITECOOKIEPATH, COOKIE_DOMAIN);
     
    393516endif;
    394517
    395518if ( !function_exists('is_user_logged_in') ) :
     519/**
     520 * is_user_logged_in() -
     521 *
     522 * @since
     523 *
     524 * @return bool
     525 */
    396526function is_user_logged_in() {
    397527        $user = wp_get_current_user();
    398528
     
    404534endif;
    405535
    406536if ( !function_exists('auth_redirect') ) :
     537/**
     538 * auth_redirect() -
     539 *
     540 * @since
     541 *
     542 */
    407543function auth_redirect() {
    408544        // Checks if a user is logged in, if not redirects them to the login page
    409545        if ( (!empty($_COOKIE[AUTH_COOKIE]) &&
     
    418554endif;
    419555
    420556if ( !function_exists('check_admin_referer') ) :
     557/**
     558 * check_admin_referer() -
     559 *
     560 * @param unknown_type $action
     561 */
    421562function check_admin_referer($action = -1) {
    422563        $adminurl = strtolower(get_option('siteurl')).'/wp-admin';
    423564        $referer = strtolower(wp_get_referer());
     
    430571}endif;
    431572
    432573if ( !function_exists('check_ajax_referer') ) :
     574/**
     575 * check_ajax_referer() -
     576 *
     577 * @since
     578 *
     579 * @param unknown_type $action
     580 */
    433581function check_ajax_referer( $action = -1 ) {
    434582        $nonce = $_REQUEST['_ajax_nonce'] ? $_REQUEST['_ajax_nonce'] : $_REQUEST['_wpnonce'];
    435583        if ( !wp_verify_nonce( $nonce, $action ) ) {
     
    462610// Cookie safe redirect.  Works around IIS Set-Cookie bug.
    463611// http://support.microsoft.com/kb/q176113/
    464612if ( !function_exists('wp_redirect') ) :
     613/**
     614 * wp_redirect() -
     615 *
     616 * @since
     617 *
     618 * @param unknown_type $location
     619 * @param unknown_type $status
     620 * @return unknown
     621 */
    465622function wp_redirect($location, $status = 302) {
    466623        global $is_IIS;
    467624
     
    484641
    485642if ( !function_exists('wp_sanitize_redirect') ) :
    486643/**
    487  * sanitizes a URL for use in a redirect
     644 * wp_sanitize_redirect() - Sanitizes a URL for use in a redirect
     645 *
     646 * @since
     647 *
    488648 * @return string redirect-sanitized URL
    489649 **/
    490650function wp_sanitize_redirect($location) {
     
    509669
    510670if ( !function_exists('wp_safe_redirect') ) :
    511671/**
    512  * performs a safe (local) redirect, using wp_redirect()
     672 * wp_safe_redirect() - Performs a safe (local) redirect, using wp_redirect()
     673 *
     674 * @since 2.3
     675 *
    513676 * @return void
    514677 **/
    515678function wp_safe_redirect($location, $status = 302) {
     
    534697endif;
    535698
    536699if ( ! function_exists('wp_notify_postauthor') ) :
     700/**
     701 * wp_notify_postauthor() - Notify an author of a comment/trackback/pingback to one of their posts
     702 *
     703 * @since 1.0.1
     704 *
     705 * @param int $comment_id Comment ID
     706 * @param string $comment_type Optional. The comment type either 'comment' (default), 'trackback', or 'pingback'
     707 * @return bool False if user email does not exist. True on completion.
     708 */
    537709function wp_notify_postauthor($comment_id, $comment_type='') {
    538710        $comment = get_comment($comment_id);
    539711        $post    = get_post($comment->comment_post_ID);
     
    603775}
    604776endif;
    605777
    606 /* wp_notify_moderator
    607    notifies the moderator of the blog (usually the admin)
    608    about a new comment that waits for approval
    609    always returns true
     778if ( !function_exists('wp_notify_moderator') ) :
     779/**
     780 * wp_notify_moderator() - Notifies the moderator of the blog about a new comment that is awaiting approval
     781 *
     782 * @since 1.0.1
     783 * @uses $wpdb
     784 *
     785 * @param int $comment_id Comment ID
     786 * @return bool Always returns true
    610787 */
    611 if ( !function_exists('wp_notify_moderator') ) :
    612788function wp_notify_moderator($comment_id) {
    613789        global $wpdb;
    614790
     
    648824endif;
    649825
    650826if ( !function_exists('wp_new_user_notification') ) :
     827/**
     828 * wp_new_user_notification() - Notify the blog admin of a new user, normally via email
     829 *
     830 * @since 2.0
     831 *
     832 * @param int $user_id User ID
     833 * @param string $plaintext_pass Optional. The user's plaintext password
     834 */
    651835function wp_new_user_notification($user_id, $plaintext_pass = '') {
    652836        $user = new WP_User($user_id);
    653837
     
    673857endif;
    674858
    675859if ( !function_exists('wp_verify_nonce') ) :
     860/**
     861 * wp_verify_nonce() - Verify that correct nonce was used with time limit
     862 *
     863 * The user is given an amount of time to use the token, so therefore, since
     864 * the UID and $action remain the same, the independent variable is the time.
     865 *
     866 * @since 2.0.4
     867 *
     868 * @param string $nonce
     869 * @param string|int $action Should give context to what is taking place and be the same when nonce was created.
     870 * @return bool Whether the nonce check passed or failed.
     871 */
    676872function wp_verify_nonce($nonce, $action = -1) {
    677873        $user = wp_get_current_user();
    678874        $uid = (int) $user->id;
     
    687883endif;
    688884
    689885if ( !function_exists('wp_create_nonce') ) :
     886/**
     887 * wp_create_nonce() - Creates a random, one use token
     888 *
     889 * @since 2.0.4
     890 *
     891 * @param string|int $action Scalar value to add context to the nonce.
     892 * @return string The one use form token
     893 */
    690894function wp_create_nonce($action = -1) {
    691895        $user = wp_get_current_user();
    692896        $uid = (int) $user->id;
     
    698902endif;
    699903
    700904if ( !function_exists('wp_salt') ) :
     905/**
     906 * wp_salt() - Get salt to add to hashes to help prevent attacks
     907 *
     908 * You can set the salt by defining two areas. One is in the database and
     909 * the other is in your wp-config.php file. The database location is defined
     910 * in the option named 'secret', but most likely will not need to be changed.
     911 *
     912 * The second, located in wp-config.php, is a constant named 'SECRET_KEY', but
     913 * is not required. If the constant is not defined then the database constants
     914 * will be used, since they are most likely given to be unique. However, given
     915 * that the salt will be added to the password and can be seen, the constant
     916 * is recommended to be set manually.
     917 *
     918 * <code>
     919 * define('SECRET_KEY', 'mAry1HadA15|\/|b17w55w1t3asSn09w');
     920 * </code>
     921 *
     922 * Attention: Do not use above example!
     923 *
     924 * Salting passwords helps against tools which has stored hashed values
     925 * of common dictionary strings. The added values makes it harder to crack
     926 * if given salt string is not weak.
     927 *
     928 * Salting only helps if the string is not predictable and should be
     929 * made up of various characters. Think of the salt as a password for
     930 * securing your passwords, but common among all of your passwords.
     931 * Therefore the salt should be as long as possible as as difficult as
     932 * possible, because you will not have to remember it.
     933 *
     934 * @since 2.4
     935 *
     936 * @return unknown
     937 */
    701938function wp_salt() {
    702939
    703940        if ( defined('SECRET_KEY') && '' != SECRET_KEY )
     
    714951endif;
    715952
    716953if ( !function_exists('wp_hash') ) :
     954/**
     955 * wp_hash() - Get hash of given string
     956 *
     957 * @since 2.0.4
     958 * @uses wp_salt() Get WordPress salt
     959 *
     960 * @param string $data Plain text to hash
     961 * @return string Hash of $data
     962 */
    717963function wp_hash($data) {
    718964        $salt = wp_salt();
    719965
     
    726972endif;
    727973
    728974if ( !function_exists('wp_hash_password') ) :
     975/**
     976 * wp_hash_password() - Create a hash (encrypt) of a plain text password
     977 *
     978 * For integration with other applications, this function can be
     979 * overwritten to instead use the other package password checking
     980 * algorithm.
     981 *
     982 * @since 2.4
     983 * @global object $wp_hasher PHPass object
     984 * @uses PasswordHash::HashPassword
     985 *
     986 * @param string $password Plain text user password to hash
     987 * @return string The hash string of the password
     988 */
    729989function wp_hash_password($password) {
    730990        global $wp_hasher;
    731991
     
    7401000endif;
    7411001
    7421002if ( !function_exists('wp_check_password') ) :
     1003/**
     1004 * wp_check_password() - Checks the plaintext password against the encrypted Password
     1005 *
     1006 * Maintains compatibility between old version and the new cookie
     1007 * authentication protocol using PHPass library. The $hash parameter
     1008 * is the encrypted password and the function compares the plain text
     1009 * password when encypted similarly against the already encrypted
     1010 * password to see if they match.
     1011 *
     1012 * For integration with other applications, this function can be
     1013 * overwritten to instead use the other package password checking
     1014 * algorithm.
     1015 *
     1016 * @since 2.4
     1017 * @global object $wp_hasher PHPass object used for checking the password
     1018 *      against the $hash + $password
     1019 * @uses PasswordHash::CheckPassword
     1020 *
     1021 * @param string $password
     1022 * @param string $hash
     1023 * @return bool False, if the $password does not match the hashed password
     1024 */
    7431025function wp_check_password($password, $hash) {
    7441026        global $wp_hasher;
    7451027
     
    7601042
    7611043if ( !function_exists('wp_generate_password') ) :
    7621044/**
    763  * Generates a random password drawn from the defined set of characters
    764  * @return string the password
     1045 * wp_generate_password() - Generates a random password drawn from the defined set of characters
     1046 *
     1047 * @since 2.4
     1048 *
     1049 * @return string The random password
    7651050 **/
    7661051function wp_generate_password() {
    7671052        $chars = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
     
    7741059endif;
    7751060
    7761061if ( !function_exists('wp_set_password') ) :
     1062/**
     1063 * wp_set_password() - Updates the user's password with a new encrypted one
     1064 *
     1065 * For integration with other applications, this function can be
     1066 * overwritten to instead use the other package password checking
     1067 * algorithm.
     1068 *
     1069 * @since 2.4
     1070 * @uses $wpdb WordPress database object for queries
     1071 * @uses wp_hash_password() Used to encrypt the user's password before passing to the database
     1072 *
     1073 * @param string $password The plaintext new user password
     1074 * @param int $user_id User ID
     1075 */
    7771076function wp_set_password( $password, $user_id ) {
    7781077        global $wpdb;
    7791078
     
    7841083}
    7851084endif;
    7861085
    787 // Deprecated. Use wp_set_auth_cookie()
    7881086if ( !function_exists('wp_setcookie') ) :
     1087/**
     1088 * wp_setcookie() - Sets a cookie for a user who just logged in
     1089 *
     1090 * @since 1.5
     1091 * @deprecated Use wp_set_auth_cookie()
     1092 * @see wp_set_auth_cookie()
     1093 *
     1094 * @param string  $username The user's username
     1095 * @param string  $password Optional. The user's password
     1096 * @param bool $already_md5 Optional. Whether the password has already been through MD5
     1097 * @param string $home Optional. Will be used instead of COOKIEPATH if set
     1098 * @param string $siteurl Optional. Will be used instead of SITECOOKIEPATH if set
     1099 * @param bool $remember Optional. Remember that the user is logged in
     1100 */
    7891101function wp_setcookie($username, $password = '', $already_md5 = false, $home = '', $siteurl = '', $remember = false) {
    7901102        $user = get_userdatabylogin($username);
    7911103        wp_set_auth_cookie($user->ID, $remember);
    7921104}
    7931105endif;
    7941106
    795 // Deprecated. Use wp_clear_auth_cookie()
    7961107if ( !function_exists('wp_clearcookie') ) :
     1108/**
     1109 * wp_clearcookie() - Clears the authentication cookie, logging the user out
     1110 *
     1111 * @since 1.5
     1112 * @deprecated Use wp_clear_auth_cookie()
     1113 * @see wp_clear_auth_cookie()
     1114 */
    7971115function wp_clearcookie() {
    7981116        wp_clear_auth_cookie();
    7991117}
    8001118endif;
    8011119
    802 // Deprecated.  No alternative.
    8031120if ( !function_exists('wp_get_cookie_login') ):
     1121/**
     1122 * wp_get_cookie_login() - {@internal Missing Short Description}}
     1123 *
     1124 * @since 2.0.4
     1125 * @deprecated No alternative
     1126 *
     1127 * @return bool Always returns false
     1128 */
    8041129function wp_get_cookie_login() {
    8051130        return false;
    8061131}