Ticket #5509: pluggable.phpdoc.r6582.diff
| File pluggable.phpdoc.r6582.diff, 18.8 kB (added by darkdragon, 8 months ago) |
|---|
-
pluggable.php
old new 1 1 <?php 2 /** 3 * These functions can be replaced via plugins. They are loaded after 4 * plugins are loaded. 5 * 6 * @package WordPress 7 */ 2 8 3 /* These functions can be replaced via plugins. They are loaded after4 plugins are loaded. */5 6 9 if ( !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 */ 7 22 function set_current_user($id, $name = '') { 8 23 return wp_set_current_user($id, $name); 9 24 } 10 25 endif; 11 26 12 27 if ( !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 */ 13 44 function wp_set_current_user($id, $name = '') { 14 45 global $current_user; 15 46 … … 27 58 endif; 28 59 29 60 if ( !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 */ 30 70 function wp_get_current_user() { 31 71 global $current_user; 32 72 … … 37 77 endif; 38 78 39 79 if ( !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 */ 40 89 function get_currentuserinfo() { 41 90 global $current_user; 42 91 … … 56 105 endif; 57 106 58 107 if ( !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 */ 59 118 function get_userdata( $user_id ) { 60 119 global $wpdb; 61 120 … … 82 141 endif; 83 142 84 143 if ( !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 */ 85 153 function update_user_cache() { 86 154 return true; 87 155 } 88 156 endif; 89 157 90 158 if ( !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 */ 91 169 function get_userdatabylogin($user_login) { 92 170 global $wpdb; 93 171 $user_login = sanitize_user( $user_login ); … … 118 196 endif; 119 197 120 198 if ( !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 */ 121 209 function get_user_by_email($email) { 122 210 global $wpdb; 123 211 … … 145 233 endif; 146 234 147 235 if ( !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 */ 148 249 function wp_mail( $to, $subject, $message, $headers = '' ) { 149 250 // Compact the input, apply the filters, and extract them back out 150 251 extract( apply_filters( 'wp_mail', compact( 'to', 'subject', 'message', 'headers' ) ) ); … … 291 392 endif; 292 393 293 394 if ( !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 */ 294 407 function wp_login($username, $password, $deprecated = '') { 295 408 global $error; 296 409 … … 325 438 endif; 326 439 327 440 if ( !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 */ 328 451 function wp_validate_auth_cookie($cookie = '') { 329 452 if ( empty($cookie) ) { 330 453 if ( empty($_COOKIE[AUTH_COOKIE]) ) … … 358 481 endif; 359 482 360 483 if ( !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 */ 361 495 function wp_generate_auth_cookie($user_id, $expiration) { 362 496 $user = get_userdata($user_id); 363 497 … … 371 505 endif; 372 506 373 507 if ( !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 */ 374 518 function wp_set_auth_cookie($user_id, $remember = false) { 375 519 if ( $remember ) { 376 520 $expiration = $expire = time() + 1209600; … … 390 534 endif; 391 535 392 536 if ( !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 */ 393 544 function wp_clear_auth_cookie() { 394 545 setcookie(AUTH_COOKIE, ' ', time() - 31536000, COOKIEPATH, COOKIE_DOMAIN); 395 546 setcookie(AUTH_COOKIE, ' ', time() - 31536000, SITECOOKIEPATH, COOKIE_DOMAIN); … … 403 554 endif; 404 555 405 556 if ( !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 */ 406 566 function is_user_logged_in() { 407 567 $user = wp_get_current_user(); 408 568 … … 414 574 endif; 415 575 416 576 if ( !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 */ 417 584 function auth_redirect() { 418 585 // Checks if a user is logged in, if not redirects them to the login page 419 586 if ( (!empty($_COOKIE[AUTH_COOKIE]) && … … 428 595 endif; 429 596 430 597 if ( !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 */ 431 607 function check_admin_referer($action = -1) { 432 608 $adminurl = strtolower(get_option('siteurl')).'/wp-admin'; 433 609 $referer = strtolower(wp_get_referer()); … … 440 616 }endif; 441 617 442 618 if ( !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 */ 443 628 function check_ajax_referer( $action = -1 ) { 444 629 $nonce = $_REQUEST['_ajax_nonce'] ? $_REQUEST['_ajax_nonce'] : $_REQUEST['_wpnonce']; 445 630 if ( !wp_verify_nonce( $nonce, $action ) ) { … … 469 654 } 470 655 endif; 471 656 472 // Cookie safe redirect. Works around IIS Set-Cookie bug.473 // http://support.microsoft.com/kb/q176113/474 657 if ( !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 */ 475 668 function wp_redirect($location, $status = 302) { 476 669 global $is_IIS; 477 670 … … 494 687 495 688 if ( !function_exists('wp_sanitize_redirect') ) : 496 689 /** 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 * 498 694 * @return string redirect-sanitized URL 499 695 **/ 500 696 function wp_sanitize_redirect($location) { … … 519 715 520 716 if ( !function_exists('wp_safe_redirect') ) : 521 717 /** 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 524 723 **/ 525 724 function wp_safe_redirect($location, $status = 302) { 526 725 … … 544 743 endif; 545 744 546 745 if ( ! 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 */ 547 755 function wp_notify_postauthor($comment_id, $comment_type='') { 548 756 $comment = get_comment($comment_id); 549 757 $post = get_post($comment->comment_post_ID); … … 613 821 } 614 822 endif; 615 823 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 824 if ( !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 620 833 */ 621 if ( !function_exists('wp_notify_moderator') ) :622 834 function wp_notify_moderator($comment_id) { 623 835 global $wpdb; 624 836 … … 658 870 endif; 659 871 660 872 if ( !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 */ 661 881 function wp_new_user_notification($user_id, $plaintext_pass = '') { 662 882 $user = new WP_User($user_id); 663 883 … … 683 903 endif; 684 904 685 905 if ( !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 */ 686 918 function wp_verify_nonce($nonce, $action = -1) { 687 919 $user = wp_get_current_user(); 688 920 $uid = (int) $user->id; … … 697 929 endif; 698 930 699 931 if ( !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 */ 700 940 function wp_create_nonce($action = -1) { 701 941 $user = wp_get_current_user(); 702 942 $uid = (int) $user->id; … … 708 948 endif; 709 949 710 950 if ( !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 */ 711 984 function wp_salt() { 712 985 713 986 $secret_key = ''; … … 729 1002 endif; 730 1003 731 1004 if ( !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 */ 732 1014 function wp_hash($data) { 733 1015 $salt = wp_salt(); 734 1016 … … 741 1023 endif; 742 1024 743 1025 if ( !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 */ 744 1040 function wp_hash_password($password) { 745 1041 global $wp_hasher; 746 1042 … … 755 1051 endif; 756 1052 757 1053 if ( !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 */ 758 1076 function wp_check_password($password, $hash) { 759 1077 global $wp_hasher; 760 1078 … … 775 1093 776 1094 if ( !function_exists('wp_generate_password') ) : 777 1095 /** 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 780 1101 **/ 781 1102 function wp_generate_password() { 782 1103 $chars = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"; … … 789 1110 endif; 790 1111 791 1112 if ( !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 */ 792 1127 function wp_set_password( $password, $user_id ) { 793 1128 global $wpdb; 794 1129 … … 799 1134 } 800 1135 endif; 801 1136 802 // Deprecated. Use wp_set_auth_cookie()803 1137 if ( !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 */ 804 1152 function wp_setcookie($username, $password = '', $already_md5 = false, $home = '', $siteurl = '', $remember = false) { 805 1153 _deprecated_function( __FUNCTION__, '2.4', 'wp_set_auth_cookie()' ); 806 1154 $user = get_userdatabylogin($username); … … 808 1156 } 809 1157 endif; 810 1158 811 // Deprecated. Use wp_clear_auth_cookie()812 1159 if ( !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 */ 813 1167 function wp_clearcookie() { 814 1168 _deprecated_function( __FUNCTION__, '2.4', 'wp_clear_auth_cookie()' ); 815 1169 wp_clear_auth_cookie(); 816 1170 } 817 1171 endif; 818 1172 819 // Deprecated. No alternative.820 1173 if ( !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 */ 821 1185 function wp_get_cookie_login() { 822 1186 _deprecated_function( __FUNCTION__, '2.4', '' ); 823 1187 return false;
