| [ Index ] |
PHP Cross Reference of WordPress |
[Summary view] [Print] [Text view]
1 <?php 2 /** 3 * Core User API 4 * 5 * @package WordPress 6 * @subpackage Users 7 */ 8 9 /** 10 * Authenticates and logs a user in with 'remember' capability. 11 * 12 * The credentials is an array that has 'user_login', 'user_password', and 13 * 'remember' indices. If the credentials is not given, then the log in form 14 * will be assumed and used if set. 15 * 16 * The various authentication cookies will be set by this function and will be 17 * set for a longer period depending on if the 'remember' credential is set to 18 * true. 19 * 20 * Note: wp_signon() doesn't handle setting the current user. This means that if the 21 * function is called before the {@see 'init'} hook is fired, is_user_logged_in() will 22 * evaluate as false until that point. If is_user_logged_in() is needed in conjunction 23 * with wp_signon(), wp_set_current_user() should be called explicitly. 24 * 25 * @since 2.5.0 26 * 27 * @global string $auth_secure_cookie 28 * 29 * @param array $credentials Optional. User info in order to sign on. 30 * @param string|bool $secure_cookie Optional. Whether to use secure cookie. 31 * @return WP_User|WP_Error WP_User on success, WP_Error on failure. 32 */ 33 function wp_signon( $credentials = array(), $secure_cookie = '' ) { 34 if ( empty( $credentials ) ) { 35 $credentials = array(); // Back-compat for plugins passing an empty string. 36 37 if ( ! empty( $_POST['log'] ) ) { 38 $credentials['user_login'] = $_POST['log']; 39 } 40 if ( ! empty( $_POST['pwd'] ) ) { 41 $credentials['user_password'] = $_POST['pwd']; 42 } 43 if ( ! empty( $_POST['rememberme'] ) ) { 44 $credentials['remember'] = $_POST['rememberme']; 45 } 46 } 47 48 if ( ! empty( $credentials['remember'] ) ) { 49 $credentials['remember'] = true; 50 } else { 51 $credentials['remember'] = false; 52 } 53 54 /** 55 * Fires before the user is authenticated. 56 * 57 * The variables passed to the callbacks are passed by reference, 58 * and can be modified by callback functions. 59 * 60 * @since 1.5.1 61 * 62 * @todo Decide whether to deprecate the wp_authenticate action. 63 * 64 * @param string $user_login Username (passed by reference). 65 * @param string $user_password User password (passed by reference). 66 */ 67 do_action_ref_array( 'wp_authenticate', array( &$credentials['user_login'], &$credentials['user_password'] ) ); 68 69 if ( '' === $secure_cookie ) { 70 $secure_cookie = is_ssl(); 71 } 72 73 /** 74 * Filters whether to use a secure sign-on cookie. 75 * 76 * @since 3.1.0 77 * 78 * @param bool $secure_cookie Whether to use a secure sign-on cookie. 79 * @param array $credentials { 80 * Array of entered sign-on data. 81 * 82 * @type string $user_login Username. 83 * @type string $user_password Password entered. 84 * @type bool $remember Whether to 'remember' the user. Increases the time 85 * that the cookie will be kept. Default false. 86 * } 87 */ 88 $secure_cookie = apply_filters( 'secure_signon_cookie', $secure_cookie, $credentials ); 89 90 global $auth_secure_cookie; // XXX ugly hack to pass this to wp_authenticate_cookie 91 $auth_secure_cookie = $secure_cookie; 92 93 add_filter( 'authenticate', 'wp_authenticate_cookie', 30, 3 ); 94 95 $user = wp_authenticate( $credentials['user_login'], $credentials['user_password'] ); 96 97 if ( is_wp_error( $user ) ) { 98 return $user; 99 } 100 101 wp_set_auth_cookie( $user->ID, $credentials['remember'], $secure_cookie ); 102 /** 103 * Fires after the user has successfully logged in. 104 * 105 * @since 1.5.0 106 * 107 * @param string $user_login Username. 108 * @param WP_User $user WP_User object of the logged-in user. 109 */ 110 do_action( 'wp_login', $user->user_login, $user ); 111 return $user; 112 } 113 114 /** 115 * Authenticate a user, confirming the username and password are valid. 116 * 117 * @since 2.8.0 118 * 119 * @param WP_User|WP_Error|null $user WP_User or WP_Error object from a previous callback. Default null. 120 * @param string $username Username for authentication. 121 * @param string $password Password for authentication. 122 * @return WP_User|WP_Error WP_User on success, WP_Error on failure. 123 */ 124 function wp_authenticate_username_password( $user, $username, $password ) { 125 if ( $user instanceof WP_User ) { 126 return $user; 127 } 128 129 if ( empty( $username ) || empty( $password ) ) { 130 if ( is_wp_error( $user ) ) { 131 return $user; 132 } 133 134 $error = new WP_Error(); 135 136 if ( empty( $username ) ) { 137 $error->add( 'empty_username', __( '<strong>ERROR</strong>: The username field is empty.' ) ); 138 } 139 140 if ( empty( $password ) ) { 141 $error->add( 'empty_password', __( '<strong>ERROR</strong>: The password field is empty.' ) ); 142 } 143 144 return $error; 145 } 146 147 $user = get_user_by( 'login', $username ); 148 149 if ( ! $user ) { 150 return new WP_Error( 151 'invalid_username', 152 __( '<strong>ERROR</strong>: Invalid username.' ) . 153 ' <a href="' . wp_lostpassword_url() . '">' . 154 __( 'Lost your password?' ) . 155 '</a>' 156 ); 157 } 158 159 /** 160 * Filters whether the given user can be authenticated with the provided $password. 161 * 162 * @since 2.5.0 163 * 164 * @param WP_User|WP_Error $user WP_User or WP_Error object if a previous 165 * callback failed authentication. 166 * @param string $password Password to check against the user. 167 */ 168 $user = apply_filters( 'wp_authenticate_user', $user, $password ); 169 if ( is_wp_error( $user ) ) { 170 return $user; 171 } 172 173 if ( ! wp_check_password( $password, $user->user_pass, $user->ID ) ) { 174 return new WP_Error( 175 'incorrect_password', 176 sprintf( 177 /* translators: %s: user name */ 178 __( '<strong>ERROR</strong>: The password you entered for the username %s is incorrect.' ), 179 '<strong>' . $username . '</strong>' 180 ) . 181 ' <a href="' . wp_lostpassword_url() . '">' . 182 __( 'Lost your password?' ) . 183 '</a>' 184 ); 185 } 186 187 return $user; 188 } 189 190 /** 191 * Authenticates a user using the email and password. 192 * 193 * @since 4.5.0 194 * 195 * @param WP_User|WP_Error|null $user WP_User or WP_Error object if a previous 196 * callback failed authentication. 197 * @param string $email Email address for authentication. 198 * @param string $password Password for authentication. 199 * @return WP_User|WP_Error WP_User on success, WP_Error on failure. 200 */ 201 function wp_authenticate_email_password( $user, $email, $password ) { 202 if ( $user instanceof WP_User ) { 203 return $user; 204 } 205 206 if ( empty( $email ) || empty( $password ) ) { 207 if ( is_wp_error( $user ) ) { 208 return $user; 209 } 210 211 $error = new WP_Error(); 212 213 if ( empty( $email ) ) { 214 $error->add( 'empty_username', __( '<strong>ERROR</strong>: The email field is empty.' ) ); // Uses 'empty_username' for back-compat with wp_signon() 215 } 216 217 if ( empty( $password ) ) { 218 $error->add( 'empty_password', __( '<strong>ERROR</strong>: The password field is empty.' ) ); 219 } 220 221 return $error; 222 } 223 224 if ( ! is_email( $email ) ) { 225 return $user; 226 } 227 228 $user = get_user_by( 'email', $email ); 229 230 if ( ! $user ) { 231 return new WP_Error( 232 'invalid_email', 233 __( '<strong>ERROR</strong>: Invalid email address.' ) . 234 ' <a href="' . wp_lostpassword_url() . '">' . 235 __( 'Lost your password?' ) . 236 '</a>' 237 ); 238 } 239 240 /** This filter is documented in wp-includes/user.php */ 241 $user = apply_filters( 'wp_authenticate_user', $user, $password ); 242 243 if ( is_wp_error( $user ) ) { 244 return $user; 245 } 246 247 if ( ! wp_check_password( $password, $user->user_pass, $user->ID ) ) { 248 return new WP_Error( 249 'incorrect_password', 250 sprintf( 251 /* translators: %s: email address */ 252 __( '<strong>ERROR</strong>: The password you entered for the email address %s is incorrect.' ), 253 '<strong>' . $email . '</strong>' 254 ) . 255 ' <a href="' . wp_lostpassword_url() . '">' . 256 __( 'Lost your password?' ) . 257 '</a>' 258 ); 259 } 260 261 return $user; 262 } 263 264 /** 265 * Authenticate the user using the WordPress auth cookie. 266 * 267 * @since 2.8.0 268 * 269 * @global string $auth_secure_cookie 270 * 271 * @param WP_User|WP_Error|null $user WP_User or WP_Error object from a previous callback. Default null. 272 * @param string $username Username. If not empty, cancels the cookie authentication. 273 * @param string $password Password. If not empty, cancels the cookie authentication. 274 * @return WP_User|WP_Error WP_User on success, WP_Error on failure. 275 */ 276 function wp_authenticate_cookie( $user, $username, $password ) { 277 if ( $user instanceof WP_User ) { 278 return $user; 279 } 280 281 if ( empty( $username ) && empty( $password ) ) { 282 $user_id = wp_validate_auth_cookie(); 283 if ( $user_id ) { 284 return new WP_User( $user_id ); 285 } 286 287 global $auth_secure_cookie; 288 289 if ( $auth_secure_cookie ) { 290 $auth_cookie = SECURE_AUTH_COOKIE; 291 } else { 292 $auth_cookie = AUTH_COOKIE; 293 } 294 295 if ( ! empty( $_COOKIE[ $auth_cookie ] ) ) { 296 return new WP_Error( 'expired_session', __( 'Please log in again.' ) ); 297 } 298 299 // If the cookie is not set, be silent. 300 } 301 302 return $user; 303 } 304 305 /** 306 * For Multisite blogs, check if the authenticated user has been marked as a 307 * spammer, or if the user's primary blog has been marked as spam. 308 * 309 * @since 3.7.0 310 * 311 * @param WP_User|WP_Error|null $user WP_User or WP_Error object from a previous callback. Default null. 312 * @return WP_User|WP_Error WP_User on success, WP_Error if the user is considered a spammer. 313 */ 314 function wp_authenticate_spam_check( $user ) { 315 if ( $user instanceof WP_User && is_multisite() ) { 316 /** 317 * Filters whether the user has been marked as a spammer. 318 * 319 * @since 3.7.0 320 * 321 * @param bool $spammed Whether the user is considered a spammer. 322 * @param WP_User $user User to check against. 323 */ 324 $spammed = apply_filters( 'check_is_user_spammed', is_user_spammy( $user ), $user ); 325 326 if ( $spammed ) { 327 return new WP_Error( 'spammer_account', __( '<strong>ERROR</strong>: Your account has been marked as a spammer.' ) ); 328 } 329 } 330 return $user; 331 } 332 333 /** 334 * Validates the logged-in cookie. 335 * 336 * Checks the logged-in cookie if the previous auth cookie could not be 337 * validated and parsed. 338 * 339 * This is a callback for the {@see 'determine_current_user'} filter, rather than API. 340 * 341 * @since 3.9.0 342 * 343 * @param int|bool $user_id The user ID (or false) as received from the 344 * determine_current_user filter. 345 * @return int|false User ID if validated, false otherwise. If a user ID from 346 * an earlier filter callback is received, that value is returned. 347 */ 348 function wp_validate_logged_in_cookie( $user_id ) { 349 if ( $user_id ) { 350 return $user_id; 351 } 352 353 if ( is_blog_admin() || is_network_admin() || empty( $_COOKIE[ LOGGED_IN_COOKIE ] ) ) { 354 return false; 355 } 356 357 return wp_validate_auth_cookie( $_COOKIE[ LOGGED_IN_COOKIE ], 'logged_in' ); 358 } 359 360 /** 361 * Number of posts user has written. 362 * 363 * @since 3.0.0 364 * @since 4.1.0 Added `$post_type` argument. 365 * @since 4.3.0 Added `$public_only` argument. Added the ability to pass an array 366 * of post types to `$post_type`. 367 * 368 * @global wpdb $wpdb WordPress database abstraction object. 369 * 370 * @param int $userid User ID. 371 * @param array|string $post_type Optional. Single post type or array of post types to count the number of posts for. Default 'post'. 372 * @param bool $public_only Optional. Whether to only return counts for public posts. Default false. 373 * @return string Number of posts the user has written in this post type. 374 */ 375 function count_user_posts( $userid, $post_type = 'post', $public_only = false ) { 376 global $wpdb; 377 378 $where = get_posts_by_author_sql( $post_type, true, $userid, $public_only ); 379 380 $count = $wpdb->get_var( "SELECT COUNT(*) FROM $wpdb->posts $where" ); 381 382 /** 383 * Filters the number of posts a user has written. 384 * 385 * @since 2.7.0 386 * @since 4.1.0 Added `$post_type` argument. 387 * @since 4.3.1 Added `$public_only` argument. 388 * 389 * @param int $count The user's post count. 390 * @param int $userid User ID. 391 * @param string|array $post_type Single post type or array of post types to count the number of posts for. 392 * @param bool $public_only Whether to limit counted posts to public posts. 393 */ 394 return apply_filters( 'get_usernumposts', $count, $userid, $post_type, $public_only ); 395 } 396 397 /** 398 * Number of posts written by a list of users. 399 * 400 * @since 3.0.0 401 * 402 * @global wpdb $wpdb WordPress database abstraction object. 403 * 404 * @param array $users Array of user IDs. 405 * @param string|array $post_type Optional. Single post type or array of post types to check. Defaults to 'post'. 406 * @param bool $public_only Optional. Only return counts for public posts. Defaults to false. 407 * @return array Amount of posts each user has written. 408 */ 409 function count_many_users_posts( $users, $post_type = 'post', $public_only = false ) { 410 global $wpdb; 411 412 $count = array(); 413 if ( empty( $users ) || ! is_array( $users ) ) { 414 return $count; 415 } 416 417 $userlist = implode( ',', array_map( 'absint', $users ) ); 418 $where = get_posts_by_author_sql( $post_type, true, null, $public_only ); 419 420 $result = $wpdb->get_results( "SELECT post_author, COUNT(*) FROM $wpdb->posts $where AND post_author IN ($userlist) GROUP BY post_author", ARRAY_N ); 421 foreach ( $result as $row ) { 422 $count[ $row[0] ] = $row[1]; 423 } 424 425 foreach ( $users as $id ) { 426 if ( ! isset( $count[ $id ] ) ) { 427 $count[ $id ] = 0; 428 } 429 } 430 431 return $count; 432 } 433 434 // 435 // User option functions 436 // 437 438 /** 439 * Get the current user's ID 440 * 441 * @since MU (3.0.0) 442 * 443 * @return int The current user's ID, or 0 if no user is logged in. 444 */ 445 function get_current_user_id() { 446 if ( ! function_exists( 'wp_get_current_user' ) ) { 447 return 0; 448 } 449 $user = wp_get_current_user(); 450 return ( isset( $user->ID ) ? (int) $user->ID : 0 ); 451 } 452 453 /** 454 * Retrieve user option that can be either per Site or per Network. 455 * 456 * If the user ID is not given, then the current user will be used instead. If 457 * the user ID is given, then the user data will be retrieved. The filter for 458 * the result, will also pass the original option name and finally the user data 459 * object as the third parameter. 460 * 461 * The option will first check for the per site name and then the per Network name. 462 * 463 * @since 2.0.0 464 * 465 * @global wpdb $wpdb WordPress database abstraction object. 466 * 467 * @param string $option User option name. 468 * @param int $user Optional. User ID. 469 * @param string $deprecated Use get_option() to check for an option in the options table. 470 * @return mixed User option value on success, false on failure. 471 */ 472 function get_user_option( $option, $user = 0, $deprecated = '' ) { 473 global $wpdb; 474 475 if ( ! empty( $deprecated ) ) { 476 _deprecated_argument( __FUNCTION__, '3.0.0' ); 477 } 478 479 if ( empty( $user ) ) { 480 $user = get_current_user_id(); 481 } 482 483 $user = get_userdata( $user ); 484 if ( ! $user ) { 485 return false; 486 } 487 488 $prefix = $wpdb->get_blog_prefix(); 489 if ( $user->has_prop( $prefix . $option ) ) { // Blog specific 490 $result = $user->get( $prefix . $option ); 491 } elseif ( $user->has_prop( $option ) ) { // User specific and cross-blog 492 $result = $user->get( $option ); 493 } else { 494 $result = false; 495 } 496 497 /** 498 * Filters a specific user option value. 499 * 500 * The dynamic portion of the hook name, `$option`, refers to the user option name. 501 * 502 * @since 2.5.0 503 * 504 * @param mixed $result Value for the user's option. 505 * @param string $option Name of the option being retrieved. 506 * @param WP_User $user WP_User object of the user whose option is being retrieved. 507 */ 508 return apply_filters( "get_user_option_{$option}", $result, $option, $user ); 509 } 510 511 /** 512 * Update user option with global blog capability. 513 * 514 * User options are just like user metadata except that they have support for 515 * global blog options. If the 'global' parameter is false, which it is by default 516 * it will prepend the WordPress table prefix to the option name. 517 * 518 * Deletes the user option if $newvalue is empty. 519 * 520 * @since 2.0.0 521 * 522 * @global wpdb $wpdb WordPress database abstraction object. 523 * 524 * @param int $user_id User ID. 525 * @param string $option_name User option name. 526 * @param mixed $newvalue User option value. 527 * @param bool $global Optional. Whether option name is global or blog specific. 528 * Default false (blog specific). 529 * @return int|bool User meta ID if the option didn't exist, true on successful update, 530 * false on failure. 531 */ 532 function update_user_option( $user_id, $option_name, $newvalue, $global = false ) { 533 global $wpdb; 534 535 if ( ! $global ) { 536 $option_name = $wpdb->get_blog_prefix() . $option_name; 537 } 538 539 return update_user_meta( $user_id, $option_name, $newvalue ); 540 } 541 542 /** 543 * Delete user option with global blog capability. 544 * 545 * User options are just like user metadata except that they have support for 546 * global blog options. If the 'global' parameter is false, which it is by default 547 * it will prepend the WordPress table prefix to the option name. 548 * 549 * @since 3.0.0 550 * 551 * @global wpdb $wpdb WordPress database abstraction object. 552 * 553 * @param int $user_id User ID 554 * @param string $option_name User option name. 555 * @param bool $global Optional. Whether option name is global or blog specific. 556 * Default false (blog specific). 557 * @return bool True on success, false on failure. 558 */ 559 function delete_user_option( $user_id, $option_name, $global = false ) { 560 global $wpdb; 561 562 if ( ! $global ) { 563 $option_name = $wpdb->get_blog_prefix() . $option_name; 564 } 565 return delete_user_meta( $user_id, $option_name ); 566 } 567 568 /** 569 * Retrieve list of users matching criteria. 570 * 571 * @since 3.1.0 572 * 573 * @see WP_User_Query 574 * 575 * @param array $args Optional. Arguments to retrieve users. See WP_User_Query::prepare_query(). 576 * for more information on accepted arguments. 577 * @return array List of users. 578 */ 579 function get_users( $args = array() ) { 580 581 $args = wp_parse_args( $args ); 582 $args['count_total'] = false; 583 584 $user_search = new WP_User_Query( $args ); 585 586 return (array) $user_search->get_results(); 587 } 588 589 /** 590 * Get the sites a user belongs to. 591 * 592 * @since 3.0.0 593 * @since 4.7.0 Converted to use `get_sites()`. 594 * 595 * @global wpdb $wpdb WordPress database abstraction object. 596 * 597 * @param int $user_id User ID 598 * @param bool $all Whether to retrieve all sites, or only sites that are not 599 * marked as deleted, archived, or spam. 600 * @return array A list of the user's sites. An empty array if the user doesn't exist 601 * or belongs to no sites. 602 */ 603 function get_blogs_of_user( $user_id, $all = false ) { 604 global $wpdb; 605 606 $user_id = (int) $user_id; 607 608 // Logged out users can't have sites 609 if ( empty( $user_id ) ) { 610 return array(); 611 } 612 613 /** 614 * Filters the list of a user's sites before it is populated. 615 * 616 * Passing a non-null value to the filter will effectively short circuit 617 * get_blogs_of_user(), returning that value instead. 618 * 619 * @since 4.6.0 620 * 621 * @param null|array $sites An array of site objects of which the user is a member. 622 * @param int $user_id User ID. 623 * @param bool $all Whether the returned array should contain all sites, including 624 * those marked 'deleted', 'archived', or 'spam'. Default false. 625 */ 626 $sites = apply_filters( 'pre_get_blogs_of_user', null, $user_id, $all ); 627 628 if ( null !== $sites ) { 629 return $sites; 630 } 631 632 $keys = get_user_meta( $user_id ); 633 if ( empty( $keys ) ) { 634 return array(); 635 } 636 637 if ( ! is_multisite() ) { 638 $site_id = get_current_blog_id(); 639 $sites = array( $site_id => new stdClass ); 640 $sites[ $site_id ]->userblog_id = $site_id; 641 $sites[ $site_id ]->blogname = get_option( 'blogname' ); 642 $sites[ $site_id ]->domain = ''; 643 $sites[ $site_id ]->path = ''; 644 $sites[ $site_id ]->site_id = 1; 645 $sites[ $site_id ]->siteurl = get_option( 'siteurl' ); 646 $sites[ $site_id ]->archived = 0; 647 $sites[ $site_id ]->spam = 0; 648 $sites[ $site_id ]->deleted = 0; 649 return $sites; 650 } 651 652 $site_ids = array(); 653 654 if ( isset( $keys[ $wpdb->base_prefix . 'capabilities' ] ) && defined( 'MULTISITE' ) ) { 655 $site_ids[] = 1; 656 unset( $keys[ $wpdb->base_prefix . 'capabilities' ] ); 657 } 658 659 $keys = array_keys( $keys ); 660 661 foreach ( $keys as $key ) { 662 if ( 'capabilities' !== substr( $key, -12 ) ) { 663 continue; 664 } 665 if ( $wpdb->base_prefix && 0 !== strpos( $key, $wpdb->base_prefix ) ) { 666 continue; 667 } 668 $site_id = str_replace( array( $wpdb->base_prefix, '_capabilities' ), '', $key ); 669 if ( ! is_numeric( $site_id ) ) { 670 continue; 671 } 672 673 $site_ids[] = (int) $site_id; 674 } 675 676 $sites = array(); 677 678 if ( ! empty( $site_ids ) ) { 679 $args = array( 680 'number' => '', 681 'site__in' => $site_ids, 682 'update_site_meta_cache' => false, 683 ); 684 if ( ! $all ) { 685 $args['archived'] = 0; 686 $args['spam'] = 0; 687 $args['deleted'] = 0; 688 } 689 690 $_sites = get_sites( $args ); 691 692 foreach ( $_sites as $site ) { 693 $sites[ $site->id ] = (object) array( 694 'userblog_id' => $site->id, 695 'blogname' => $site->blogname, 696 'domain' => $site->domain, 697 'path' => $site->path, 698 'site_id' => $site->network_id, 699 'siteurl' => $site->siteurl, 700 'archived' => $site->archived, 701 'mature' => $site->mature, 702 'spam' => $site->spam, 703 'deleted' => $site->deleted, 704 ); 705 } 706 } 707 708 /** 709 * Filters the list of sites a user belongs to. 710 * 711 * @since MU (3.0.0) 712 * 713 * @param array $sites An array of site objects belonging to the user. 714 * @param int $user_id User ID. 715 * @param bool $all Whether the returned sites array should contain all sites, including 716 * those marked 'deleted', 'archived', or 'spam'. Default false. 717 */ 718 return apply_filters( 'get_blogs_of_user', $sites, $user_id, $all ); 719 } 720 721 /** 722 * Find out whether a user is a member of a given blog. 723 * 724 * @since MU (3.0.0) 725 * 726 * @global wpdb $wpdb WordPress database abstraction object. 727 * 728 * @param int $user_id Optional. The unique ID of the user. Defaults to the current user. 729 * @param int $blog_id Optional. ID of the blog to check. Defaults to the current site. 730 * @return bool 731 */ 732 function is_user_member_of_blog( $user_id = 0, $blog_id = 0 ) { 733 global $wpdb; 734 735 $user_id = (int) $user_id; 736 $blog_id = (int) $blog_id; 737 738 if ( empty( $user_id ) ) { 739 $user_id = get_current_user_id(); 740 } 741 742 // Technically not needed, but does save calls to get_site and get_user_meta 743 // in the event that the function is called when a user isn't logged in 744 if ( empty( $user_id ) ) { 745 return false; 746 } else { 747 $user = get_userdata( $user_id ); 748 if ( ! $user instanceof WP_User ) { 749 return false; 750 } 751 } 752 753 if ( ! is_multisite() ) { 754 return true; 755 } 756 757 if ( empty( $blog_id ) ) { 758 $blog_id = get_current_blog_id(); 759 } 760 761 $blog = get_site( $blog_id ); 762 763 if ( ! $blog || ! isset( $blog->domain ) || $blog->archived || $blog->spam || $blog->deleted ) { 764 return false; 765 } 766 767 $keys = get_user_meta( $user_id ); 768 if ( empty( $keys ) ) { 769 return false; 770 } 771 772 // no underscore before capabilities in $base_capabilities_key 773 $base_capabilities_key = $wpdb->base_prefix . 'capabilities'; 774 $site_capabilities_key = $wpdb->base_prefix . $blog_id . '_capabilities'; 775 776 if ( isset( $keys[ $base_capabilities_key ] ) && $blog_id == 1 ) { 777 return true; 778 } 779 780 if ( isset( $keys[ $site_capabilities_key ] ) ) { 781 return true; 782 } 783 784 return false; 785 } 786 787 /** 788 * Adds meta data to a user. 789 * 790 * @since 3.0.0 791 * 792 * @param int $user_id User ID. 793 * @param string $meta_key Metadata name. 794 * @param mixed $meta_value Metadata value. 795 * @param bool $unique Optional. Whether the same key should not be added. Default false. 796 * @return int|false Meta ID on success, false on failure. 797 */ 798 function add_user_meta( $user_id, $meta_key, $meta_value, $unique = false ) { 799 return add_metadata( 'user', $user_id, $meta_key, $meta_value, $unique ); 800 } 801 802 /** 803 * Remove metadata matching criteria from a user. 804 * 805 * You can match based on the key, or key and value. Removing based on key and 806 * value, will keep from removing duplicate metadata with the same key. It also 807 * allows removing all metadata matching key, if needed. 808 * 809 * @since 3.0.0 810 * @link https://codex.wordpress.org/Function_Reference/delete_user_meta 811 * 812 * @param int $user_id User ID 813 * @param string $meta_key Metadata name. 814 * @param mixed $meta_value Optional. Metadata value. 815 * @return bool True on success, false on failure. 816 */ 817 function delete_user_meta( $user_id, $meta_key, $meta_value = '' ) { 818 return delete_metadata( 'user', $user_id, $meta_key, $meta_value ); 819 } 820 821 /** 822 * Retrieve user meta field for a user. 823 * 824 * @since 3.0.0 825 * @link https://codex.wordpress.org/Function_Reference/get_user_meta 826 * 827 * @param int $user_id User ID. 828 * @param string $key Optional. The meta key to retrieve. By default, returns data for all keys. 829 * @param bool $single Whether to return a single value. 830 * @return mixed Will be an array if $single is false. Will be value of meta data field if $single is true. 831 */ 832 function get_user_meta( $user_id, $key = '', $single = false ) { 833 return get_metadata( 'user', $user_id, $key, $single ); 834 } 835 836 /** 837 * Update user meta field based on user ID. 838 * 839 * Use the $prev_value parameter to differentiate between meta fields with the 840 * same key and user ID. 841 * 842 * If the meta field for the user does not exist, it will be added. 843 * 844 * @since 3.0.0 845 * @link https://codex.wordpress.org/Function_Reference/update_user_meta 846 * 847 * @param int $user_id User ID. 848 * @param string $meta_key Metadata key. 849 * @param mixed $meta_value Metadata value. 850 * @param mixed $prev_value Optional. Previous value to check before removing. 851 * @return int|bool Meta ID if the key didn't exist, true on successful update, false on failure. 852 */ 853 function update_user_meta( $user_id, $meta_key, $meta_value, $prev_value = '' ) { 854 return update_metadata( 'user', $user_id, $meta_key, $meta_value, $prev_value ); 855 } 856 857 /** 858 * Count number of users who have each of the user roles. 859 * 860 * Assumes there are neither duplicated nor orphaned capabilities meta_values. 861 * Assumes role names are unique phrases. Same assumption made by WP_User_Query::prepare_query() 862 * Using $strategy = 'time' this is CPU-intensive and should handle around 10^7 users. 863 * Using $strategy = 'memory' this is memory-intensive and should handle around 10^5 users, but see WP Bug #12257. 864 * 865 * @since 3.0.0 866 * @since 4.4.0 The number of users with no role is now included in the `none` element. 867 * @since 4.9.0 The `$site_id` parameter was added to support multisite. 868 * 869 * @global wpdb $wpdb WordPress database abstraction object. 870 * 871 * @param string $strategy Optional. The computational strategy to use when counting the users. 872 * Accepts either 'time' or 'memory'. Default 'time'. 873 * @param int|null $site_id Optional. The site ID to count users for. Defaults to the current site. 874 * @return array Includes a grand total and an array of counts indexed by role strings. 875 */ 876 function count_users( $strategy = 'time', $site_id = null ) { 877 global $wpdb; 878 879 // Initialize 880 if ( ! $site_id ) { 881 $site_id = get_current_blog_id(); 882 } 883 884 /** 885 * Filter the user count before queries are run. Return a non-null value to cause count_users() 886 * to return early. 887 * 888 * @since 5.1.0 889 * 890 * @param null|string $result Default null. 891 * @param string $strategy Optional. The computational strategy to use when counting the users. 892 * Accepts either 'time' or 'memory'. Default 'time'. 893 * @param int|null $site_id Optional. The site ID to count users for. Defaults to the current site. 894 */ 895 $pre = apply_filters( 'pre_count_users', null, $strategy, $site_id ); 896 897 if ( null !== $pre ) { 898 return $pre; 899 } 900 901 $blog_prefix = $wpdb->get_blog_prefix( $site_id ); 902 $result = array(); 903 904 if ( 'time' == $strategy ) { 905 if ( is_multisite() && $site_id != get_current_blog_id() ) { 906 switch_to_blog( $site_id ); 907 $avail_roles = wp_roles()->get_names(); 908 restore_current_blog(); 909 } else { 910 $avail_roles = wp_roles()->get_names(); 911 } 912 913 // Build a CPU-intensive query that will return concise information. 914 $select_count = array(); 915 foreach ( $avail_roles as $this_role => $name ) { 916 $select_count[] = $wpdb->prepare( 'COUNT(NULLIF(`meta_value` LIKE %s, false))', '%' . $wpdb->esc_like( '"' . $this_role . '"' ) . '%' ); 917 } 918 $select_count[] = "COUNT(NULLIF(`meta_value` = 'a:0:{}', false))"; 919 $select_count = implode( ', ', $select_count ); 920 921 // Add the meta_value index to the selection list, then run the query. 922 $row = $wpdb->get_row( 923 " 924 SELECT {$select_count}, COUNT(*) 925 FROM {$wpdb->usermeta} 926 INNER JOIN {$wpdb->users} ON user_id = ID 927 WHERE meta_key = '{$blog_prefix}capabilities' 928 ", 929 ARRAY_N 930 ); 931 932 // Run the previous loop again to associate results with role names. 933 $col = 0; 934 $role_counts = array(); 935 foreach ( $avail_roles as $this_role => $name ) { 936 $count = (int) $row[ $col++ ]; 937 if ( $count > 0 ) { 938 $role_counts[ $this_role ] = $count; 939 } 940 } 941 942 $role_counts['none'] = (int) $row[ $col++ ]; 943 944 // Get the meta_value index from the end of the result set. 945 $total_users = (int) $row[ $col ]; 946 947 $result['total_users'] = $total_users; 948 $result['avail_roles'] =& $role_counts; 949 } else { 950 $avail_roles = array( 951 'none' => 0, 952 ); 953 954 $users_of_blog = $wpdb->get_col( 955 " 956 SELECT meta_value 957 FROM {$wpdb->usermeta} 958 INNER JOIN {$wpdb->users} ON user_id = ID 959 WHERE meta_key = '{$blog_prefix}capabilities' 960 " 961 ); 962 963 foreach ( $users_of_blog as $caps_meta ) { 964 $b_roles = maybe_unserialize( $caps_meta ); 965 if ( ! is_array( $b_roles ) ) { 966 continue; 967 } 968 if ( empty( $b_roles ) ) { 969 $avail_roles['none']++; 970 } 971 foreach ( $b_roles as $b_role => $val ) { 972 if ( isset( $avail_roles[ $b_role ] ) ) { 973 $avail_roles[ $b_role ]++; 974 } else { 975 $avail_roles[ $b_role ] = 1; 976 } 977 } 978 } 979 980 $result['total_users'] = count( $users_of_blog ); 981 $result['avail_roles'] =& $avail_roles; 982 } 983 984 return $result; 985 } 986 987 // 988 // Private helper functions 989 // 990 991 /** 992 * Set up global user vars. 993 * 994 * Used by wp_set_current_user() for back compat. Might be deprecated in the future. 995 * 996 * @since 2.0.4 997 * 998 * @global string $user_login The user username for logging in 999 * @global WP_User $userdata User data. 1000 * @global int $user_level The level of the user 1001 * @global int $user_ID The ID of the user 1002 * @global string $user_email The email address of the user 1003 * @global string $user_url The url in the user's profile 1004 * @global string $user_identity The display name of the user 1005 * 1006 * @param int $for_user_id Optional. User ID to set up global data. Default 0. 1007 */ 1008 function setup_userdata( $for_user_id = 0 ) { 1009 global $user_login, $userdata, $user_level, $user_ID, $user_email, $user_url, $user_identity; 1010 1011 if ( ! $for_user_id ) { 1012 $for_user_id = get_current_user_id(); 1013 } 1014 $user = get_userdata( $for_user_id ); 1015 1016 if ( ! $user ) { 1017 $user_ID = 0; 1018 $user_level = 0; 1019 $userdata = null; 1020 $user_login = ''; 1021 $user_email = ''; 1022 $user_url = ''; 1023 $user_identity = ''; 1024 return; 1025 } 1026 1027 $user_ID = (int) $user->ID; 1028 $user_level = (int) $user->user_level; 1029 $userdata = $user; 1030 $user_login = $user->user_login; 1031 $user_email = $user->user_email; 1032 $user_url = $user->user_url; 1033 $user_identity = $user->display_name; 1034 } 1035 1036 /** 1037 * Create dropdown HTML content of users. 1038 * 1039 * The content can either be displayed, which it is by default or retrieved by 1040 * setting the 'echo' argument. The 'include' and 'exclude' arguments do not 1041 * need to be used; all users will be displayed in that case. Only one can be 1042 * used, either 'include' or 'exclude', but not both. 1043 * 1044 * The available arguments are as follows: 1045 * 1046 * @since 2.3.0 1047 * @since 4.5.0 Added the 'display_name_with_login' value for 'show'. 1048 * @since 4.7.0 Added the `$role`, `$role__in`, and `$role__not_in` parameters. 1049 * 1050 * @param array|string $args { 1051 * Optional. Array or string of arguments to generate a drop-down of users. 1052 * See WP_User_Query::prepare_query() for additional available arguments. 1053 * 1054 * @type string $show_option_all Text to show as the drop-down default (all). 1055 * Default empty. 1056 * @type string $show_option_none Text to show as the drop-down default when no 1057 * users were found. Default empty. 1058 * @type int|string $option_none_value Value to use for $show_option_non when no users 1059 * were found. Default -1. 1060 * @type string $hide_if_only_one_author Whether to skip generating the drop-down 1061 * if only one user was found. Default empty. 1062 * @type string $orderby Field to order found users by. Accepts user fields. 1063 * Default 'display_name'. 1064 * @type string $order Whether to order users in ascending or descending 1065 * order. Accepts 'ASC' (ascending) or 'DESC' (descending). 1066 * Default 'ASC'. 1067 * @type array|string $include Array or comma-separated list of user IDs to include. 1068 * Default empty. 1069 * @type array|string $exclude Array or comma-separated list of user IDs to exclude. 1070 * Default empty. 1071 * @type bool|int $multi Whether to skip the ID attribute on the 'select' element. 1072 * Accepts 1|true or 0|false. Default 0|false. 1073 * @type string $show User data to display. If the selected item is empty 1074 * then the 'user_login' will be displayed in parentheses. 1075 * Accepts any user field, or 'display_name_with_login' to show 1076 * the display name with user_login in parentheses. 1077 * Default 'display_name'. 1078 * @type int|bool $echo Whether to echo or return the drop-down. Accepts 1|true (echo) 1079 * or 0|false (return). Default 1|true. 1080 * @type int $selected Which user ID should be selected. Default 0. 1081 * @type bool $include_selected Whether to always include the selected user ID in the drop- 1082 * down. Default false. 1083 * @type string $name Name attribute of select element. Default 'user'. 1084 * @type string $id ID attribute of the select element. Default is the value of $name. 1085 * @type string $class Class attribute of the select element. Default empty. 1086 * @type int $blog_id ID of blog (Multisite only). Default is ID of the current blog. 1087 * @type string $who Which type of users to query. Accepts only an empty string or 1088 * 'authors'. Default empty. 1089 * @type string|array $role An array or a comma-separated list of role names that users must 1090 * match to be included in results. Note that this is an inclusive 1091 * list: users must match *each* role. Default empty. 1092 * @type array $role__in An array of role names. Matched users must have at least one of 1093 * these roles. Default empty array. 1094 * @type array $role__not_in An array of role names to exclude. Users matching one or more of 1095 * these roles will not be included in results. Default empty array. 1096 * } 1097 * @return string String of HTML content. 1098 */ 1099 function wp_dropdown_users( $args = '' ) { 1100 $defaults = array( 1101 'show_option_all' => '', 1102 'show_option_none' => '', 1103 'hide_if_only_one_author' => '', 1104 'orderby' => 'display_name', 1105 'order' => 'ASC', 1106 'include' => '', 1107 'exclude' => '', 1108 'multi' => 0, 1109 'show' => 'display_name', 1110 'echo' => 1, 1111 'selected' => 0, 1112 'name' => 'user', 1113 'class' => '', 1114 'id' => '', 1115 'blog_id' => get_current_blog_id(), 1116 'who' => '', 1117 'include_selected' => false, 1118 'option_none_value' => -1, 1119 'role' => '', 1120 'role__in' => array(), 1121 'role__not_in' => array(), 1122 ); 1123 1124 $defaults['selected'] = is_author() ? get_query_var( 'author' ) : 0; 1125 1126 $r = wp_parse_args( $args, $defaults ); 1127 1128 $query_args = wp_array_slice_assoc( $r, array( 'blog_id', 'include', 'exclude', 'orderby', 'order', 'who', 'role', 'role__in', 'role__not_in' ) ); 1129 1130 $fields = array( 'ID', 'user_login' ); 1131 1132 $show = ! empty( $r['show'] ) ? $r['show'] : 'display_name'; 1133 if ( 'display_name_with_login' === $show ) { 1134 $fields[] = 'display_name'; 1135 } else { 1136 $fields[] = $show; 1137 } 1138 1139 $query_args['fields'] = $fields; 1140 1141 $show_option_all = $r['show_option_all']; 1142 $show_option_none = $r['show_option_none']; 1143 $option_none_value = $r['option_none_value']; 1144 1145 /** 1146 * Filters the query arguments for the list of users in the dropdown. 1147 * 1148 * @since 4.4.0 1149 * 1150 * @param array $query_args The query arguments for get_users(). 1151 * @param array $r The arguments passed to wp_dropdown_users() combined with the defaults. 1152 */ 1153 $query_args = apply_filters( 'wp_dropdown_users_args', $query_args, $r ); 1154 1155 $users = get_users( $query_args ); 1156 1157 $output = ''; 1158 if ( ! empty( $users ) && ( empty( $r['hide_if_only_one_author'] ) || count( $users ) > 1 ) ) { 1159 $name = esc_attr( $r['name'] ); 1160 if ( $r['multi'] && ! $r['id'] ) { 1161 $id = ''; 1162 } else { 1163 $id = $r['id'] ? " id='" . esc_attr( $r['id'] ) . "'" : " id='$name'"; 1164 } 1165 $output = "<select name='{$name}'{$id} class='" . $r['class'] . "'>\n"; 1166 1167 if ( $show_option_all ) { 1168 $output .= "\t<option value='0'>$show_option_all</option>\n"; 1169 } 1170 1171 if ( $show_option_none ) { 1172 $_selected = selected( $option_none_value, $r['selected'], false ); 1173 $output .= "\t<option value='" . esc_attr( $option_none_value ) . "'$_selected>$show_option_none</option>\n"; 1174 } 1175 1176 if ( $r['include_selected'] && ( $r['selected'] > 0 ) ) { 1177 $found_selected = false; 1178 $r['selected'] = (int) $r['selected']; 1179 foreach ( (array) $users as $user ) { 1180 $user->ID = (int) $user->ID; 1181 if ( $user->ID === $r['selected'] ) { 1182 $found_selected = true; 1183 } 1184 } 1185 1186 if ( ! $found_selected ) { 1187 $users[] = get_userdata( $r['selected'] ); 1188 } 1189 } 1190 1191 foreach ( (array) $users as $user ) { 1192 if ( 'display_name_with_login' === $show ) { 1193 /* translators: 1: display name, 2: user_login */ 1194 $display = sprintf( _x( '%1$s (%2$s)', 'user dropdown' ), $user->display_name, $user->user_login ); 1195 } elseif ( ! empty( $user->$show ) ) { 1196 $display = $user->$show; 1197 } else { 1198 $display = '(' . $user->user_login . ')'; 1199 } 1200 1201 $_selected = selected( $user->ID, $r['selected'], false ); 1202 $output .= "\t<option value='$user->ID'$_selected>" . esc_html( $display ) . "</option>\n"; 1203 } 1204 1205 $output .= '</select>'; 1206 } 1207 1208 /** 1209 * Filters the wp_dropdown_users() HTML output. 1210 * 1211 * @since 2.3.0 1212 * 1213 * @param string $output HTML output generated by wp_dropdown_users(). 1214 */ 1215 $html = apply_filters( 'wp_dropdown_users', $output ); 1216 1217 if ( $r['echo'] ) { 1218 echo $html; 1219 } 1220 return $html; 1221 } 1222 1223 /** 1224 * Sanitize user field based on context. 1225 * 1226 * Possible context values are: 'raw', 'edit', 'db', 'display', 'attribute' and 'js'. The 1227 * 'display' context is used by default. 'attribute' and 'js' contexts are treated like 'display' 1228 * when calling filters. 1229 * 1230 * @since 2.3.0 1231 * 1232 * @param string $field The user Object field name. 1233 * @param mixed $value The user Object value. 1234 * @param int $user_id User ID. 1235 * @param string $context How to sanitize user fields. Looks for 'raw', 'edit', 'db', 'display', 1236 * 'attribute' and 'js'. 1237 * @return mixed Sanitized value. 1238 */ 1239 function sanitize_user_field( $field, $value, $user_id, $context ) { 1240 $int_fields = array( 'ID' ); 1241 if ( in_array( $field, $int_fields ) ) { 1242 $value = (int) $value; 1243 } 1244 1245 if ( 'raw' == $context ) { 1246 return $value; 1247 } 1248 1249 if ( ! is_string( $value ) && ! is_numeric( $value ) ) { 1250 return $value; 1251 } 1252 1253 $prefixed = false !== strpos( $field, 'user_' ); 1254 1255 if ( 'edit' == $context ) { 1256 if ( $prefixed ) { 1257 1258 /** This filter is documented in wp-includes/post.php */ 1259 $value = apply_filters( "edit_{$field}", $value, $user_id ); 1260 } else { 1261 1262 /** 1263 * Filters a user field value in the 'edit' context. 1264 * 1265 * The dynamic portion of the hook name, `$field`, refers to the prefixed user 1266 * field being filtered, such as 'user_login', 'user_email', 'first_name', etc. 1267 * 1268 * @since 2.9.0 1269 * 1270 * @param mixed $value Value of the prefixed user field. 1271 * @param int $user_id User ID. 1272 */ 1273 $value = apply_filters( "edit_user_{$field}", $value, $user_id ); 1274 } 1275 1276 if ( 'description' == $field ) { 1277 $value = esc_html( $value ); // textarea_escaped? 1278 } else { 1279 $value = esc_attr( $value ); 1280 } 1281 } elseif ( 'db' == $context ) { 1282 if ( $prefixed ) { 1283 /** This filter is documented in wp-includes/post.php */ 1284 $value = apply_filters( "pre_{$field}", $value ); 1285 } else { 1286 1287 /** 1288 * Filters the value of a user field in the 'db' context. 1289 * 1290 * The dynamic portion of the hook name, `$field`, refers to the prefixed user 1291 * field being filtered, such as 'user_login', 'user_email', 'first_name', etc. 1292 * 1293 * @since 2.9.0 1294 * 1295 * @param mixed $value Value of the prefixed user field. 1296 */ 1297 $value = apply_filters( "pre_user_{$field}", $value ); 1298 } 1299 } else { 1300 // Use display filters by default. 1301 if ( $prefixed ) { 1302 1303 /** This filter is documented in wp-includes/post.php */ 1304 $value = apply_filters( "{$field}", $value, $user_id, $context ); 1305 } else { 1306 1307 /** 1308 * Filters the value of a user field in a standard context. 1309 * 1310 * The dynamic portion of the hook name, `$field`, refers to the prefixed user 1311 * field being filtered, such as 'user_login', 'user_email', 'first_name', etc. 1312 * 1313 * @since 2.9.0 1314 * 1315 * @param mixed $value The user object value to sanitize. 1316 * @param int $user_id User ID. 1317 * @param string $context The context to filter within. 1318 */ 1319 $value = apply_filters( "user_{$field}", $value, $user_id, $context ); 1320 } 1321 } 1322 1323 if ( 'user_url' == $field ) { 1324 $value = esc_url( $value ); 1325 } 1326 1327 if ( 'attribute' == $context ) { 1328 $value = esc_attr( $value ); 1329 } elseif ( 'js' == $context ) { 1330 $value = esc_js( $value ); 1331 } 1332 return $value; 1333 } 1334 1335 /** 1336 * Update all user caches 1337 * 1338 * @since 3.0.0 1339 * 1340 * @param WP_User $user User object to be cached 1341 * @return bool|null Returns false on failure. 1342 */ 1343 function update_user_caches( $user ) { 1344 if ( $user instanceof WP_User ) { 1345 if ( ! $user->exists() ) { 1346 return false; 1347 } 1348 1349 $user = $user->data; 1350 } 1351 1352 wp_cache_add( $user->ID, $user, 'users' ); 1353 wp_cache_add( $user->user_login, $user->ID, 'userlogins' ); 1354 wp_cache_add( $user->user_email, $user->ID, 'useremail' ); 1355 wp_cache_add( $user->user_nicename, $user->ID, 'userslugs' ); 1356 } 1357 1358 /** 1359 * Clean all user caches 1360 * 1361 * @since 3.0.0 1362 * @since 4.4.0 'clean_user_cache' action was added. 1363 * 1364 * @param WP_User|int $user User object or ID to be cleaned from the cache 1365 */ 1366 function clean_user_cache( $user ) { 1367 if ( is_numeric( $user ) ) { 1368 $user = new WP_User( $user ); 1369 } 1370 1371 if ( ! $user->exists() ) { 1372 return; 1373 } 1374 1375 wp_cache_delete( $user->ID, 'users' ); 1376 wp_cache_delete( $user->user_login, 'userlogins' ); 1377 wp_cache_delete( $user->user_email, 'useremail' ); 1378 wp_cache_delete( $user->user_nicename, 'userslugs' ); 1379 1380 /** 1381 * Fires immediately after the given user's cache is cleaned. 1382 * 1383 * @since 4.4.0 1384 * 1385 * @param int $user_id User ID. 1386 * @param WP_User $user User object. 1387 */ 1388 do_action( 'clean_user_cache', $user->ID, $user ); 1389 } 1390 1391 /** 1392 * Determines whether the given username exists. 1393 * 1394 * For more information on this and similar theme functions, check out 1395 * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ 1396 * Conditional Tags} article in the Theme Developer Handbook. 1397 * 1398 * @since 2.0.0 1399 * 1400 * @param string $username Username. 1401 * @return int|false The user's ID on success, and false on failure. 1402 */ 1403 function username_exists( $username ) { 1404 $user = get_user_by( 'login', $username ); 1405 if ( $user ) { 1406 $user_id = $user->ID; 1407 } else { 1408 $user_id = false; 1409 } 1410 1411 /** 1412 * Filters whether the given username exists or not. 1413 * 1414 * @since 4.9.0 1415 * 1416 * @param int|false $user_id The user's ID on success, and false on failure. 1417 * @param string $username Username to check. 1418 */ 1419 return apply_filters( 'username_exists', $user_id, $username ); 1420 } 1421 1422 /** 1423 * Determines whether the given email exists. 1424 * 1425 * For more information on this and similar theme functions, check out 1426 * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ 1427 * Conditional Tags} article in the Theme Developer Handbook. 1428 * 1429 * @since 2.1.0 1430 * 1431 * @param string $email Email. 1432 * @return int|false The user's ID on success, and false on failure. 1433 */ 1434 function email_exists( $email ) { 1435 $user = get_user_by( 'email', $email ); 1436 if ( $user ) { 1437 return $user->ID; 1438 } 1439 return false; 1440 } 1441 1442 /** 1443 * Checks whether a username is valid. 1444 * 1445 * @since 2.0.1 1446 * @since 4.4.0 Empty sanitized usernames are now considered invalid 1447 * 1448 * @param string $username Username. 1449 * @return bool Whether username given is valid 1450 */ 1451 function validate_username( $username ) { 1452 $sanitized = sanitize_user( $username, true ); 1453 $valid = ( $sanitized == $username && ! empty( $sanitized ) ); 1454 1455 /** 1456 * Filters whether the provided username is valid or not. 1457 * 1458 * @since 2.0.1 1459 * 1460 * @param bool $valid Whether given username is valid. 1461 * @param string $username Username to check. 1462 */ 1463 return apply_filters( 'validate_username', $valid, $username ); 1464 } 1465 1466 /** 1467 * Insert a user into the database. 1468 * 1469 * Most of the `$userdata` array fields have filters associated with the values. Exceptions are 1470 * 'ID', 'rich_editing', 'syntax_highlighting', 'comment_shortcuts', 'admin_color', 'use_ssl', 1471 * 'user_registered', and 'role'. The filters have the prefix 'pre_user_' followed by the field 1472 * name. An example using 'description' would have the filter called, 'pre_user_description' that 1473 * can be hooked into. 1474 * 1475 * @since 2.0.0 1476 * @since 3.6.0 The `aim`, `jabber`, and `yim` fields were removed as default user contact 1477 * methods for new installations. See wp_get_user_contact_methods(). 1478 * @since 4.7.0 The user's locale can be passed to `$userdata`. 1479 * 1480 * @global wpdb $wpdb WordPress database abstraction object. 1481 * 1482 * @param array|object|WP_User $userdata { 1483 * An array, object, or WP_User object of user data arguments. 1484 * 1485 * @type int $ID User ID. If supplied, the user will be updated. 1486 * @type string $user_pass The plain-text user password. 1487 * @type string $user_login The user's login username. 1488 * @type string $user_nicename The URL-friendly user name. 1489 * @type string $user_url The user URL. 1490 * @type string $user_email The user email address. 1491 * @type string $display_name The user's display name. 1492 * Default is the user's username. 1493 * @type string $nickname The user's nickname. 1494 * Default is the user's username. 1495 * @type string $first_name The user's first name. For new users, will be used 1496 * to build the first part of the user's display name 1497 * if `$display_name` is not specified. 1498 * @type string $last_name The user's last name. For new users, will be used 1499 * to build the second part of the user's display name 1500 * if `$display_name` is not specified. 1501 * @type string $description The user's biographical description. 1502 * @type string|bool $rich_editing Whether to enable the rich-editor for the user. 1503 * False if not empty. 1504 * @type string|bool $syntax_highlighting Whether to enable the rich code editor for the user. 1505 * False if not empty. 1506 * @type string|bool $comment_shortcuts Whether to enable comment moderation keyboard 1507 * shortcuts for the user. Default false. 1508 * @type string $admin_color Admin color scheme for the user. Default 'fresh'. 1509 * @type bool $use_ssl Whether the user should always access the admin over 1510 * https. Default false. 1511 * @type string $user_registered Date the user registered. Format is 'Y-m-d H:i:s'. 1512 * @type string|bool $show_admin_bar_front Whether to display the Admin Bar for the user on the 1513 * site's front end. Default true. 1514 * @type string $role User's role. 1515 * @type string $locale User's locale. Default empty. 1516 * } 1517 * @return int|WP_Error The newly created user's ID or a WP_Error object if the user could not 1518 * be created. 1519 */ 1520 function wp_insert_user( $userdata ) { 1521 global $wpdb; 1522 1523 if ( $userdata instanceof stdClass ) { 1524 $userdata = get_object_vars( $userdata ); 1525 } elseif ( $userdata instanceof WP_User ) { 1526 $userdata = $userdata->to_array(); 1527 } 1528 1529 // Are we updating or creating? 1530 if ( ! empty( $userdata['ID'] ) ) { 1531 $ID = (int) $userdata['ID']; 1532 $update = true; 1533 $old_user_data = get_userdata( $ID ); 1534 1535 if ( ! $old_user_data ) { 1536 return new WP_Error( 'invalid_user_id', __( 'Invalid user ID.' ) ); 1537 } 1538 1539 // hashed in wp_update_user(), plaintext if called directly 1540 $user_pass = ! empty( $userdata['user_pass'] ) ? $userdata['user_pass'] : $old_user_data->user_pass; 1541 } else { 1542 $update = false; 1543 // Hash the password 1544 $user_pass = wp_hash_password( $userdata['user_pass'] ); 1545 } 1546 1547 $sanitized_user_login = sanitize_user( $userdata['user_login'], true ); 1548 1549 /** 1550 * Filters a username after it has been sanitized. 1551 * 1552 * This filter is called before the user is created or updated. 1553 * 1554 * @since 2.0.3 1555 * 1556 * @param string $sanitized_user_login Username after it has been sanitized. 1557 */ 1558 $pre_user_login = apply_filters( 'pre_user_login', $sanitized_user_login ); 1559 1560 //Remove any non-printable chars from the login string to see if we have ended up with an empty username 1561 $user_login = trim( $pre_user_login ); 1562 1563 // user_login must be between 0 and 60 characters. 1564 if ( empty( $user_login ) ) { 1565 return new WP_Error( 'empty_user_login', __( 'Cannot create a user with an empty login name.' ) ); 1566 } elseif ( mb_strlen( $user_login ) > 60 ) { 1567 return new WP_Error( 'user_login_too_long', __( 'Username may not be longer than 60 characters.' ) ); 1568 } 1569 1570 if ( ! $update && username_exists( $user_login ) ) { 1571 return new WP_Error( 'existing_user_login', __( 'Sorry, that username already exists!' ) ); 1572 } 1573 1574 /** 1575 * Filters the list of blacklisted usernames. 1576 * 1577 * @since 4.4.0 1578 * 1579 * @param array $usernames Array of blacklisted usernames. 1580 */ 1581 $illegal_logins = (array) apply_filters( 'illegal_user_logins', array() ); 1582 1583 if ( in_array( strtolower( $user_login ), array_map( 'strtolower', $illegal_logins ) ) ) { 1584 return new WP_Error( 'invalid_username', __( 'Sorry, that username is not allowed.' ) ); 1585 } 1586 1587 /* 1588 * If a nicename is provided, remove unsafe user characters before using it. 1589 * Otherwise build a nicename from the user_login. 1590 */ 1591 if ( ! empty( $userdata['user_nicename'] ) ) { 1592 $user_nicename = sanitize_user( $userdata['user_nicename'], true ); 1593 if ( mb_strlen( $user_nicename ) > 50 ) { 1594 return new WP_Error( 'user_nicename_too_long', __( 'Nicename may not be longer than 50 characters.' ) ); 1595 } 1596 } else { 1597 $user_nicename = mb_substr( $user_login, 0, 50 ); 1598 } 1599 1600 $user_nicename = sanitize_title( $user_nicename ); 1601 1602 // Store values to save in user meta. 1603 $meta = array(); 1604 1605 /** 1606 * Filters a user's nicename before the user is created or updated. 1607 * 1608 * @since 2.0.3 1609 * 1610 * @param string $user_nicename The user's nicename. 1611 */ 1612 $user_nicename = apply_filters( 'pre_user_nicename', $user_nicename ); 1613 1614 $raw_user_url = empty( $userdata['user_url'] ) ? '' : $userdata['user_url']; 1615 1616 /** 1617 * Filters a user's URL before the user is created or updated. 1618 * 1619 * @since 2.0.3 1620 * 1621 * @param string $raw_user_url The user's URL. 1622 */ 1623 $user_url = apply_filters( 'pre_user_url', $raw_user_url ); 1624 1625 $raw_user_email = empty( $userdata['user_email'] ) ? '' : $userdata['user_email']; 1626 1627 /** 1628 * Filters a user's email before the user is created or updated. 1629 * 1630 * @since 2.0.3 1631 * 1632 * @param string $raw_user_email The user's email. 1633 */ 1634 $user_email = apply_filters( 'pre_user_email', $raw_user_email ); 1635 1636 /* 1637 * If there is no update, just check for `email_exists`. If there is an update, 1638 * check if current email and new email are the same, or not, and check `email_exists` 1639 * accordingly. 1640 */ 1641 if ( ( ! $update || ( ! empty( $old_user_data ) && 0 !== strcasecmp( $user_email, $old_user_data->user_email ) ) ) 1642 && ! defined( 'WP_IMPORTING' ) 1643 && email_exists( $user_email ) 1644 ) { 1645 return new WP_Error( 'existing_user_email', __( 'Sorry, that email address is already used!' ) ); 1646 } 1647 $nickname = empty( $userdata['nickname'] ) ? $user_login : $userdata['nickname']; 1648 1649 /** 1650 * Filters a user's nickname before the user is created or updated. 1651 * 1652 * @since 2.0.3 1653 * 1654 * @param string $nickname The user's nickname. 1655 */ 1656 $meta['nickname'] = apply_filters( 'pre_user_nickname', $nickname ); 1657 1658 $first_name = empty( $userdata['first_name'] ) ? '' : $userdata['first_name']; 1659 1660 /** 1661 * Filters a user's first name before the user is created or updated. 1662 * 1663 * @since 2.0.3 1664 * 1665 * @param string $first_name The user's first name. 1666 */ 1667 $meta['first_name'] = apply_filters( 'pre_user_first_name', $first_name ); 1668 1669 $last_name = empty( $userdata['last_name'] ) ? '' : $userdata['last_name']; 1670 1671 /** 1672 * Filters a user's last name before the user is created or updated. 1673 * 1674 * @since 2.0.3 1675 * 1676 * @param string $last_name The user's last name. 1677 */ 1678 $meta['last_name'] = apply_filters( 'pre_user_last_name', $last_name ); 1679 1680 if ( empty( $userdata['display_name'] ) ) { 1681 if ( $update ) { 1682 $display_name = $user_login; 1683 } elseif ( $meta['first_name'] && $meta['last_name'] ) { 1684 /* translators: 1: first name, 2: last name */ 1685 $display_name = sprintf( _x( '%1$s %2$s', 'Display name based on first name and last name' ), $meta['first_name'], $meta['last_name'] ); 1686 } elseif ( $meta['first_name'] ) { 1687 $display_name = $meta['first_name']; 1688 } elseif ( $meta['last_name'] ) { 1689 $display_name = $meta['last_name']; 1690 } else { 1691 $display_name = $user_login; 1692 } 1693 } else { 1694 $display_name = $userdata['display_name']; 1695 } 1696 1697 /** 1698 * Filters a user's display name before the user is created or updated. 1699 * 1700 * @since 2.0.3 1701 * 1702 * @param string $display_name The user's display name. 1703 */ 1704 $display_name = apply_filters( 'pre_user_display_name', $display_name ); 1705 1706 $description = empty( $userdata['description'] ) ? '' : $userdata['description']; 1707 1708 /** 1709 * Filters a user's description before the user is created or updated. 1710 * 1711 * @since 2.0.3 1712 * 1713 * @param string $description The user's description. 1714 */ 1715 $meta['description'] = apply_filters( 'pre_user_description', $description ); 1716 1717 $meta['rich_editing'] = empty( $userdata['rich_editing'] ) ? 'true' : $userdata['rich_editing']; 1718 1719 $meta['syntax_highlighting'] = empty( $userdata['syntax_highlighting'] ) ? 'true' : $userdata['syntax_highlighting']; 1720 1721 $meta['comment_shortcuts'] = empty( $userdata['comment_shortcuts'] ) || 'false' === $userdata['comment_shortcuts'] ? 'false' : 'true'; 1722 1723 $admin_color = empty( $userdata['admin_color'] ) ? 'fresh' : $userdata['admin_color']; 1724 $meta['admin_color'] = preg_replace( '|[^a-z0-9 _.\-@]|i', '', $admin_color ); 1725 1726 $meta['use_ssl'] = empty( $userdata['use_ssl'] ) ? 0 : $userdata['use_ssl']; 1727 1728 $user_registered = empty( $userdata['user_registered'] ) ? gmdate( 'Y-m-d H:i:s' ) : $userdata['user_registered']; 1729 1730 $meta['show_admin_bar_front'] = empty( $userdata['show_admin_bar_front'] ) ? 'true' : $userdata['show_admin_bar_front']; 1731 1732 $meta['locale'] = isset( $userdata['locale'] ) ? $userdata['locale'] : ''; 1733 1734 $user_nicename_check = $wpdb->get_var( $wpdb->prepare( "SELECT ID FROM $wpdb->users WHERE user_nicename = %s AND user_login != %s LIMIT 1", $user_nicename, $user_login ) ); 1735 1736 if ( $user_nicename_check ) { 1737 $suffix = 2; 1738 while ( $user_nicename_check ) { 1739 // user_nicename allows 50 chars. Subtract one for a hyphen, plus the length of the suffix. 1740 $base_length = 49 - mb_strlen( $suffix ); 1741 $alt_user_nicename = mb_substr( $user_nicename, 0, $base_length ) . "-$suffix"; 1742 $user_nicename_check = $wpdb->get_var( $wpdb->prepare( "SELECT ID FROM $wpdb->users WHERE user_nicename = %s AND user_login != %s LIMIT 1", $alt_user_nicename, $user_login ) ); 1743 $suffix++; 1744 } 1745 $user_nicename = $alt_user_nicename; 1746 } 1747 1748 $compacted = compact( 'user_pass', 'user_email', 'user_url', 'user_nicename', 'display_name', 'user_registered' ); 1749 $data = wp_unslash( $compacted ); 1750 1751 if ( ! $update ) { 1752 $data = $data + compact( 'user_login' ); 1753 } 1754 1755 /** 1756 * Filters user data before the record is created or updated. 1757 * 1758 * It only includes data in the wp_users table wp_user, not any user metadata. 1759 * 1760 * @since 4.9.0 1761 * 1762 * @param array $data { 1763 * Values and keys for the user. 1764 * 1765 * @type string $user_login The user's login. Only included if $update == false 1766 * @type string $user_pass The user's password. 1767 * @type string $user_email The user's email. 1768 * @type string $user_url The user's url. 1769 * @type string $user_nicename The user's nice name. Defaults to a URL-safe version of user's login 1770 * @type string $display_name The user's display name. 1771 * @type string $user_registered MySQL timestamp describing the moment when the user registered. Defaults to 1772 * the current UTC timestamp. 1773 * } 1774 * @param bool $update Whether the user is being updated rather than created. 1775 * @param int|null $id ID of the user to be updated, or NULL if the user is being created. 1776 */ 1777 $data = apply_filters( 'wp_pre_insert_user_data', $data, $update, $update ? (int) $ID : null ); 1778 1779 if ( $update ) { 1780 if ( $user_email !== $old_user_data->user_email ) { 1781 $data['user_activation_key'] = ''; 1782 } 1783 $wpdb->update( $wpdb->users, $data, compact( 'ID' ) ); 1784 $user_id = (int) $ID; 1785 } else { 1786 $wpdb->insert( $wpdb->users, $data ); 1787 $user_id = (int) $wpdb->insert_id; 1788 } 1789 1790 $user = new WP_User( $user_id ); 1791 1792 /** 1793 * Filters a user's meta values and keys immediately after the user is created or updated 1794 * and before any user meta is inserted or updated. 1795 * 1796 * Does not include contact methods. These are added using `wp_get_user_contact_methods( $user )`. 1797 * 1798 * @since 4.4.0 1799 * 1800 * @param array $meta { 1801 * Default meta values and keys for the user. 1802 * 1803 * @type string $nickname The user's nickname. Default is the user's username. 1804 * @type string $first_name The user's first name. 1805 * @type string $last_name The user's last name. 1806 * @type string $description The user's description. 1807 * @type bool $rich_editing Whether to enable the rich-editor for the user. False if not empty. 1808 * @type bool $syntax_highlighting Whether to enable the rich code editor for the user. False if not empty. 1809 * @type bool $comment_shortcuts Whether to enable keyboard shortcuts for the user. Default false. 1810 * @type string $admin_color The color scheme for a user's admin screen. Default 'fresh'. 1811 * @type int|bool $use_ssl Whether to force SSL on the user's admin area. 0|false if SSL is 1812 * not forced. 1813 * @type bool $show_admin_bar_front Whether to show the admin bar on the front end for the user. 1814 * Default true. 1815 * @type string $locale User's locale. Default empty. 1816 * } 1817 * @param WP_User $user User object. 1818 * @param bool $update Whether the user is being updated rather than created. 1819 */ 1820 $meta = apply_filters( 'insert_user_meta', $meta, $user, $update ); 1821 1822 // Update user meta. 1823 foreach ( $meta as $key => $value ) { 1824 update_user_meta( $user_id, $key, $value ); 1825 } 1826 1827 foreach ( wp_get_user_contact_methods( $user ) as $key => $value ) { 1828 if ( isset( $userdata[ $key ] ) ) { 1829 update_user_meta( $user_id, $key, $userdata[ $key ] ); 1830 } 1831 } 1832 1833 if ( isset( $userdata['role'] ) ) { 1834 $user->set_role( $userdata['role'] ); 1835 } elseif ( ! $update ) { 1836 $user->set_role( get_option( 'default_role' ) ); 1837 } 1838 wp_cache_delete( $user_id, 'users' ); 1839 wp_cache_delete( $user_login, 'userlogins' ); 1840 1841 if ( $update ) { 1842 /** 1843 * Fires immediately after an existing user is updated. 1844 * 1845 * @since 2.0.0 1846 * 1847 * @param int $user_id User ID. 1848 * @param WP_User $old_user_data Object containing user's data prior to update. 1849 */ 1850 do_action( 'profile_update', $user_id, $old_user_data ); 1851 } else { 1852 /** 1853 * Fires immediately after a new user is registered. 1854 * 1855 * @since 1.5.0 1856 * 1857 * @param int $user_id User ID. 1858 */ 1859 do_action( 'user_register', $user_id ); 1860 } 1861 1862 return $user_id; 1863 } 1864 1865 /** 1866 * Update a user in the database. 1867 * 1868 * It is possible to update a user's password by specifying the 'user_pass' 1869 * value in the $userdata parameter array. 1870 * 1871 * If current user's password is being updated, then the cookies will be 1872 * cleared. 1873 * 1874 * @since 2.0.0 1875 * 1876 * @see wp_insert_user() For what fields can be set in $userdata. 1877 * 1878 * @param array|object|WP_User $userdata An array of user data or a user object of type stdClass or WP_User. 1879 * @return int|WP_Error The updated user's ID or a WP_Error object if the user could not be updated. 1880 */ 1881 function wp_update_user( $userdata ) { 1882 if ( $userdata instanceof stdClass ) { 1883 $userdata = get_object_vars( $userdata ); 1884 } elseif ( $userdata instanceof WP_User ) { 1885 $userdata = $userdata->to_array(); 1886 } 1887 1888 $ID = isset( $userdata['ID'] ) ? (int) $userdata['ID'] : 0; 1889 if ( ! $ID ) { 1890 return new WP_Error( 'invalid_user_id', __( 'Invalid user ID.' ) ); 1891 } 1892 1893 // First, get all of the original fields 1894 $user_obj = get_userdata( $ID ); 1895 if ( ! $user_obj ) { 1896 return new WP_Error( 'invalid_user_id', __( 'Invalid user ID.' ) ); 1897 } 1898 1899 $user = $user_obj->to_array(); 1900 1901 // Add additional custom fields 1902 foreach ( _get_additional_user_keys( $user_obj ) as $key ) { 1903 $user[ $key ] = get_user_meta( $ID, $key, true ); 1904 } 1905 1906 // Escape data pulled from DB. 1907 $user = add_magic_quotes( $user ); 1908 1909 if ( ! empty( $userdata['user_pass'] ) && $userdata['user_pass'] !== $user_obj->user_pass ) { 1910 // If password is changing, hash it now 1911 $plaintext_pass = $userdata['user_pass']; 1912 $userdata['user_pass'] = wp_hash_password( $userdata['user_pass'] ); 1913 1914 /** 1915 * Filters whether to send the password change email. 1916 * 1917 * @since 4.3.0 1918 * 1919 * @see wp_insert_user() For `$user` and `$userdata` fields. 1920 * 1921 * @param bool $send Whether to send the email. 1922 * @param array $user The original user array. 1923 * @param array $userdata The updated user array. 1924 */ 1925 $send_password_change_email = apply_filters( 'send_password_change_email', true, $user, $userdata ); 1926 } 1927 1928 if ( isset( $userdata['user_email'] ) && $user['user_email'] !== $userdata['user_email'] ) { 1929 /** 1930 * Filters whether to send the email change email. 1931 * 1932 * @since 4.3.0 1933 * 1934 * @see wp_insert_user() For `$user` and `$userdata` fields. 1935 * 1936 * @param bool $send Whether to send the email. 1937 * @param array $user The original user array. 1938 * @param array $userdata The updated user array. 1939 */ 1940 $send_email_change_email = apply_filters( 'send_email_change_email', true, $user, $userdata ); 1941 } 1942 1943 wp_cache_delete( $user['user_email'], 'useremail' ); 1944 wp_cache_delete( $user['user_nicename'], 'userslugs' ); 1945 1946 // Merge old and new fields with new fields overwriting old ones. 1947 $userdata = array_merge( $user, $userdata ); 1948 $user_id = wp_insert_user( $userdata ); 1949 1950 if ( ! is_wp_error( $user_id ) ) { 1951 1952 $blog_name = wp_specialchars_decode( get_option( 'blogname' ), ENT_QUOTES ); 1953 1954 $switched_locale = false; 1955 if ( ! empty( $send_password_change_email ) || ! empty( $send_email_change_email ) ) { 1956 $switched_locale = switch_to_locale( get_user_locale( $user_id ) ); 1957 } 1958 1959 if ( ! empty( $send_password_change_email ) ) { 1960 /* translators: Do not translate USERNAME, ADMIN_EMAIL, EMAIL, SITENAME, SITEURL: those are placeholders. */ 1961 $pass_change_text = __( 1962 'Hi ###USERNAME###, 1963 1964 This notice confirms that your password was changed on ###SITENAME###. 1965 1966 If you did not change your password, please contact the Site Administrator at 1967 ###ADMIN_EMAIL### 1968 1969 This email has been sent to ###EMAIL### 1970 1971 Regards, 1972 All at ###SITENAME### 1973 ###SITEURL###' 1974 ); 1975 1976 $pass_change_email = array( 1977 'to' => $user['user_email'], 1978 /* translators: Password change notification email subject. %s: Site name */ 1979 'subject' => __( '[%s] Password Changed' ), 1980 'message' => $pass_change_text, 1981 'headers' => '', 1982 ); 1983 1984 /** 1985 * Filters the contents of the email sent when the user's password is changed. 1986 * 1987 * @since 4.3.0 1988 * 1989 * @param array $pass_change_email { 1990 * Used to build wp_mail(). 1991 * @type string $to The intended recipients. Add emails in a comma separated string. 1992 * @type string $subject The subject of the email. 1993 * @type string $message The content of the email. 1994 * The following strings have a special meaning and will get replaced dynamically: 1995 * - ###USERNAME### The current user's username. 1996 * - ###ADMIN_EMAIL### The admin email in case this was unexpected. 1997 * - ###EMAIL### The user's email address. 1998 * - ###SITENAME### The name of the site. 1999 * - ###SITEURL### The URL to the site. 2000 * @type string $headers Headers. Add headers in a newline (\r\n) separated string. 2001 * } 2002 * @param array $user The original user array. 2003 * @param array $userdata The updated user array. 2004 */ 2005 $pass_change_email = apply_filters( 'password_change_email', $pass_change_email, $user, $userdata ); 2006 2007 $pass_change_email['message'] = str_replace( '###USERNAME###', $user['user_login'], $pass_change_email['message'] ); 2008 $pass_change_email['message'] = str_replace( '###ADMIN_EMAIL###', get_option( 'admin_email' ), $pass_change_email['message'] ); 2009 $pass_change_email['message'] = str_replace( '###EMAIL###', $user['user_email'], $pass_change_email['message'] ); 2010 $pass_change_email['message'] = str_replace( '###SITENAME###', $blog_name, $pass_change_email['message'] ); 2011 $pass_change_email['message'] = str_replace( '###SITEURL###', home_url(), $pass_change_email['message'] ); 2012 2013 wp_mail( $pass_change_email['to'], sprintf( $pass_change_email['subject'], $blog_name ), $pass_change_email['message'], $pass_change_email['headers'] ); 2014 } 2015 2016 if ( ! empty( $send_email_change_email ) ) { 2017 /* translators: Do not translate USERNAME, ADMIN_EMAIL, NEW_EMAIL, EMAIL, SITENAME, SITEURL: those are placeholders. */ 2018 $email_change_text = __( 2019 'Hi ###USERNAME###, 2020 2021 This notice confirms that your email address on ###SITENAME### was changed to ###NEW_EMAIL###. 2022 2023 If you did not change your email, please contact the Site Administrator at 2024 ###ADMIN_EMAIL### 2025 2026 This email has been sent to ###EMAIL### 2027 2028 Regards, 2029 All at ###SITENAME### 2030 ###SITEURL###' 2031 ); 2032 2033 $email_change_email = array( 2034 'to' => $user['user_email'], 2035 /* translators: Email change notification email subject. %s: Site name */ 2036 'subject' => __( '[%s] Email Changed' ), 2037 'message' => $email_change_text, 2038 'headers' => '', 2039 ); 2040 2041 /** 2042 * Filters the contents of the email sent when the user's email is changed. 2043 * 2044 * @since 4.3.0 2045 * 2046 * @param array $email_change_email { 2047 * Used to build wp_mail(). 2048 * @type string $to The intended recipients. 2049 * @type string $subject The subject of the email. 2050 * @type string $message The content of the email. 2051 * The following strings have a special meaning and will get replaced dynamically: 2052 * - ###USERNAME### The current user's username. 2053 * - ###ADMIN_EMAIL### The admin email in case this was unexpected. 2054 * - ###NEW_EMAIL### The new email address. 2055 * - ###EMAIL### The old email address. 2056 * - ###SITENAME### The name of the site. 2057 * - ###SITEURL### The URL to the site. 2058 * @type string $headers Headers. 2059 * } 2060 * @param array $user The original user array. 2061 * @param array $userdata The updated user array. 2062 */ 2063 $email_change_email = apply_filters( 'email_change_email', $email_change_email, $user, $userdata ); 2064 2065 $email_change_email['message'] = str_replace( '###USERNAME###', $user['user_login'], $email_change_email['message'] ); 2066 $email_change_email['message'] = str_replace( '###ADMIN_EMAIL###', get_option( 'admin_email' ), $email_change_email['message'] ); 2067 $email_change_email['message'] = str_replace( '###NEW_EMAIL###', $userdata['user_email'], $email_change_email['message'] ); 2068 $email_change_email['message'] = str_replace( '###EMAIL###', $user['user_email'], $email_change_email['message'] ); 2069 $email_change_email['message'] = str_replace( '###SITENAME###', $blog_name, $email_change_email['message'] ); 2070 $email_change_email['message'] = str_replace( '###SITEURL###', home_url(), $email_change_email['message'] ); 2071 2072 wp_mail( $email_change_email['to'], sprintf( $email_change_email['subject'], $blog_name ), $email_change_email['message'], $email_change_email['headers'] ); 2073 } 2074 2075 if ( $switched_locale ) { 2076 restore_previous_locale(); 2077 } 2078 } 2079 2080 // Update the cookies if the password changed. 2081 $current_user = wp_get_current_user(); 2082 if ( $current_user->ID == $ID ) { 2083 if ( isset( $plaintext_pass ) ) { 2084 wp_clear_auth_cookie(); 2085 2086 // Here we calculate the expiration length of the current auth cookie and compare it to the default expiration. 2087 // If it's greater than this, then we know the user checked 'Remember Me' when they logged in. 2088 $logged_in_cookie = wp_parse_auth_cookie( '', 'logged_in' ); 2089 /** This filter is documented in wp-includes/pluggable.php */ 2090 $default_cookie_life = apply_filters( 'auth_cookie_expiration', ( 2 * DAY_IN_SECONDS ), $ID, false ); 2091 $remember = false; 2092 if ( false !== $logged_in_cookie && ( $logged_in_cookie['expiration'] - time() ) > $default_cookie_life ) { 2093 $remember = true; 2094 } 2095 2096 wp_set_auth_cookie( $ID, $remember ); 2097 } 2098 } 2099 2100 return $user_id; 2101 } 2102 2103 /** 2104 * A simpler way of inserting a user into the database. 2105 * 2106 * Creates a new user with just the username, password, and email. For more 2107 * complex user creation use wp_insert_user() to specify more information. 2108 * 2109 * @since 2.0.0 2110 * @see wp_insert_user() More complete way to create a new user 2111 * 2112 * @param string $username The user's username. 2113 * @param string $password The user's password. 2114 * @param string $email Optional. The user's email. Default empty. 2115 * @return int|WP_Error The newly created user's ID or a WP_Error object if the user could not 2116 * be created. 2117 */ 2118 function wp_create_user( $username, $password, $email = '' ) { 2119 $user_login = wp_slash( $username ); 2120 $user_email = wp_slash( $email ); 2121 $user_pass = $password; 2122 2123 $userdata = compact( 'user_login', 'user_email', 'user_pass' ); 2124 return wp_insert_user( $userdata ); 2125 } 2126 2127 /** 2128 * Returns a list of meta keys to be (maybe) populated in wp_update_user(). 2129 * 2130 * The list of keys returned via this function are dependent on the presence 2131 * of those keys in the user meta data to be set. 2132 * 2133 * @since 3.3.0 2134 * @access private 2135 * 2136 * @param WP_User $user WP_User instance. 2137 * @return array List of user keys to be populated in wp_update_user(). 2138 */ 2139 function _get_additional_user_keys( $user ) { 2140 $keys = array( 'first_name', 'last_name', 'nickname', 'description', 'rich_editing', 'syntax_highlighting', 'comment_shortcuts', 'admin_color', 'use_ssl', 'show_admin_bar_front', 'locale' ); 2141 return array_merge( $keys, array_keys( wp_get_user_contact_methods( $user ) ) ); 2142 } 2143 2144 /** 2145 * Set up the user contact methods. 2146 * 2147 * Default contact methods were removed in 3.6. A filter dictates contact methods. 2148 * 2149 * @since 3.7.0 2150 * 2151 * @param WP_User $user Optional. WP_User object. 2152 * @return array Array of contact methods and their labels. 2153 */ 2154 function wp_get_user_contact_methods( $user = null ) { 2155 $methods = array(); 2156 if ( get_site_option( 'initial_db_version' ) < 23588 ) { 2157 $methods = array( 2158 'aim' => __( 'AIM' ), 2159 'yim' => __( 'Yahoo IM' ), 2160 'jabber' => __( 'Jabber / Google Talk' ), 2161 ); 2162 } 2163 2164 /** 2165 * Filters the user contact methods. 2166 * 2167 * @since 2.9.0 2168 * 2169 * @param array $methods Array of contact methods and their labels. 2170 * @param WP_User $user WP_User object. 2171 */ 2172 return apply_filters( 'user_contactmethods', $methods, $user ); 2173 } 2174 2175 /** 2176 * The old private function for setting up user contact methods. 2177 * 2178 * Use wp_get_user_contact_methods() instead. 2179 * 2180 * @since 2.9.0 2181 * @access private 2182 * 2183 * @param WP_User $user Optional. WP_User object. Default null. 2184 * @return array Array of contact methods and their labels. 2185 */ 2186 function _wp_get_user_contactmethods( $user = null ) { 2187 return wp_get_user_contact_methods( $user ); 2188 } 2189 2190 /** 2191 * Gets the text suggesting how to create strong passwords. 2192 * 2193 * @since 4.1.0 2194 * 2195 * @return string The password hint text. 2196 */ 2197 function wp_get_password_hint() { 2198 $hint = __( 'Hint: The password should be at least twelve characters long. To make it stronger, use upper and lower case letters, numbers, and symbols like ! " ? $ % ^ & ).' ); 2199 2200 /** 2201 * Filters the text describing the site's password complexity policy. 2202 * 2203 * @since 4.1.0 2204 * 2205 * @param string $hint The password hint text. 2206 */ 2207 return apply_filters( 'password_hint', $hint ); 2208 } 2209 2210 /** 2211 * Creates, stores, then returns a password reset key for user. 2212 * 2213 * @since 4.4.0 2214 * 2215 * @global wpdb $wpdb WordPress database abstraction object. 2216 * @global PasswordHash $wp_hasher Portable PHP password hashing framework. 2217 * 2218 * @param WP_User $user User to retrieve password reset key for. 2219 * 2220 * @return string|WP_Error Password reset key on success. WP_Error on error. 2221 */ 2222 function get_password_reset_key( $user ) { 2223 global $wpdb, $wp_hasher; 2224 2225 if ( ! ( $user instanceof WP_User ) ) { 2226 return new WP_Error( 'invalidcombo', __( '<strong>ERROR</strong>: There is no account with that username or email address.' ) ); 2227 } 2228 2229 /** 2230 * Fires before a new password is retrieved. 2231 * 2232 * Use the {@see 'retrieve_password'} hook instead. 2233 * 2234 * @since 1.5.0 2235 * @deprecated 1.5.1 Misspelled. Use 'retrieve_password' hook instead. 2236 * 2237 * @param string $user_login The user login name. 2238 */ 2239 do_action( 'retreive_password', $user->user_login ); 2240 2241 /** 2242 * Fires before a new password is retrieved. 2243 * 2244 * @since 1.5.1 2245 * 2246 * @param string $user_login The user login name. 2247 */ 2248 do_action( 'retrieve_password', $user->user_login ); 2249 2250 $allow = true; 2251 if ( is_multisite() && is_user_spammy( $user ) ) { 2252 $allow = false; 2253 } 2254 2255 /** 2256 * Filters whether to allow a password to be reset. 2257 * 2258 * @since 2.7.0 2259 * 2260 * @param bool $allow Whether to allow the password to be reset. Default true. 2261 * @param int $user_data->ID The ID of the user attempting to reset a password. 2262 */ 2263 $allow = apply_filters( 'allow_password_reset', $allow, $user->ID ); 2264 2265 if ( ! $allow ) { 2266 return new WP_Error( 'no_password_reset', __( 'Password reset is not allowed for this user' ) ); 2267 } elseif ( is_wp_error( $allow ) ) { 2268 return $allow; 2269 } 2270 2271 // Generate something random for a password reset key. 2272 $key = wp_generate_password( 20, false ); 2273 2274 /** 2275 * Fires when a password reset key is generated. 2276 * 2277 * @since 2.5.0 2278 * 2279 * @param string $user_login The username for the user. 2280 * @param string $key The generated password reset key. 2281 */ 2282 do_action( 'retrieve_password_key', $user->user_login, $key ); 2283 2284 // Now insert the key, hashed, into the DB. 2285 if ( empty( $wp_hasher ) ) { 2286 require_once ABSPATH . WPINC . '/class-phpass.php'; 2287 $wp_hasher = new PasswordHash( 8, true ); 2288 } 2289 $hashed = time() . ':' . $wp_hasher->HashPassword( $key ); 2290 $key_saved = $wpdb->update( $wpdb->users, array( 'user_activation_key' => $hashed ), array( 'user_login' => $user->user_login ) ); 2291 if ( false === $key_saved ) { 2292 return new WP_Error( 'no_password_key_update', __( 'Could not save password reset key to database.' ) ); 2293 } 2294 2295 return $key; 2296 } 2297 2298 /** 2299 * Retrieves a user row based on password reset key and login 2300 * 2301 * A key is considered 'expired' if it exactly matches the value of the 2302 * user_activation_key field, rather than being matched after going through the 2303 * hashing process. This field is now hashed; old values are no longer accepted 2304 * but have a different WP_Error code so good user feedback can be provided. 2305 * 2306 * @since 3.1.0 2307 * 2308 * @global wpdb $wpdb WordPress database object for queries. 2309 * @global PasswordHash $wp_hasher Portable PHP password hashing framework instance. 2310 * 2311 * @param string $key Hash to validate sending user's password. 2312 * @param string $login The user login. 2313 * @return WP_User|WP_Error WP_User object on success, WP_Error object for invalid or expired keys. 2314 */ 2315 function check_password_reset_key( $key, $login ) { 2316 global $wpdb, $wp_hasher; 2317 2318 $key = preg_replace( '/[^a-z0-9]/i', '', $key ); 2319 2320 if ( empty( $key ) || ! is_string( $key ) ) { 2321 return new WP_Error( 'invalid_key', __( 'Invalid key.' ) ); 2322 } 2323 2324 if ( empty( $login ) || ! is_string( $login ) ) { 2325 return new WP_Error( 'invalid_key', __( 'Invalid key.' ) ); 2326 } 2327 2328 $row = $wpdb->get_row( $wpdb->prepare( "SELECT ID, user_activation_key FROM $wpdb->users WHERE user_login = %s", $login ) ); 2329 if ( ! $row ) { 2330 return new WP_Error( 'invalid_key', __( 'Invalid key.' ) ); 2331 } 2332 2333 if ( empty( $wp_hasher ) ) { 2334 require_once ABSPATH . WPINC . '/class-phpass.php'; 2335 $wp_hasher = new PasswordHash( 8, true ); 2336 } 2337 2338 /** 2339 * Filters the expiration time of password reset keys. 2340 * 2341 * @since 4.3.0 2342 * 2343 * @param int $expiration The expiration time in seconds. 2344 */ 2345 $expiration_duration = apply_filters( 'password_reset_expiration', DAY_IN_SECONDS ); 2346 2347 if ( false !== strpos( $row->user_activation_key, ':' ) ) { 2348 list( $pass_request_time, $pass_key ) = explode( ':', $row->user_activation_key, 2 ); 2349 $expiration_time = $pass_request_time + $expiration_duration; 2350 } else { 2351 $pass_key = $row->user_activation_key; 2352 $expiration_time = false; 2353 } 2354 2355 if ( ! $pass_key ) { 2356 return new WP_Error( 'invalid_key', __( 'Invalid key.' ) ); 2357 } 2358 2359 $hash_is_correct = $wp_hasher->CheckPassword( $key, $pass_key ); 2360 2361 if ( $hash_is_correct && $expiration_time && time() < $expiration_time ) { 2362 return get_userdata( $row->ID ); 2363 } elseif ( $hash_is_correct && $expiration_time ) { 2364 // Key has an expiration time that's passed 2365 return new WP_Error( 'expired_key', __( 'Invalid key.' ) ); 2366 } 2367 2368 if ( hash_equals( $row->user_activation_key, $key ) || ( $hash_is_correct && ! $expiration_time ) ) { 2369 $return = new WP_Error( 'expired_key', __( 'Invalid key.' ) ); 2370 $user_id = $row->ID; 2371 2372 /** 2373 * Filters the return value of check_password_reset_key() when an 2374 * old-style key is used. 2375 * 2376 * @since 3.7.0 Previously plain-text keys were stored in the database. 2377 * @since 4.3.0 Previously key hashes were stored without an expiration time. 2378 * 2379 * @param WP_Error $return A WP_Error object denoting an expired key. 2380 * Return a WP_User object to validate the key. 2381 * @param int $user_id The matched user ID. 2382 */ 2383 return apply_filters( 'password_reset_key_expired', $return, $user_id ); 2384 } 2385 2386 return new WP_Error( 'invalid_key', __( 'Invalid key.' ) ); 2387 } 2388 2389 /** 2390 * Handles resetting the user's password. 2391 * 2392 * @since 2.5.0 2393 * 2394 * @param WP_User $user The user 2395 * @param string $new_pass New password for the user in plaintext 2396 */ 2397 function reset_password( $user, $new_pass ) { 2398 /** 2399 * Fires before the user's password is reset. 2400 * 2401 * @since 1.5.0 2402 * 2403 * @param object $user The user. 2404 * @param string $new_pass New user password. 2405 */ 2406 do_action( 'password_reset', $user, $new_pass ); 2407 2408 wp_set_password( $new_pass, $user->ID ); 2409 update_user_option( $user->ID, 'default_password_nag', false, true ); 2410 2411 /** 2412 * Fires after the user's password is reset. 2413 * 2414 * @since 4.4.0 2415 * 2416 * @param WP_User $user The user. 2417 * @param string $new_pass New user password. 2418 */ 2419 do_action( 'after_password_reset', $user, $new_pass ); 2420 } 2421 2422 /** 2423 * Handles registering a new user. 2424 * 2425 * @since 2.5.0 2426 * 2427 * @param string $user_login User's username for logging in 2428 * @param string $user_email User's email address to send password and add 2429 * @return int|WP_Error Either user's ID or error on failure. 2430 */ 2431 function register_new_user( $user_login, $user_email ) { 2432 $errors = new WP_Error(); 2433 2434 $sanitized_user_login = sanitize_user( $user_login ); 2435 /** 2436 * Filters the email address of a user being registered. 2437 * 2438 * @since 2.1.0 2439 * 2440 * @param string $user_email The email address of the new user. 2441 */ 2442 $user_email = apply_filters( 'user_registration_email', $user_email ); 2443 2444 // Check the username 2445 if ( $sanitized_user_login == '' ) { 2446 $errors->add( 'empty_username', __( '<strong>ERROR</strong>: Please enter a username.' ) ); 2447 } elseif ( ! validate_username( $user_login ) ) { 2448 $errors->add( 'invalid_username', __( '<strong>ERROR</strong>: This username is invalid because it uses illegal characters. Please enter a valid username.' ) ); 2449 $sanitized_user_login = ''; 2450 } elseif ( username_exists( $sanitized_user_login ) ) { 2451 $errors->add( 'username_exists', __( '<strong>ERROR</strong>: This username is already registered. Please choose another one.' ) ); 2452 2453 } else { 2454 /** This filter is documented in wp-includes/user.php */ 2455 $illegal_user_logins = array_map( 'strtolower', (array) apply_filters( 'illegal_user_logins', array() ) ); 2456 if ( in_array( strtolower( $sanitized_user_login ), $illegal_user_logins ) ) { 2457 $errors->add( 'invalid_username', __( '<strong>ERROR</strong>: Sorry, that username is not allowed.' ) ); 2458 } 2459 } 2460 2461 // Check the email address 2462 if ( $user_email == '' ) { 2463 $errors->add( 'empty_email', __( '<strong>ERROR</strong>: Please type your email address.' ) ); 2464 } elseif ( ! is_email( $user_email ) ) { 2465 $errors->add( 'invalid_email', __( '<strong>ERROR</strong>: The email address isn’t correct.' ) ); 2466 $user_email = ''; 2467 } elseif ( email_exists( $user_email ) ) { 2468 $errors->add( 'email_exists', __( '<strong>ERROR</strong>: This email is already registered, please choose another one.' ) ); 2469 } 2470 2471 /** 2472 * Fires when submitting registration form data, before the user is created. 2473 * 2474 * @since 2.1.0 2475 * 2476 * @param string $sanitized_user_login The submitted username after being sanitized. 2477 * @param string $user_email The submitted email. 2478 * @param WP_Error $errors Contains any errors with submitted username and email, 2479 * e.g., an empty field, an invalid username or email, 2480 * or an existing username or email. 2481 */ 2482 do_action( 'register_post', $sanitized_user_login, $user_email, $errors ); 2483 2484 /** 2485 * Filters the errors encountered when a new user is being registered. 2486 * 2487 * The filtered WP_Error object may, for example, contain errors for an invalid 2488 * or existing username or email address. A WP_Error object should always returned, 2489 * but may or may not contain errors. 2490 * 2491 * If any errors are present in $errors, this will abort the user's registration. 2492 * 2493 * @since 2.1.0 2494 * 2495 * @param WP_Error $errors A WP_Error object containing any errors encountered 2496 * during registration. 2497 * @param string $sanitized_user_login User's username after it has been sanitized. 2498 * @param string $user_email User's email. 2499 */ 2500 $errors = apply_filters( 'registration_errors', $errors, $sanitized_user_login, $user_email ); 2501 2502 if ( $errors->has_errors() ) { 2503 return $errors; 2504 } 2505 2506 $user_pass = wp_generate_password( 12, false ); 2507 $user_id = wp_create_user( $sanitized_user_login, $user_pass, $user_email ); 2508 if ( ! $user_id || is_wp_error( $user_id ) ) { 2509 $errors->add( 'registerfail', sprintf( __( '<strong>ERROR</strong>: Couldn’t register you… please contact the <a href="mailto:%s">webmaster</a> !' ), get_option( 'admin_email' ) ) ); 2510 return $errors; 2511 } 2512 2513 update_user_option( $user_id, 'default_password_nag', true, true ); //Set up the Password change nag. 2514 2515 /** 2516 * Fires after a new user registration has been recorded. 2517 * 2518 * @since 4.4.0 2519 * 2520 * @param int $user_id ID of the newly registered user. 2521 */ 2522 do_action( 'register_new_user', $user_id ); 2523 2524 return $user_id; 2525 } 2526 2527 /** 2528 * Initiates email notifications related to the creation of new users. 2529 * 2530 * Notifications are sent both to the site admin and to the newly created user. 2531 * 2532 * @since 4.4.0 2533 * @since 4.6.0 Converted the `$notify` parameter to accept 'user' for sending 2534 * notifications only to the user created. 2535 * 2536 * @param int $user_id ID of the newly created user. 2537 * @param string $notify Optional. Type of notification that should happen. Accepts 'admin' 2538 * or an empty string (admin only), 'user', or 'both' (admin and user). 2539 * Default 'both'. 2540 */ 2541 function wp_send_new_user_notifications( $user_id, $notify = 'both' ) { 2542 wp_new_user_notification( $user_id, null, $notify ); 2543 } 2544 2545 /** 2546 * Retrieve the current session token from the logged_in cookie. 2547 * 2548 * @since 4.0.0 2549 * 2550 * @return string Token. 2551 */ 2552 function wp_get_session_token() { 2553 $cookie = wp_parse_auth_cookie( '', 'logged_in' ); 2554 return ! empty( $cookie['token'] ) ? $cookie['token'] : ''; 2555 } 2556 2557 /** 2558 * Retrieve a list of sessions for the current user. 2559 * 2560 * @since 4.0.0 2561 * @return array Array of sessions. 2562 */ 2563 function wp_get_all_sessions() { 2564 $manager = WP_Session_Tokens::get_instance( get_current_user_id() ); 2565 return $manager->get_all(); 2566 } 2567 2568 /** 2569 * Remove the current session token from the database. 2570 * 2571 * @since 4.0.0 2572 */ 2573 function wp_destroy_current_session() { 2574 $token = wp_get_session_token(); 2575 if ( $token ) { 2576 $manager = WP_Session_Tokens::get_instance( get_current_user_id() ); 2577 $manager->destroy( $token ); 2578 } 2579 } 2580 2581 /** 2582 * Remove all but the current session token for the current user for the database. 2583 * 2584 * @since 4.0.0 2585 */ 2586 function wp_destroy_other_sessions() { 2587 $token = wp_get_session_token(); 2588 if ( $token ) { 2589 $manager = WP_Session_Tokens::get_instance( get_current_user_id() ); 2590 $manager->destroy_others( $token ); 2591 } 2592 } 2593 2594 /** 2595 * Remove all session tokens for the current user from the database. 2596 * 2597 * @since 4.0.0 2598 */ 2599 function wp_destroy_all_sessions() { 2600 $manager = WP_Session_Tokens::get_instance( get_current_user_id() ); 2601 $manager->destroy_all(); 2602 } 2603 2604 /** 2605 * Get the user IDs of all users with no role on this site. 2606 * 2607 * @since 4.4.0 2608 * @since 4.9.0 The `$site_id` parameter was added to support multisite. 2609 * 2610 * @param int|null $site_id Optional. The site ID to get users with no role for. Defaults to the current site. 2611 * @return array Array of user IDs. 2612 */ 2613 function wp_get_users_with_no_role( $site_id = null ) { 2614 global $wpdb; 2615 2616 if ( ! $site_id ) { 2617 $site_id = get_current_blog_id(); 2618 } 2619 2620 $prefix = $wpdb->get_blog_prefix( $site_id ); 2621 2622 if ( is_multisite() && $site_id != get_current_blog_id() ) { 2623 switch_to_blog( $site_id ); 2624 $role_names = wp_roles()->get_names(); 2625 restore_current_blog(); 2626 } else { 2627 $role_names = wp_roles()->get_names(); 2628 } 2629 2630 $regex = implode( '|', array_keys( $role_names ) ); 2631 $regex = preg_replace( '/[^a-zA-Z_\|-]/', '', $regex ); 2632 $users = $wpdb->get_col( 2633 $wpdb->prepare( 2634 " 2635 SELECT user_id 2636 FROM $wpdb->usermeta 2637 WHERE meta_key = '{$prefix}capabilities' 2638 AND meta_value NOT REGEXP %s 2639 ", 2640 $regex 2641 ) 2642 ); 2643 2644 return $users; 2645 } 2646 2647 /** 2648 * Retrieves the current user object. 2649 * 2650 * Will set the current user, if the current user is not set. The current user 2651 * will be set to the logged-in person. If no user is logged-in, then it will 2652 * set the current user to 0, which is invalid and won't have any permissions. 2653 * 2654 * This function is used by the pluggable functions wp_get_current_user() and 2655 * get_currentuserinfo(), the latter of which is deprecated but used for backward 2656 * compatibility. 2657 * 2658 * @since 4.5.0 2659 * @access private 2660 * 2661 * @see wp_get_current_user() 2662 * @global WP_User $current_user Checks if the current user is set. 2663 * 2664 * @return WP_User Current WP_User instance. 2665 */ 2666 function _wp_get_current_user() { 2667 global $current_user; 2668 2669 if ( ! empty( $current_user ) ) { 2670 if ( $current_user instanceof WP_User ) { 2671 return $current_user; 2672 } 2673 2674 // Upgrade stdClass to WP_User 2675 if ( is_object( $current_user ) && isset( $current_user->ID ) ) { 2676 $cur_id = $current_user->ID; 2677 $current_user = null; 2678 wp_set_current_user( $cur_id ); 2679 return $current_user; 2680 } 2681 2682 // $current_user has a junk value. Force to WP_User with ID 0. 2683 $current_user = null; 2684 wp_set_current_user( 0 ); 2685 return $current_user; 2686 } 2687 2688 if ( defined( 'XMLRPC_REQUEST' ) && XMLRPC_REQUEST ) { 2689 wp_set_current_user( 0 ); 2690 return $current_user; 2691 } 2692 2693 /** 2694 * Filters the current user. 2695 * 2696 * The default filters use this to determine the current user from the 2697 * request's cookies, if available. 2698 * 2699 * Returning a value of false will effectively short-circuit setting 2700 * the current user. 2701 * 2702 * @since 3.9.0 2703 * 2704 * @param int|bool $user_id User ID if one has been determined, false otherwise. 2705 */ 2706 $user_id = apply_filters( 'determine_current_user', false ); 2707 if ( ! $user_id ) { 2708 wp_set_current_user( 0 ); 2709 return $current_user; 2710 } 2711 2712 wp_set_current_user( $user_id ); 2713 2714 return $current_user; 2715 } 2716 2717 /** 2718 * Send a confirmation request email when a change of user email address is attempted. 2719 * 2720 * @since 3.0.0 2721 * @since 4.9.0 This function was moved from wp-admin/includes/ms.php so it's no longer Multisite specific. 2722 * 2723 * @global WP_Error $errors WP_Error object. 2724 */ 2725 function send_confirmation_on_profile_email() { 2726 global $errors; 2727 2728 $current_user = wp_get_current_user(); 2729 if ( ! is_object( $errors ) ) { 2730 $errors = new WP_Error(); 2731 } 2732 2733 if ( $current_user->ID != $_POST['user_id'] ) { 2734 return false; 2735 } 2736 2737 if ( $current_user->user_email != $_POST['email'] ) { 2738 if ( ! is_email( $_POST['email'] ) ) { 2739 $errors->add( 2740 'user_email', 2741 __( '<strong>ERROR</strong>: The email address isn’t correct.' ), 2742 array( 2743 'form-field' => 'email', 2744 ) 2745 ); 2746 2747 return; 2748 } 2749 2750 if ( email_exists( $_POST['email'] ) ) { 2751 $errors->add( 2752 'user_email', 2753 __( '<strong>ERROR</strong>: The email address is already used.' ), 2754 array( 2755 'form-field' => 'email', 2756 ) 2757 ); 2758 delete_user_meta( $current_user->ID, '_new_email' ); 2759 2760 return; 2761 } 2762 2763 $hash = md5( $_POST['email'] . time() . wp_rand() ); 2764 $new_user_email = array( 2765 'hash' => $hash, 2766 'newemail' => $_POST['email'], 2767 ); 2768 update_user_meta( $current_user->ID, '_new_email', $new_user_email ); 2769 2770 $sitename = wp_specialchars_decode( get_option( 'blogname' ), ENT_QUOTES ); 2771 2772 /* translators: Do not translate USERNAME, ADMIN_URL, EMAIL, SITENAME, SITEURL: those are placeholders. */ 2773 $email_text = __( 2774 'Howdy ###USERNAME###, 2775 2776 You recently requested to have the email address on your account changed. 2777 2778 If this is correct, please click on the following link to change it: 2779 ###ADMIN_URL### 2780 2781 You can safely ignore and delete this email if you do not want to 2782 take this action. 2783 2784 This email has been sent to ###EMAIL### 2785 2786 Regards, 2787 All at ###SITENAME### 2788 ###SITEURL###' 2789 ); 2790 2791 /** 2792 * Filters the text of the email sent when a change of user email address is attempted. 2793 * 2794 * The following strings have a special meaning and will get replaced dynamically: 2795 * ###USERNAME### The current user's username. 2796 * ###ADMIN_URL### The link to click on to confirm the email change. 2797 * ###EMAIL### The new email. 2798 * ###SITENAME### The name of the site. 2799 * ###SITEURL### The URL to the site. 2800 * 2801 * @since MU (3.0.0) 2802 * @since 4.9.0 This filter is no longer Multisite specific. 2803 * 2804 * @param string $email_text Text in the email. 2805 * @param array $new_user_email { 2806 * Data relating to the new user email address. 2807 * 2808 * @type string $hash The secure hash used in the confirmation link URL. 2809 * @type string $newemail The proposed new email address. 2810 * } 2811 */ 2812 $content = apply_filters( 'new_user_email_content', $email_text, $new_user_email ); 2813 2814 $content = str_replace( '###USERNAME###', $current_user->user_login, $content ); 2815 $content = str_replace( '###ADMIN_URL###', esc_url( admin_url( 'profile.php?newuseremail=' . $hash ) ), $content ); 2816 $content = str_replace( '###EMAIL###', $_POST['email'], $content ); 2817 $content = str_replace( '###SITENAME###', $sitename, $content ); 2818 $content = str_replace( '###SITEURL###', home_url(), $content ); 2819 2820 /* translators: New email address notification email subject. %s: Site name */ 2821 wp_mail( $_POST['email'], sprintf( __( '[%s] Email Change Request' ), $sitename ), $content ); 2822 2823 $_POST['email'] = $current_user->user_email; 2824 } 2825 } 2826 2827 /** 2828 * Adds an admin notice alerting the user to check for confirmation request email 2829 * after email address change. 2830 * 2831 * @since 3.0.0 2832 * @since 4.9.0 This function was moved from wp-admin/includes/ms.php so it's no longer Multisite specific. 2833 * 2834 * @global string $pagenow 2835 */ 2836 function new_user_email_admin_notice() { 2837 global $pagenow; 2838 2839 if ( 'profile.php' === $pagenow && isset( $_GET['updated'] ) ) { 2840 $email = get_user_meta( get_current_user_id(), '_new_email', true ); 2841 if ( $email ) { 2842 /* translators: %s: New email address */ 2843 echo '<div class="notice notice-info"><p>' . sprintf( __( 'Your email address has not been updated yet. Please check your inbox at %s for a confirmation email.' ), '<code>' . esc_html( $email['newemail'] ) . '</code>' ) . '</p></div>'; 2844 } 2845 } 2846 } 2847 2848 /** 2849 * Get all user privacy request types. 2850 * 2851 * @since 4.9.6 2852 * @access private 2853 * 2854 * @return array List of core privacy action types. 2855 */ 2856 function _wp_privacy_action_request_types() { 2857 return array( 2858 'export_personal_data', 2859 'remove_personal_data', 2860 ); 2861 } 2862 2863 /** 2864 * Registers the personal data exporter for users. 2865 * 2866 * @since 4.9.6 2867 * 2868 * @param array $exporters An array of personal data exporters. 2869 * @return array An array of personal data exporters. 2870 */ 2871 function wp_register_user_personal_data_exporter( $exporters ) { 2872 $exporters['wordpress-user'] = array( 2873 'exporter_friendly_name' => __( 'WordPress User' ), 2874 'callback' => 'wp_user_personal_data_exporter', 2875 ); 2876 2877 return $exporters; 2878 } 2879 2880 /** 2881 * Finds and exports personal data associated with an email address from the user and user_meta table. 2882 * 2883 * @since 4.9.6 2884 * 2885 * @param string $email_address The users email address. 2886 * @return array An array of personal data. 2887 */ 2888 function wp_user_personal_data_exporter( $email_address ) { 2889 $email_address = trim( $email_address ); 2890 2891 $data_to_export = array(); 2892 2893 $user = get_user_by( 'email', $email_address ); 2894 2895 if ( ! $user ) { 2896 return array( 2897 'data' => array(), 2898 'done' => true, 2899 ); 2900 } 2901 2902 $user_meta = get_user_meta( $user->ID ); 2903 2904 $user_prop_to_export = array( 2905 'ID' => __( 'User ID' ), 2906 'user_login' => __( 'User Login Name' ), 2907 'user_nicename' => __( 'User Nice Name' ), 2908 'user_email' => __( 'User Email' ), 2909 'user_url' => __( 'User URL' ), 2910 'user_registered' => __( 'User Registration Date' ), 2911 'display_name' => __( 'User Display Name' ), 2912 'nickname' => __( 'User Nickname' ), 2913 'first_name' => __( 'User First Name' ), 2914 'last_name' => __( 'User Last Name' ), 2915 'description' => __( 'User Description' ), 2916 ); 2917 2918 $user_data_to_export = array(); 2919 2920 foreach ( $user_prop_to_export as $key => $name ) { 2921 $value = ''; 2922 2923 switch ( $key ) { 2924 case 'ID': 2925 case 'user_login': 2926 case 'user_nicename': 2927 case 'user_email': 2928 case 'user_url': 2929 case 'user_registered': 2930 case 'display_name': 2931 $value = $user->data->$key; 2932 break; 2933 case 'nickname': 2934 case 'first_name': 2935 case 'last_name': 2936 case 'description': 2937 $value = $user_meta[ $key ][0]; 2938 break; 2939 } 2940 2941 if ( ! empty( $value ) ) { 2942 $user_data_to_export[] = array( 2943 'name' => $name, 2944 'value' => $value, 2945 ); 2946 } 2947 } 2948 2949 $data_to_export[] = array( 2950 'group_id' => 'user', 2951 'group_label' => __( 'User' ), 2952 'item_id' => "user-{$user->ID}", 2953 'data' => $user_data_to_export, 2954 ); 2955 2956 return array( 2957 'data' => $data_to_export, 2958 'done' => true, 2959 ); 2960 } 2961 2962 /** 2963 * Update log when privacy request is confirmed. 2964 * 2965 * @since 4.9.6 2966 * @access private 2967 * 2968 * @param int $request_id ID of the request. 2969 */ 2970 function _wp_privacy_account_request_confirmed( $request_id ) { 2971 $request = wp_get_user_request_data( $request_id ); 2972 2973 if ( ! $request ) { 2974 return; 2975 } 2976 2977 if ( ! in_array( $request->status, array( 'request-pending', 'request-failed' ), true ) ) { 2978 return; 2979 } 2980 2981 update_post_meta( $request_id, '_wp_user_request_confirmed_timestamp', time() ); 2982 wp_update_post( 2983 array( 2984 'ID' => $request_id, 2985 'post_status' => 'request-confirmed', 2986 ) 2987 ); 2988 } 2989 2990 /** 2991 * Notify the site administrator via email when a request is confirmed. 2992 * 2993 * Without this, the admin would have to manually check the site to see if any 2994 * action was needed on their part yet. 2995 * 2996 * @since 4.9.6 2997 * 2998 * @param int $request_id The ID of the request. 2999 */ 3000 function _wp_privacy_send_request_confirmation_notification( $request_id ) { 3001 $request = wp_get_user_request_data( $request_id ); 3002 3003 if ( ! is_a( $request, 'WP_User_Request' ) || 'request-confirmed' !== $request->status ) { 3004 return; 3005 } 3006 3007 $already_notified = (bool) get_post_meta( $request_id, '_wp_admin_notified', true ); 3008 3009 if ( $already_notified ) { 3010 return; 3011 } 3012 3013 $manage_url = add_query_arg( 'page', $request->action_name, admin_url( 'tools.php' ) ); 3014 $action_description = wp_user_request_action_description( $request->action_name ); 3015 3016 /** 3017 * Filters the recipient of the data request confirmation notification. 3018 * 3019 * In a Multisite environment, this will default to the email address of the 3020 * network admin because, by default, single site admins do not have the 3021 * capabilities required to process requests. Some networks may wish to 3022 * delegate those capabilities to a single-site admin, or a dedicated person 3023 * responsible for managing privacy requests. 3024 * 3025 * @since 4.9.6 3026 * 3027 * @param string $admin_email The email address of the notification recipient. 3028 * @param WP_User_Request $request The request that is initiating the notification. 3029 */ 3030 $admin_email = apply_filters( 'user_request_confirmed_email_to', get_site_option( 'admin_email' ), $request ); 3031 3032 $email_data = array( 3033 'request' => $request, 3034 'user_email' => $request->email, 3035 'description' => $action_description, 3036 'manage_url' => $manage_url, 3037 'sitename' => wp_specialchars_decode( get_option( 'blogname' ), ENT_QUOTES ), 3038 'siteurl' => home_url(), 3039 'admin_email' => $admin_email, 3040 ); 3041 3042 /* translators: Do not translate SITENAME, USER_EMAIL, DESCRIPTION, MANAGE_URL, SITEURL; those are placeholders. */ 3043 $email_text = __( 3044 'Howdy, 3045 3046 A user data privacy request has been confirmed on ###SITENAME###: 3047 3048 User: ###USER_EMAIL### 3049 Request: ###DESCRIPTION### 3050 3051 You can view and manage these data privacy requests here: 3052 3053 ###MANAGE_URL### 3054 3055 Regards, 3056 All at ###SITENAME### 3057 ###SITEURL###' 3058 ); 3059 3060 /** 3061 * Filters the body of the user request confirmation email. 3062 * 3063 * The email is sent to an administrator when an user request is confirmed. 3064 * The following strings have a special meaning and will get replaced dynamically: 3065 * 3066 * ###SITENAME### The name of the site. 3067 * ###USER_EMAIL### The user email for the request. 3068 * ###DESCRIPTION### Description of the action being performed so the user knows what the email is for. 3069 * ###MANAGE_URL### The URL to manage requests. 3070 * ###SITEURL### The URL to the site. 3071 * 3072 * @since 4.9.6 3073 * 3074 * @param string $email_text Text in the email. 3075 * @param array $email_data { 3076 * Data relating to the account action email. 3077 * 3078 * @type WP_User_Request $request User request object. 3079 * @type string $user_email The email address confirming a request 3080 * @type string $description Description of the action being performed so the user knows what the email is for. 3081 * @type string $manage_url The link to click manage privacy requests of this type. 3082 * @type string $sitename The site name sending the mail. 3083 * @type string $siteurl The site URL sending the mail. 3084 * @type string $admin_email The administrator email receiving the mail. 3085 * } 3086 */ 3087 $content = apply_filters( 'user_confirmed_action_email_content', $email_text, $email_data ); 3088 3089 $content = str_replace( '###SITENAME###', $email_data['sitename'], $content ); 3090 $content = str_replace( '###USER_EMAIL###', $email_data['user_email'], $content ); 3091 $content = str_replace( '###DESCRIPTION###', $email_data['description'], $content ); 3092 $content = str_replace( '###MANAGE_URL###', esc_url_raw( $email_data['manage_url'] ), $content ); 3093 $content = str_replace( '###SITEURL###', esc_url_raw( $email_data['siteurl'] ), $content ); 3094 3095 $subject = sprintf( 3096 /* translators: Privacy data request confirmed notification email subject. 1: Site title, 2: Name of the confirmed action. */ 3097 __( '[%1$s] Action Confirmed: %2$s' ), 3098 $email_data['sitename'], 3099 $action_description 3100 ); 3101 3102 /** 3103 * Filters the subject of the user request confirmation email. 3104 * 3105 * @since 4.9.8 3106 * 3107 * @param string $subject The email subject. 3108 * @param string $sitename The name of the site. 3109 * @param array $email_data { 3110 * Data relating to the account action email. 3111 * 3112 * @type WP_User_Request $request User request object. 3113 * @type string $user_email The email address confirming a request 3114 * @type string $description Description of the action being performed so the user knows what the email is for. 3115 * @type string $manage_url The link to click manage privacy requests of this type. 3116 * @type string $sitename The site name sending the mail. 3117 * @type string $siteurl The site URL sending the mail. 3118 * @type string $admin_email The administrator email receiving the mail. 3119 * } 3120 */ 3121 $subject = apply_filters( 'user_request_confirmed_email_subject', $subject, $email_data['sitename'], $email_data ); 3122 3123 $email_sent = wp_mail( $email_data['admin_email'], $subject, $content ); 3124 3125 if ( $email_sent ) { 3126 update_post_meta( $request_id, '_wp_admin_notified', true ); 3127 } 3128 } 3129 3130 /** 3131 * Notify the user when their erasure request is fulfilled. 3132 * 3133 * Without this, the user would never know if their data was actually erased. 3134 * 3135 * @since 4.9.6 3136 * 3137 * @param int $request_id The privacy request post ID associated with this request. 3138 */ 3139 function _wp_privacy_send_erasure_fulfillment_notification( $request_id ) { 3140 $request = wp_get_user_request_data( $request_id ); 3141 3142 if ( ! is_a( $request, 'WP_User_Request' ) || 'request-completed' !== $request->status ) { 3143 return; 3144 } 3145 3146 $already_notified = (bool) get_post_meta( $request_id, '_wp_user_notified', true ); 3147 3148 if ( $already_notified ) { 3149 return; 3150 } 3151 3152 // Localize message content for user; fallback to site default for visitors. 3153 if ( ! empty( $request->user_id ) ) { 3154 $locale = get_user_locale( $request->user_id ); 3155 } else { 3156 $locale = get_locale(); 3157 } 3158 3159 $switched_locale = switch_to_locale( $locale ); 3160 3161 /** 3162 * Filters the recipient of the data erasure fulfillment notification. 3163 * 3164 * @since 4.9.6 3165 * 3166 * @param string $user_email The email address of the notification recipient. 3167 * @param WP_User_Request $request The request that is initiating the notification. 3168 */ 3169 $user_email = apply_filters( 'user_erasure_fulfillment_email_to', $request->email, $request ); 3170 3171 $email_data = array( 3172 'request' => $request, 3173 'message_recipient' => $user_email, 3174 'privacy_policy_url' => get_privacy_policy_url(), 3175 'sitename' => wp_specialchars_decode( get_option( 'blogname' ), ENT_QUOTES ), 3176 'siteurl' => home_url(), 3177 ); 3178 3179 $subject = sprintf( 3180 /* translators: Erasure request fulfilled notification email subject. %s: Site name. */ 3181 __( '[%s] Erasure Request Fulfilled' ), 3182 $email_data['sitename'] 3183 ); 3184 3185 /** 3186 * Filters the subject of the email sent when an erasure request is completed. 3187 * 3188 * @since 4.9.8 3189 * 3190 * @param string $subject The email subject. 3191 * @param string $sitename The name of the site. 3192 * @param array $email_data { 3193 * Data relating to the account action email. 3194 * 3195 * @type WP_User_Request $request User request object. 3196 * @type string $message_recipient The address that the email will be sent to. Defaults 3197 * to the value of `$request->email`, but can be changed 3198 * by the `user_erasure_fulfillment_email_to` filter. 3199 * @type string $privacy_policy_url Privacy policy URL. 3200 * @type string $sitename The site name sending the mail. 3201 * @type string $siteurl The site URL sending the mail. 3202 * } 3203 */ 3204 $subject = apply_filters( 'user_erasure_complete_email_subject', $subject, $email_data['sitename'], $email_data ); 3205 3206 if ( empty( $email_data['privacy_policy_url'] ) ) { 3207 /* translators: Do not translate SITENAME, SITEURL; those are placeholders. */ 3208 $email_text = __( 3209 'Howdy, 3210 3211 Your request to erase your personal data on ###SITENAME### has been completed. 3212 3213 If you have any follow-up questions or concerns, please contact the site administrator. 3214 3215 Regards, 3216 All at ###SITENAME### 3217 ###SITEURL###' 3218 ); 3219 } else { 3220 /* translators: Do not translate SITENAME, SITEURL, PRIVACY_POLICY_URL; those are placeholders. */ 3221 $email_text = __( 3222 'Howdy, 3223 3224 Your request to erase your personal data on ###SITENAME### has been completed. 3225 3226 If you have any follow-up questions or concerns, please contact the site administrator. 3227 3228 For more information, you can also read our privacy policy: ###PRIVACY_POLICY_URL### 3229 3230 Regards, 3231 All at ###SITENAME### 3232 ###SITEURL###' 3233 ); 3234 } 3235 3236 /** 3237 * Filters the body of the data erasure fulfillment notification. 3238 * 3239 * The email is sent to a user when a their data erasure request is fulfilled 3240 * by an administrator. 3241 * 3242 * The following strings have a special meaning and will get replaced dynamically: 3243 * 3244 * ###SITENAME### The name of the site. 3245 * ###PRIVACY_POLICY_URL### Privacy policy page URL. 3246 * ###SITEURL### The URL to the site. 3247 * 3248 * @since 4.9.6 3249 * 3250 * @param string $email_text Text in the email. 3251 * @param array $email_data { 3252 * Data relating to the account action email. 3253 * 3254 * @type WP_User_Request $request User request object. 3255 * @type string $message_recipient The address that the email will be sent to. Defaults 3256 * to the value of `$request->email`, but can be changed 3257 * by the `user_erasure_fulfillment_email_to` filter. 3258 * @type string $privacy_policy_url Privacy policy URL. 3259 * @type string $sitename The site name sending the mail. 3260 * @type string $siteurl The site URL sending the mail. 3261 * } 3262 */ 3263 $content = apply_filters( 'user_confirmed_action_email_content', $email_text, $email_data ); 3264 3265 $content = str_replace( '###SITENAME###', $email_data['sitename'], $content ); 3266 $content = str_replace( '###PRIVACY_POLICY_URL###', $email_data['privacy_policy_url'], $content ); 3267 $content = str_replace( '###SITEURL###', esc_url_raw( $email_data['siteurl'] ), $content ); 3268 3269 $email_sent = wp_mail( $user_email, $subject, $content ); 3270 3271 if ( $switched_locale ) { 3272 restore_previous_locale(); 3273 } 3274 3275 if ( $email_sent ) { 3276 update_post_meta( $request_id, '_wp_user_notified', true ); 3277 } 3278 } 3279 3280 /** 3281 * Return request confirmation message HTML. 3282 * 3283 * @since 4.9.6 3284 * @access private 3285 * 3286 * @param int $request_id The request ID being confirmed. 3287 * @return string $message The confirmation message. 3288 */ 3289 function _wp_privacy_account_request_confirmed_message( $request_id ) { 3290 $request = wp_get_user_request_data( $request_id ); 3291 3292 $message = '<p class="success">' . __( 'Action has been confirmed.' ) . '</p>'; 3293 $message .= '<p>' . __( 'The site administrator has been notified and will fulfill your request as soon as possible.' ) . '</p>'; 3294 3295 if ( $request && in_array( $request->action_name, _wp_privacy_action_request_types(), true ) ) { 3296 if ( 'export_personal_data' === $request->action_name ) { 3297 $message = '<p class="success">' . __( 'Thanks for confirming your export request.' ) . '</p>'; 3298 $message .= '<p>' . __( 'The site administrator has been notified. You will receive a link to download your export via email when they fulfill your request.' ) . '</p>'; 3299 } elseif ( 'remove_personal_data' === $request->action_name ) { 3300 $message = '<p class="success">' . __( 'Thanks for confirming your erasure request.' ) . '</p>'; 3301 $message .= '<p>' . __( 'The site administrator has been notified. You will receive an email confirmation when they erase your data.' ) . '</p>'; 3302 } 3303 } 3304 3305 /** 3306 * Filters the message displayed to a user when they confirm a data request. 3307 * 3308 * @since 4.9.6 3309 * 3310 * @param string $message The message to the user. 3311 * @param int $request_id The ID of the request being confirmed. 3312 */ 3313 $message = apply_filters( 'user_request_action_confirmed_message', $message, $request_id ); 3314 3315 return $message; 3316 } 3317 3318 /** 3319 * Create and log a user request to perform a specific action. 3320 * 3321 * Requests are stored inside a post type named `user_request` since they can apply to both 3322 * users on the site, or guests without a user account. 3323 * 3324 * @since 4.9.6 3325 * 3326 * @param string $email_address User email address. This can be the address of a registered or non-registered user. 3327 * @param string $action_name Name of the action that is being confirmed. Required. 3328 * @param array $request_data Misc data you want to send with the verification request and pass to the actions once the request is confirmed. 3329 * @return int|WP_Error Returns the request ID if successful, or a WP_Error object on failure. 3330 */ 3331 function wp_create_user_request( $email_address = '', $action_name = '', $request_data = array() ) { 3332 $email_address = sanitize_email( $email_address ); 3333 $action_name = sanitize_key( $action_name ); 3334 3335 if ( ! is_email( $email_address ) ) { 3336 return new WP_Error( 'invalid_email', __( 'Invalid email address.' ) ); 3337 } 3338 3339 if ( ! $action_name ) { 3340 return new WP_Error( 'invalid_action', __( 'Invalid action name.' ) ); 3341 } 3342 3343 $user = get_user_by( 'email', $email_address ); 3344 $user_id = $user && ! is_wp_error( $user ) ? $user->ID : 0; 3345 3346 // Check for duplicates. 3347 $requests_query = new WP_Query( 3348 array( 3349 'post_type' => 'user_request', 3350 'post_name__in' => array( $action_name ), // Action name stored in post_name column. 3351 'title' => $email_address, // Email address stored in post_title column. 3352 'post_status' => array( 3353 'request-pending', 3354 'request-confirmed', 3355 ), 3356 'fields' => 'ids', 3357 ) 3358 ); 3359 3360 if ( $requests_query->found_posts ) { 3361 return new WP_Error( 'duplicate_request', __( 'An incomplete request for this email address already exists.' ) ); 3362 } 3363 3364 $request_id = wp_insert_post( 3365 array( 3366 'post_author' => $user_id, 3367 'post_name' => $action_name, 3368 'post_title' => $email_address, 3369 'post_content' => wp_json_encode( $request_data ), 3370 'post_status' => 'request-pending', 3371 'post_type' => 'user_request', 3372 'post_date' => current_time( 'mysql', false ), 3373 'post_date_gmt' => current_time( 'mysql', true ), 3374 ), 3375 true 3376 ); 3377 3378 return $request_id; 3379 } 3380 3381 /** 3382 * Get action description from the name and return a string. 3383 * 3384 * @since 4.9.6 3385 * 3386 * @param string $action_name Action name of the request. 3387 * @return string Human readable action name. 3388 */ 3389 function wp_user_request_action_description( $action_name ) { 3390 switch ( $action_name ) { 3391 case 'export_personal_data': 3392 $description = __( 'Export Personal Data' ); 3393 break; 3394 case 'remove_personal_data': 3395 $description = __( 'Erase Personal Data' ); 3396 break; 3397 default: 3398 /* translators: %s: action name */ 3399 $description = sprintf( __( 'Confirm the "%s" action' ), $action_name ); 3400 break; 3401 } 3402 3403 /** 3404 * Filters the user action description. 3405 * 3406 * @since 4.9.6 3407 * 3408 * @param string $description The default description. 3409 * @param string $action_name The name of the request. 3410 */ 3411 return apply_filters( 'user_request_action_description', $description, $action_name ); 3412 } 3413 3414 /** 3415 * Send a confirmation request email to confirm an action. 3416 * 3417 * If the request is not already pending, it will be updated. 3418 * 3419 * @since 4.9.6 3420 * 3421 * @param string $request_id ID of the request created via wp_create_user_request(). 3422 * @return bool|WP_Error True on success, `WP_Error` on failure. 3423 */ 3424 function wp_send_user_request( $request_id ) { 3425 $request_id = absint( $request_id ); 3426 $request = wp_get_user_request_data( $request_id ); 3427 3428 if ( ! $request ) { 3429 return new WP_Error( 'invalid_request', __( 'Invalid user request.' ) ); 3430 } 3431 3432 // Localize message content for user; fallback to site default for visitors. 3433 if ( ! empty( $request->user_id ) ) { 3434 $locale = get_user_locale( $request->user_id ); 3435 } else { 3436 $locale = get_locale(); 3437 } 3438 3439 $switched_locale = switch_to_locale( $locale ); 3440 3441 $email_data = array( 3442 'request' => $request, 3443 'email' => $request->email, 3444 'description' => wp_user_request_action_description( $request->action_name ), 3445 'confirm_url' => add_query_arg( 3446 array( 3447 'action' => 'confirmaction', 3448 'request_id' => $request_id, 3449 'confirm_key' => wp_generate_user_request_key( $request_id ), 3450 ), 3451 wp_login_url() 3452 ), 3453 'sitename' => wp_specialchars_decode( get_option( 'blogname' ), ENT_QUOTES ), 3454 'siteurl' => home_url(), 3455 ); 3456 3457 /* translators: Do not translate DESCRIPTION, CONFIRM_URL, SITENAME, SITEURL: those are placeholders. */ 3458 $email_text = __( 3459 'Howdy, 3460 3461 A request has been made to perform the following action on your account: 3462 3463 ###DESCRIPTION### 3464 3465 To confirm this, please click on the following link: 3466 ###CONFIRM_URL### 3467 3468 You can safely ignore and delete this email if you do not want to 3469 take this action. 3470 3471 Regards, 3472 All at ###SITENAME### 3473 ###SITEURL###' 3474 ); 3475 3476 /** 3477 * Filters the text of the email sent when an account action is attempted. 3478 * 3479 * The following strings have a special meaning and will get replaced dynamically: 3480 * 3481 * ###DESCRIPTION### Description of the action being performed so the user knows what the email is for. 3482 * ###CONFIRM_URL### The link to click on to confirm the account action. 3483 * ###SITENAME### The name of the site. 3484 * ###SITEURL### The URL to the site. 3485 * 3486 * @since 4.9.6 3487 * 3488 * @param string $email_text Text in the email. 3489 * @param array $email_data { 3490 * Data relating to the account action email. 3491 * 3492 * @type WP_User_Request $request User request object. 3493 * @type string $email The email address this is being sent to. 3494 * @type string $description Description of the action being performed so the user knows what the email is for. 3495 * @type string $confirm_url The link to click on to confirm the account action. 3496 * @type string $sitename The site name sending the mail. 3497 * @type string $siteurl The site URL sending the mail. 3498 * } 3499 */ 3500 $content = apply_filters( 'user_request_action_email_content', $email_text, $email_data ); 3501 3502 $content = str_replace( '###DESCRIPTION###', $email_data['description'], $content ); 3503 $content = str_replace( '###CONFIRM_URL###', esc_url_raw( $email_data['confirm_url'] ), $content ); 3504 $content = str_replace( '###EMAIL###', $email_data['email'], $content ); 3505 $content = str_replace( '###SITENAME###', $email_data['sitename'], $content ); 3506 $content = str_replace( '###SITEURL###', esc_url_raw( $email_data['siteurl'] ), $content ); 3507 3508 /* translators: Confirm privacy data request notification email subject. 1: Site title, 2: Name of the action */ 3509 $subject = sprintf( __( '[%1$s] Confirm Action: %2$s' ), $email_data['sitename'], $email_data['description'] ); 3510 3511 /** 3512 * Filters the subject of the email sent when an account action is attempted. 3513 * 3514 * @since 4.9.6 3515 * 3516 * @param string $subject The email subject. 3517 * @param string $sitename The name of the site. 3518 * @param array $email_data { 3519 * Data relating to the account action email. 3520 * 3521 * @type WP_User_Request $request User request object. 3522 * @type string $email The email address this is being sent to. 3523 * @type string $description Description of the action being performed so the user knows what the email is for. 3524 * @type string $confirm_url The link to click on to confirm the account action. 3525 * @type string $sitename The site name sending the mail. 3526 * @type string $siteurl The site URL sending the mail. 3527 * } 3528 */ 3529 $subject = apply_filters( 'user_request_action_email_subject', $subject, $email_data['sitename'], $email_data ); 3530 3531 $email_sent = wp_mail( $email_data['email'], $subject, $content ); 3532 3533 if ( $switched_locale ) { 3534 restore_previous_locale(); 3535 } 3536 3537 if ( ! $email_sent ) { 3538 return new WP_Error( 'privacy_email_error', __( 'Unable to send personal data export confirmation email.' ) ); 3539 } 3540 3541 return true; 3542 } 3543 3544 /** 3545 * Returns a confirmation key for a user action and stores the hashed version for future comparison. 3546 * 3547 * @since 4.9.6 3548 * 3549 * @param int $request_id Request ID. 3550 * @return string Confirmation key. 3551 */ 3552 function wp_generate_user_request_key( $request_id ) { 3553 global $wp_hasher; 3554 3555 // Generate something random for a confirmation key. 3556 $key = wp_generate_password( 20, false ); 3557 3558 // Return the key, hashed. 3559 if ( empty( $wp_hasher ) ) { 3560 require_once ABSPATH . WPINC . '/class-phpass.php'; 3561 $wp_hasher = new PasswordHash( 8, true ); 3562 } 3563 3564 wp_update_post( 3565 array( 3566 'ID' => $request_id, 3567 'post_status' => 'request-pending', 3568 'post_password' => $wp_hasher->HashPassword( $key ), 3569 ) 3570 ); 3571 3572 return $key; 3573 } 3574 3575 /** 3576 * Validate a user request by comparing the key with the request's key. 3577 * 3578 * @since 4.9.6 3579 * 3580 * @param string $request_id ID of the request being confirmed. 3581 * @param string $key Provided key to validate. 3582 * @return bool|WP_Error WP_Error on failure, true on success. 3583 */ 3584 function wp_validate_user_request_key( $request_id, $key ) { 3585 global $wp_hasher; 3586 3587 $request_id = absint( $request_id ); 3588 $request = wp_get_user_request_data( $request_id ); 3589 3590 if ( ! $request ) { 3591 return new WP_Error( 'invalid_request', __( 'Invalid request.' ) ); 3592 } 3593 3594 if ( ! in_array( $request->status, array( 'request-pending', 'request-failed' ), true ) ) { 3595 return new WP_Error( 'expired_link', __( 'This link has expired.' ) ); 3596 } 3597 3598 if ( empty( $key ) ) { 3599 return new WP_Error( 'missing_key', __( 'Missing confirm key.' ) ); 3600 } 3601 3602 if ( empty( $wp_hasher ) ) { 3603 require_once ABSPATH . WPINC . '/class-phpass.php'; 3604 $wp_hasher = new PasswordHash( 8, true ); 3605 } 3606 3607 $key_request_time = $request->modified_timestamp; 3608 $saved_key = $request->confirm_key; 3609 3610 if ( ! $saved_key ) { 3611 return new WP_Error( 'invalid_key', __( 'Invalid key.' ) ); 3612 } 3613 3614 if ( ! $key_request_time ) { 3615 return new WP_Error( 'invalid_key', __( 'Invalid action.' ) ); 3616 } 3617 3618 /** 3619 * Filters the expiration time of confirm keys. 3620 * 3621 * @since 4.9.6 3622 * 3623 * @param int $expiration The expiration time in seconds. 3624 */ 3625 $expiration_duration = (int) apply_filters( 'user_request_key_expiration', DAY_IN_SECONDS ); 3626 $expiration_time = $key_request_time + $expiration_duration; 3627 3628 if ( ! $wp_hasher->CheckPassword( $key, $saved_key ) ) { 3629 return new WP_Error( 'invalid_key', __( 'Invalid key.' ) ); 3630 } 3631 3632 if ( ! $expiration_time || time() > $expiration_time ) { 3633 return new WP_Error( 'expired_key', __( 'The confirmation email has expired.' ) ); 3634 } 3635 3636 return true; 3637 } 3638 3639 /** 3640 * Return data about a user request. 3641 * 3642 * @since 4.9.6 3643 * 3644 * @param int $request_id Request ID to get data about. 3645 * @return WP_User_Request|false 3646 */ 3647 function wp_get_user_request_data( $request_id ) { 3648 $request_id = absint( $request_id ); 3649 $post = get_post( $request_id ); 3650 3651 if ( ! $post || 'user_request' !== $post->post_type ) { 3652 return false; 3653 } 3654 3655 return new WP_User_Request( $post ); 3656 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated: Mon Jul 22 01:00:03 2019 | Cross-referenced by PHPXref 0.7.1 |