| [ 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://developer.wordpress.org/reference/functions/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://developer.wordpress.org/reference/functions/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://developer.wordpress.org/reference/functions/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 $parsed_args = wp_parse_args( $args, $defaults ); 1127 1128 $query_args = wp_array_slice_assoc( $parsed_args, 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( $parsed_args['show'] ) ? $parsed_args['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 = $parsed_args['show_option_all']; 1142 $show_option_none = $parsed_args['show_option_none']; 1143 $option_none_value = $parsed_args['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 $parsed_args The arguments passed to wp_dropdown_users() combined with the defaults. 1152 */ 1153 $query_args = apply_filters( 'wp_dropdown_users_args', $query_args, $parsed_args ); 1154 1155 $users = get_users( $query_args ); 1156 1157 $output = ''; 1158 if ( ! empty( $users ) && ( empty( $parsed_args['hide_if_only_one_author'] ) || count( $users ) > 1 ) ) { 1159 $name = esc_attr( $parsed_args['name'] ); 1160 if ( $parsed_args['multi'] && ! $parsed_args['id'] ) { 1161 $id = ''; 1162 } else { 1163 $id = $parsed_args['id'] ? " id='" . esc_attr( $parsed_args['id'] ) . "'" : " id='$name'"; 1164 } 1165 $output = "<select name='{$name}'{$id} class='" . $parsed_args['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, $parsed_args['selected'], false ); 1173 $output .= "\t<option value='" . esc_attr( $option_none_value ) . "'$_selected>$show_option_none</option>\n"; 1174 } 1175 1176 if ( $parsed_args['include_selected'] && ( $parsed_args['selected'] > 0 ) ) { 1177 $found_selected = false; 1178 $parsed_args['selected'] = (int) $parsed_args['selected']; 1179 foreach ( (array) $users as $user ) { 1180 $user->ID = (int) $user->ID; 1181 if ( $user->ID === $parsed_args['selected'] ) { 1182 $found_selected = true; 1183 } 1184 } 1185 1186 if ( ! $found_selected ) { 1187 $users[] = get_userdata( $parsed_args['selected'] ); 1188 } 1189 } 1190 1191 foreach ( (array) $users as $user ) { 1192 if ( 'display_name_with_login' === $show ) { 1193 /* translators: 1: User's 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, $parsed_args['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 ( $parsed_args['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', 'user_activation_key', 'spam', and 'role'. The filters have the prefix 1472 * 'pre_user_' followed by the field name. An example using 'description' would have the filter 1473 * called 'pre_user_description' that 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 * @since 5.3.0 The `user_activation_key` field can be passed to `$userdata`. 1480 * @since 5.3.0 The `spam` field can be passed to `$userdata` (Multisite only). 1481 * 1482 * @global wpdb $wpdb WordPress database abstraction object. 1483 * 1484 * @param array|object|WP_User $userdata { 1485 * An array, object, or WP_User object of user data arguments. 1486 * 1487 * @type int $ID User ID. If supplied, the user will be updated. 1488 * @type string $user_pass The plain-text user password. 1489 * @type string $user_login The user's login username. 1490 * @type string $user_nicename The URL-friendly user name. 1491 * @type string $user_url The user URL. 1492 * @type string $user_email The user email address. 1493 * @type string $display_name The user's display name. 1494 * Default is the user's username. 1495 * @type string $nickname The user's nickname. 1496 * Default is the user's username. 1497 * @type string $first_name The user's first name. For new users, will be used 1498 * to build the first part of the user's display name 1499 * if `$display_name` is not specified. 1500 * @type string $last_name The user's last name. For new users, will be used 1501 * to build the second part of the user's display name 1502 * if `$display_name` is not specified. 1503 * @type string $description The user's biographical description. 1504 * @type string|bool $rich_editing Whether to enable the rich-editor for the user. 1505 * False if not empty. 1506 * @type string|bool $syntax_highlighting Whether to enable the rich code editor for the user. 1507 * False if not empty. 1508 * @type string|bool $comment_shortcuts Whether to enable comment moderation keyboard 1509 * shortcuts for the user. Default false. 1510 * @type string $admin_color Admin color scheme for the user. Default 'fresh'. 1511 * @type bool $use_ssl Whether the user should always access the admin over 1512 * https. Default false. 1513 * @type string $user_registered Date the user registered. Format is 'Y-m-d H:i:s'. 1514 * @type string $user_activation_key Password reset key. Default empty. 1515 * @type bool $spam Multisite only. Whether the user is marked as spam. 1516 * Default false. 1517 * @type string|bool $show_admin_bar_front Whether to display the Admin Bar for the user on the 1518 * site's front end. Default true. 1519 * @type string $role User's role. 1520 * @type string $locale User's locale. Default empty. 1521 * } 1522 * @return int|WP_Error The newly created user's ID or a WP_Error object if the user could not 1523 * be created. 1524 */ 1525 function wp_insert_user( $userdata ) { 1526 global $wpdb; 1527 1528 if ( $userdata instanceof stdClass ) { 1529 $userdata = get_object_vars( $userdata ); 1530 } elseif ( $userdata instanceof WP_User ) { 1531 $userdata = $userdata->to_array(); 1532 } 1533 1534 // Are we updating or creating? 1535 if ( ! empty( $userdata['ID'] ) ) { 1536 $ID = (int) $userdata['ID']; 1537 $update = true; 1538 $old_user_data = get_userdata( $ID ); 1539 1540 if ( ! $old_user_data ) { 1541 return new WP_Error( 'invalid_user_id', __( 'Invalid user ID.' ) ); 1542 } 1543 1544 // hashed in wp_update_user(), plaintext if called directly 1545 $user_pass = ! empty( $userdata['user_pass'] ) ? $userdata['user_pass'] : $old_user_data->user_pass; 1546 } else { 1547 $update = false; 1548 // Hash the password 1549 $user_pass = wp_hash_password( $userdata['user_pass'] ); 1550 } 1551 1552 $sanitized_user_login = sanitize_user( $userdata['user_login'], true ); 1553 1554 /** 1555 * Filters a username after it has been sanitized. 1556 * 1557 * This filter is called before the user is created or updated. 1558 * 1559 * @since 2.0.3 1560 * 1561 * @param string $sanitized_user_login Username after it has been sanitized. 1562 */ 1563 $pre_user_login = apply_filters( 'pre_user_login', $sanitized_user_login ); 1564 1565 //Remove any non-printable chars from the login string to see if we have ended up with an empty username 1566 $user_login = trim( $pre_user_login ); 1567 1568 // user_login must be between 0 and 60 characters. 1569 if ( empty( $user_login ) ) { 1570 return new WP_Error( 'empty_user_login', __( 'Cannot create a user with an empty login name.' ) ); 1571 } elseif ( mb_strlen( $user_login ) > 60 ) { 1572 return new WP_Error( 'user_login_too_long', __( 'Username may not be longer than 60 characters.' ) ); 1573 } 1574 1575 if ( ! $update && username_exists( $user_login ) ) { 1576 return new WP_Error( 'existing_user_login', __( 'Sorry, that username already exists!' ) ); 1577 } 1578 1579 /** 1580 * Filters the list of blacklisted usernames. 1581 * 1582 * @since 4.4.0 1583 * 1584 * @param array $usernames Array of blacklisted usernames. 1585 */ 1586 $illegal_logins = (array) apply_filters( 'illegal_user_logins', array() ); 1587 1588 if ( in_array( strtolower( $user_login ), array_map( 'strtolower', $illegal_logins ) ) ) { 1589 return new WP_Error( 'invalid_username', __( 'Sorry, that username is not allowed.' ) ); 1590 } 1591 1592 /* 1593 * If a nicename is provided, remove unsafe user characters before using it. 1594 * Otherwise build a nicename from the user_login. 1595 */ 1596 if ( ! empty( $userdata['user_nicename'] ) ) { 1597 $user_nicename = sanitize_user( $userdata['user_nicename'], true ); 1598 if ( mb_strlen( $user_nicename ) > 50 ) { 1599 return new WP_Error( 'user_nicename_too_long', __( 'Nicename may not be longer than 50 characters.' ) ); 1600 } 1601 } else { 1602 $user_nicename = mb_substr( $user_login, 0, 50 ); 1603 } 1604 1605 $user_nicename = sanitize_title( $user_nicename ); 1606 1607 /** 1608 * Filters a user's nicename before the user is created or updated. 1609 * 1610 * @since 2.0.3 1611 * 1612 * @param string $user_nicename The user's nicename. 1613 */ 1614 $user_nicename = apply_filters( 'pre_user_nicename', $user_nicename ); 1615 1616 $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 ) ); 1617 1618 if ( $user_nicename_check ) { 1619 $suffix = 2; 1620 while ( $user_nicename_check ) { 1621 // user_nicename allows 50 chars. Subtract one for a hyphen, plus the length of the suffix. 1622 $base_length = 49 - mb_strlen( $suffix ); 1623 $alt_user_nicename = mb_substr( $user_nicename, 0, $base_length ) . "-$suffix"; 1624 $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 ) ); 1625 $suffix++; 1626 } 1627 $user_nicename = $alt_user_nicename; 1628 } 1629 1630 $raw_user_email = empty( $userdata['user_email'] ) ? '' : $userdata['user_email']; 1631 1632 /** 1633 * Filters a user's email before the user is created or updated. 1634 * 1635 * @since 2.0.3 1636 * 1637 * @param string $raw_user_email The user's email. 1638 */ 1639 $user_email = apply_filters( 'pre_user_email', $raw_user_email ); 1640 1641 /* 1642 * If there is no update, just check for `email_exists`. If there is an update, 1643 * check if current email and new email are the same, or not, and check `email_exists` 1644 * accordingly. 1645 */ 1646 if ( ( ! $update || ( ! empty( $old_user_data ) && 0 !== strcasecmp( $user_email, $old_user_data->user_email ) ) ) 1647 && ! defined( 'WP_IMPORTING' ) 1648 && email_exists( $user_email ) 1649 ) { 1650 return new WP_Error( 'existing_user_email', __( 'Sorry, that email address is already used!' ) ); 1651 } 1652 1653 $raw_user_url = empty( $userdata['user_url'] ) ? '' : $userdata['user_url']; 1654 1655 /** 1656 * Filters a user's URL before the user is created or updated. 1657 * 1658 * @since 2.0.3 1659 * 1660 * @param string $raw_user_url The user's URL. 1661 */ 1662 $user_url = apply_filters( 'pre_user_url', $raw_user_url ); 1663 1664 $user_registered = empty( $userdata['user_registered'] ) ? gmdate( 'Y-m-d H:i:s' ) : $userdata['user_registered']; 1665 1666 $user_activation_key = empty( $userdata['user_activation_key'] ) ? '' : $userdata['user_activation_key']; 1667 1668 if ( ! empty( $userdata['spam'] ) && ! is_multisite() ) { 1669 return new WP_Error( 'no_spam', __( 'Sorry, marking a user as spam is only supported on Multisite.' ) ); 1670 } 1671 1672 $spam = empty( $userdata['spam'] ) ? 0 : (bool) $userdata['spam']; 1673 1674 // Store values to save in user meta. 1675 $meta = array(); 1676 1677 $nickname = empty( $userdata['nickname'] ) ? $user_login : $userdata['nickname']; 1678 1679 /** 1680 * Filters a user's nickname before the user is created or updated. 1681 * 1682 * @since 2.0.3 1683 * 1684 * @param string $nickname The user's nickname. 1685 */ 1686 $meta['nickname'] = apply_filters( 'pre_user_nickname', $nickname ); 1687 1688 $first_name = empty( $userdata['first_name'] ) ? '' : $userdata['first_name']; 1689 1690 /** 1691 * Filters a user's first name before the user is created or updated. 1692 * 1693 * @since 2.0.3 1694 * 1695 * @param string $first_name The user's first name. 1696 */ 1697 $meta['first_name'] = apply_filters( 'pre_user_first_name', $first_name ); 1698 1699 $last_name = empty( $userdata['last_name'] ) ? '' : $userdata['last_name']; 1700 1701 /** 1702 * Filters a user's last name before the user is created or updated. 1703 * 1704 * @since 2.0.3 1705 * 1706 * @param string $last_name The user's last name. 1707 */ 1708 $meta['last_name'] = apply_filters( 'pre_user_last_name', $last_name ); 1709 1710 if ( empty( $userdata['display_name'] ) ) { 1711 if ( $update ) { 1712 $display_name = $user_login; 1713 } elseif ( $meta['first_name'] && $meta['last_name'] ) { 1714 /* translators: 1: User's first name, 2: Last name. */ 1715 $display_name = sprintf( _x( '%1$s %2$s', 'Display name based on first name and last name' ), $meta['first_name'], $meta['last_name'] ); 1716 } elseif ( $meta['first_name'] ) { 1717 $display_name = $meta['first_name']; 1718 } elseif ( $meta['last_name'] ) { 1719 $display_name = $meta['last_name']; 1720 } else { 1721 $display_name = $user_login; 1722 } 1723 } else { 1724 $display_name = $userdata['display_name']; 1725 } 1726 1727 /** 1728 * Filters a user's display name before the user is created or updated. 1729 * 1730 * @since 2.0.3 1731 * 1732 * @param string $display_name The user's display name. 1733 */ 1734 $display_name = apply_filters( 'pre_user_display_name', $display_name ); 1735 1736 $description = empty( $userdata['description'] ) ? '' : $userdata['description']; 1737 1738 /** 1739 * Filters a user's description before the user is created or updated. 1740 * 1741 * @since 2.0.3 1742 * 1743 * @param string $description The user's description. 1744 */ 1745 $meta['description'] = apply_filters( 'pre_user_description', $description ); 1746 1747 $meta['rich_editing'] = empty( $userdata['rich_editing'] ) ? 'true' : $userdata['rich_editing']; 1748 1749 $meta['syntax_highlighting'] = empty( $userdata['syntax_highlighting'] ) ? 'true' : $userdata['syntax_highlighting']; 1750 1751 $meta['comment_shortcuts'] = empty( $userdata['comment_shortcuts'] ) || 'false' === $userdata['comment_shortcuts'] ? 'false' : 'true'; 1752 1753 $admin_color = empty( $userdata['admin_color'] ) ? 'fresh' : $userdata['admin_color']; 1754 $meta['admin_color'] = preg_replace( '|[^a-z0-9 _.\-@]|i', '', $admin_color ); 1755 1756 $meta['use_ssl'] = empty( $userdata['use_ssl'] ) ? 0 : (bool) $userdata['use_ssl']; 1757 1758 $meta['show_admin_bar_front'] = empty( $userdata['show_admin_bar_front'] ) ? 'true' : $userdata['show_admin_bar_front']; 1759 1760 $meta['locale'] = isset( $userdata['locale'] ) ? $userdata['locale'] : ''; 1761 1762 $compacted = compact( 'user_pass', 'user_nicename', 'user_email', 'user_url', 'user_registered', 'user_activation_key', 'display_name' ); 1763 $data = wp_unslash( $compacted ); 1764 1765 if ( ! $update ) { 1766 $data = $data + compact( 'user_login' ); 1767 } 1768 1769 if ( is_multisite() ) { 1770 $data = $data + compact( 'spam' ); 1771 } 1772 1773 /** 1774 * Filters user data before the record is created or updated. 1775 * 1776 * It only includes data in the wp_users table wp_user, not any user metadata. 1777 * 1778 * @since 4.9.0 1779 * 1780 * @param array $data { 1781 * Values and keys for the user. 1782 * 1783 * @type string $user_login The user's login. Only included if $update == false 1784 * @type string $user_pass The user's password. 1785 * @type string $user_email The user's email. 1786 * @type string $user_url The user's url. 1787 * @type string $user_nicename The user's nice name. Defaults to a URL-safe version of user's login 1788 * @type string $display_name The user's display name. 1789 * @type string $user_registered MySQL timestamp describing the moment when the user registered. Defaults to 1790 * the current UTC timestamp. 1791 * } 1792 * @param bool $update Whether the user is being updated rather than created. 1793 * @param int|null $id ID of the user to be updated, or NULL if the user is being created. 1794 */ 1795 $data = apply_filters( 'wp_pre_insert_user_data', $data, $update, $update ? (int) $ID : null ); 1796 1797 if ( empty( $data ) || ! is_array( $data ) ) { 1798 return new WP_Error( 'empty_data', __( 'Not enough data to create this user.' ) ); 1799 } 1800 1801 if ( $update ) { 1802 if ( $user_email !== $old_user_data->user_email ) { 1803 $data['user_activation_key'] = ''; 1804 } 1805 $wpdb->update( $wpdb->users, $data, compact( 'ID' ) ); 1806 $user_id = (int) $ID; 1807 } else { 1808 $wpdb->insert( $wpdb->users, $data ); 1809 $user_id = (int) $wpdb->insert_id; 1810 } 1811 1812 $user = new WP_User( $user_id ); 1813 1814 /** 1815 * Filters a user's meta values and keys immediately after the user is created or updated 1816 * and before any user meta is inserted or updated. 1817 * 1818 * Does not include contact methods. These are added using `wp_get_user_contact_methods( $user )`. 1819 * 1820 * @since 4.4.0 1821 * 1822 * @param array $meta { 1823 * Default meta values and keys for the user. 1824 * 1825 * @type string $nickname The user's nickname. Default is the user's username. 1826 * @type string $first_name The user's first name. 1827 * @type string $last_name The user's last name. 1828 * @type string $description The user's description. 1829 * @type bool $rich_editing Whether to enable the rich-editor for the user. False if not empty. 1830 * @type bool $syntax_highlighting Whether to enable the rich code editor for the user. False if not empty. 1831 * @type bool $comment_shortcuts Whether to enable keyboard shortcuts for the user. Default false. 1832 * @type string $admin_color The color scheme for a user's admin screen. Default 'fresh'. 1833 * @type int|bool $use_ssl Whether to force SSL on the user's admin area. 0|false if SSL is 1834 * not forced. 1835 * @type bool $show_admin_bar_front Whether to show the admin bar on the front end for the user. 1836 * Default true. 1837 * @type string $locale User's locale. Default empty. 1838 * } 1839 * @param WP_User $user User object. 1840 * @param bool $update Whether the user is being updated rather than created. 1841 */ 1842 $meta = apply_filters( 'insert_user_meta', $meta, $user, $update ); 1843 1844 // Update user meta. 1845 foreach ( $meta as $key => $value ) { 1846 update_user_meta( $user_id, $key, $value ); 1847 } 1848 1849 foreach ( wp_get_user_contact_methods( $user ) as $key => $value ) { 1850 if ( isset( $userdata[ $key ] ) ) { 1851 update_user_meta( $user_id, $key, $userdata[ $key ] ); 1852 } 1853 } 1854 1855 if ( isset( $userdata['role'] ) ) { 1856 $user->set_role( $userdata['role'] ); 1857 } elseif ( ! $update ) { 1858 $user->set_role( get_option( 'default_role' ) ); 1859 } 1860 1861 clean_user_cache( $user_id ); 1862 1863 if ( $update ) { 1864 /** 1865 * Fires immediately after an existing user is updated. 1866 * 1867 * @since 2.0.0 1868 * 1869 * @param int $user_id User ID. 1870 * @param WP_User $old_user_data Object containing user's data prior to update. 1871 */ 1872 do_action( 'profile_update', $user_id, $old_user_data ); 1873 1874 if ( isset( $userdata['spam'] ) && $userdata['spam'] != $old_user_data->spam ) { 1875 if ( $userdata['spam'] == 1 ) { 1876 /** 1877 * Fires after the user is marked as a SPAM user. 1878 * 1879 * @since 3.0.0 1880 * 1881 * @param int $user_id ID of the user marked as SPAM. 1882 */ 1883 do_action( 'make_spam_user', $user_id ); 1884 } else { 1885 /** 1886 * Fires after the user is marked as a HAM user. Opposite of SPAM. 1887 * 1888 * @since 3.0.0 1889 * 1890 * @param int $user_id ID of the user marked as HAM. 1891 */ 1892 do_action( 'make_ham_user', $user_id ); 1893 } 1894 } 1895 } else { 1896 /** 1897 * Fires immediately after a new user is registered. 1898 * 1899 * @since 1.5.0 1900 * 1901 * @param int $user_id User ID. 1902 */ 1903 do_action( 'user_register', $user_id ); 1904 } 1905 1906 return $user_id; 1907 } 1908 1909 /** 1910 * Update a user in the database. 1911 * 1912 * It is possible to update a user's password by specifying the 'user_pass' 1913 * value in the $userdata parameter array. 1914 * 1915 * If current user's password is being updated, then the cookies will be 1916 * cleared. 1917 * 1918 * @since 2.0.0 1919 * 1920 * @see wp_insert_user() For what fields can be set in $userdata. 1921 * 1922 * @param array|object|WP_User $userdata An array of user data or a user object of type stdClass or WP_User. 1923 * @return int|WP_Error The updated user's ID or a WP_Error object if the user could not be updated. 1924 */ 1925 function wp_update_user( $userdata ) { 1926 if ( $userdata instanceof stdClass ) { 1927 $userdata = get_object_vars( $userdata ); 1928 } elseif ( $userdata instanceof WP_User ) { 1929 $userdata = $userdata->to_array(); 1930 } 1931 1932 $ID = isset( $userdata['ID'] ) ? (int) $userdata['ID'] : 0; 1933 if ( ! $ID ) { 1934 return new WP_Error( 'invalid_user_id', __( 'Invalid user ID.' ) ); 1935 } 1936 1937 // First, get all of the original fields 1938 $user_obj = get_userdata( $ID ); 1939 if ( ! $user_obj ) { 1940 return new WP_Error( 'invalid_user_id', __( 'Invalid user ID.' ) ); 1941 } 1942 1943 $user = $user_obj->to_array(); 1944 1945 // Add additional custom fields 1946 foreach ( _get_additional_user_keys( $user_obj ) as $key ) { 1947 $user[ $key ] = get_user_meta( $ID, $key, true ); 1948 } 1949 1950 // Escape data pulled from DB. 1951 $user = add_magic_quotes( $user ); 1952 1953 if ( ! empty( $userdata['user_pass'] ) && $userdata['user_pass'] !== $user_obj->user_pass ) { 1954 // If password is changing, hash it now 1955 $plaintext_pass = $userdata['user_pass']; 1956 $userdata['user_pass'] = wp_hash_password( $userdata['user_pass'] ); 1957 1958 /** 1959 * Filters whether to send the password change email. 1960 * 1961 * @since 4.3.0 1962 * 1963 * @see wp_insert_user() For `$user` and `$userdata` fields. 1964 * 1965 * @param bool $send Whether to send the email. 1966 * @param array $user The original user array. 1967 * @param array $userdata The updated user array. 1968 */ 1969 $send_password_change_email = apply_filters( 'send_password_change_email', true, $user, $userdata ); 1970 } 1971 1972 if ( isset( $userdata['user_email'] ) && $user['user_email'] !== $userdata['user_email'] ) { 1973 /** 1974 * Filters whether to send the email change email. 1975 * 1976 * @since 4.3.0 1977 * 1978 * @see wp_insert_user() For `$user` and `$userdata` fields. 1979 * 1980 * @param bool $send Whether to send the email. 1981 * @param array $user The original user array. 1982 * @param array $userdata The updated user array. 1983 */ 1984 $send_email_change_email = apply_filters( 'send_email_change_email', true, $user, $userdata ); 1985 } 1986 1987 clean_user_cache( $user_obj ); 1988 1989 // Merge old and new fields with new fields overwriting old ones. 1990 $userdata = array_merge( $user, $userdata ); 1991 $user_id = wp_insert_user( $userdata ); 1992 1993 if ( ! is_wp_error( $user_id ) ) { 1994 1995 $blog_name = wp_specialchars_decode( get_option( 'blogname' ), ENT_QUOTES ); 1996 1997 $switched_locale = false; 1998 if ( ! empty( $send_password_change_email ) || ! empty( $send_email_change_email ) ) { 1999 $switched_locale = switch_to_locale( get_user_locale( $user_id ) ); 2000 } 2001 2002 if ( ! empty( $send_password_change_email ) ) { 2003 /* translators: Do not translate USERNAME, ADMIN_EMAIL, EMAIL, SITENAME, SITEURL: those are placeholders. */ 2004 $pass_change_text = __( 2005 'Hi ###USERNAME###, 2006 2007 This notice confirms that your password was changed on ###SITENAME###. 2008 2009 If you did not change your password, please contact the Site Administrator at 2010 ###ADMIN_EMAIL### 2011 2012 This email has been sent to ###EMAIL### 2013 2014 Regards, 2015 All at ###SITENAME### 2016 ###SITEURL###' 2017 ); 2018 2019 $pass_change_email = array( 2020 'to' => $user['user_email'], 2021 /* translators: Password change notification email subject. %s: Site title. */ 2022 'subject' => __( '[%s] Password Changed' ), 2023 'message' => $pass_change_text, 2024 'headers' => '', 2025 ); 2026 2027 /** 2028 * Filters the contents of the email sent when the user's password is changed. 2029 * 2030 * @since 4.3.0 2031 * 2032 * @param array $pass_change_email { 2033 * Used to build wp_mail(). 2034 * @type string $to The intended recipients. Add emails in a comma separated string. 2035 * @type string $subject The subject of the email. 2036 * @type string $message The content of the email. 2037 * The following strings have a special meaning and will get replaced dynamically: 2038 * - ###USERNAME### The current user's username. 2039 * - ###ADMIN_EMAIL### The admin email in case this was unexpected. 2040 * - ###EMAIL### The user's email address. 2041 * - ###SITENAME### The name of the site. 2042 * - ###SITEURL### The URL to the site. 2043 * @type string $headers Headers. Add headers in a newline (\r\n) separated string. 2044 * } 2045 * @param array $user The original user array. 2046 * @param array $userdata The updated user array. 2047 */ 2048 $pass_change_email = apply_filters( 'password_change_email', $pass_change_email, $user, $userdata ); 2049 2050 $pass_change_email['message'] = str_replace( '###USERNAME###', $user['user_login'], $pass_change_email['message'] ); 2051 $pass_change_email['message'] = str_replace( '###ADMIN_EMAIL###', get_option( 'admin_email' ), $pass_change_email['message'] ); 2052 $pass_change_email['message'] = str_replace( '###EMAIL###', $user['user_email'], $pass_change_email['message'] ); 2053 $pass_change_email['message'] = str_replace( '###SITENAME###', $blog_name, $pass_change_email['message'] ); 2054 $pass_change_email['message'] = str_replace( '###SITEURL###', home_url(), $pass_change_email['message'] ); 2055 2056 wp_mail( $pass_change_email['to'], sprintf( $pass_change_email['subject'], $blog_name ), $pass_change_email['message'], $pass_change_email['headers'] ); 2057 } 2058 2059 if ( ! empty( $send_email_change_email ) ) { 2060 /* translators: Do not translate USERNAME, ADMIN_EMAIL, NEW_EMAIL, EMAIL, SITENAME, SITEURL: those are placeholders. */ 2061 $email_change_text = __( 2062 'Hi ###USERNAME###, 2063 2064 This notice confirms that your email address on ###SITENAME### was changed to ###NEW_EMAIL###. 2065 2066 If you did not change your email, please contact the Site Administrator at 2067 ###ADMIN_EMAIL### 2068 2069 This email has been sent to ###EMAIL### 2070 2071 Regards, 2072 All at ###SITENAME### 2073 ###SITEURL###' 2074 ); 2075 2076 $email_change_email = array( 2077 'to' => $user['user_email'], 2078 /* translators: Email change notification email subject. %s: Site title. */ 2079 'subject' => __( '[%s] Email Changed' ), 2080 'message' => $email_change_text, 2081 'headers' => '', 2082 ); 2083 2084 /** 2085 * Filters the contents of the email sent when the user's email is changed. 2086 * 2087 * @since 4.3.0 2088 * 2089 * @param array $email_change_email { 2090 * Used to build wp_mail(). 2091 * @type string $to The intended recipients. 2092 * @type string $subject The subject of the email. 2093 * @type string $message The content of the email. 2094 * The following strings have a special meaning and will get replaced dynamically: 2095 * - ###USERNAME### The current user's username. 2096 * - ###ADMIN_EMAIL### The admin email in case this was unexpected. 2097 * - ###NEW_EMAIL### The new email address. 2098 * - ###EMAIL### The old email address. 2099 * - ###SITENAME### The name of the site. 2100 * - ###SITEURL### The URL to the site. 2101 * @type string $headers Headers. 2102 * } 2103 * @param array $user The original user array. 2104 * @param array $userdata The updated user array. 2105 */ 2106 $email_change_email = apply_filters( 'email_change_email', $email_change_email, $user, $userdata ); 2107 2108 $email_change_email['message'] = str_replace( '###USERNAME###', $user['user_login'], $email_change_email['message'] ); 2109 $email_change_email['message'] = str_replace( '###ADMIN_EMAIL###', get_option( 'admin_email' ), $email_change_email['message'] ); 2110 $email_change_email['message'] = str_replace( '###NEW_EMAIL###', $userdata['user_email'], $email_change_email['message'] ); 2111 $email_change_email['message'] = str_replace( '###EMAIL###', $user['user_email'], $email_change_email['message'] ); 2112 $email_change_email['message'] = str_replace( '###SITENAME###', $blog_name, $email_change_email['message'] ); 2113 $email_change_email['message'] = str_replace( '###SITEURL###', home_url(), $email_change_email['message'] ); 2114 2115 wp_mail( $email_change_email['to'], sprintf( $email_change_email['subject'], $blog_name ), $email_change_email['message'], $email_change_email['headers'] ); 2116 } 2117 2118 if ( $switched_locale ) { 2119 restore_previous_locale(); 2120 } 2121 } 2122 2123 // Update the cookies if the password changed. 2124 $current_user = wp_get_current_user(); 2125 if ( $current_user->ID == $ID ) { 2126 if ( isset( $plaintext_pass ) ) { 2127 wp_clear_auth_cookie(); 2128 2129 // Here we calculate the expiration length of the current auth cookie and compare it to the default expiration. 2130 // If it's greater than this, then we know the user checked 'Remember Me' when they logged in. 2131 $logged_in_cookie = wp_parse_auth_cookie( '', 'logged_in' ); 2132 /** This filter is documented in wp-includes/pluggable.php */ 2133 $default_cookie_life = apply_filters( 'auth_cookie_expiration', ( 2 * DAY_IN_SECONDS ), $ID, false ); 2134 $remember = false; 2135 if ( false !== $logged_in_cookie && ( $logged_in_cookie['expiration'] - time() ) > $default_cookie_life ) { 2136 $remember = true; 2137 } 2138 2139 wp_set_auth_cookie( $ID, $remember ); 2140 } 2141 } 2142 2143 return $user_id; 2144 } 2145 2146 /** 2147 * A simpler way of inserting a user into the database. 2148 * 2149 * Creates a new user with just the username, password, and email. For more 2150 * complex user creation use wp_insert_user() to specify more information. 2151 * 2152 * @since 2.0.0 2153 * @see wp_insert_user() More complete way to create a new user 2154 * 2155 * @param string $username The user's username. 2156 * @param string $password The user's password. 2157 * @param string $email Optional. The user's email. Default empty. 2158 * @return int|WP_Error The newly created user's ID or a WP_Error object if the user could not 2159 * be created. 2160 */ 2161 function wp_create_user( $username, $password, $email = '' ) { 2162 $user_login = wp_slash( $username ); 2163 $user_email = wp_slash( $email ); 2164 $user_pass = $password; 2165 2166 $userdata = compact( 'user_login', 'user_email', 'user_pass' ); 2167 return wp_insert_user( $userdata ); 2168 } 2169 2170 /** 2171 * Returns a list of meta keys to be (maybe) populated in wp_update_user(). 2172 * 2173 * The list of keys returned via this function are dependent on the presence 2174 * of those keys in the user meta data to be set. 2175 * 2176 * @since 3.3.0 2177 * @access private 2178 * 2179 * @param WP_User $user WP_User instance. 2180 * @return array List of user keys to be populated in wp_update_user(). 2181 */ 2182 function _get_additional_user_keys( $user ) { 2183 $keys = array( 'first_name', 'last_name', 'nickname', 'description', 'rich_editing', 'syntax_highlighting', 'comment_shortcuts', 'admin_color', 'use_ssl', 'show_admin_bar_front', 'locale' ); 2184 return array_merge( $keys, array_keys( wp_get_user_contact_methods( $user ) ) ); 2185 } 2186 2187 /** 2188 * Set up the user contact methods. 2189 * 2190 * Default contact methods were removed in 3.6. A filter dictates contact methods. 2191 * 2192 * @since 3.7.0 2193 * 2194 * @param WP_User $user Optional. WP_User object. 2195 * @return array Array of contact methods and their labels. 2196 */ 2197 function wp_get_user_contact_methods( $user = null ) { 2198 $methods = array(); 2199 if ( get_site_option( 'initial_db_version' ) < 23588 ) { 2200 $methods = array( 2201 'aim' => __( 'AIM' ), 2202 'yim' => __( 'Yahoo IM' ), 2203 'jabber' => __( 'Jabber / Google Talk' ), 2204 ); 2205 } 2206 2207 /** 2208 * Filters the user contact methods. 2209 * 2210 * @since 2.9.0 2211 * 2212 * @param array $methods Array of contact methods and their labels. 2213 * @param WP_User $user WP_User object. 2214 */ 2215 return apply_filters( 'user_contactmethods', $methods, $user ); 2216 } 2217 2218 /** 2219 * The old private function for setting up user contact methods. 2220 * 2221 * Use wp_get_user_contact_methods() instead. 2222 * 2223 * @since 2.9.0 2224 * @access private 2225 * 2226 * @param WP_User $user Optional. WP_User object. Default null. 2227 * @return array Array of contact methods and their labels. 2228 */ 2229 function _wp_get_user_contactmethods( $user = null ) { 2230 return wp_get_user_contact_methods( $user ); 2231 } 2232 2233 /** 2234 * Gets the text suggesting how to create strong passwords. 2235 * 2236 * @since 4.1.0 2237 * 2238 * @return string The password hint text. 2239 */ 2240 function wp_get_password_hint() { 2241 $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 ! " ? $ % ^ & ).' ); 2242 2243 /** 2244 * Filters the text describing the site's password complexity policy. 2245 * 2246 * @since 4.1.0 2247 * 2248 * @param string $hint The password hint text. 2249 */ 2250 return apply_filters( 'password_hint', $hint ); 2251 } 2252 2253 /** 2254 * Creates, stores, then returns a password reset key for user. 2255 * 2256 * @since 4.4.0 2257 * 2258 * @global PasswordHash $wp_hasher Portable PHP password hashing framework. 2259 * 2260 * @param WP_User $user User to retrieve password reset key for. 2261 * 2262 * @return string|WP_Error Password reset key on success. WP_Error on error. 2263 */ 2264 function get_password_reset_key( $user ) { 2265 global $wp_hasher; 2266 2267 if ( ! ( $user instanceof WP_User ) ) { 2268 return new WP_Error( 'invalidcombo', __( '<strong>ERROR</strong>: There is no account with that username or email address.' ) ); 2269 } 2270 2271 /** 2272 * Fires before a new password is retrieved. 2273 * 2274 * Use the {@see 'retrieve_password'} hook instead. 2275 * 2276 * @since 1.5.0 2277 * @deprecated 1.5.1 Misspelled. Use 'retrieve_password' hook instead. 2278 * 2279 * @param string $user_login The user login name. 2280 */ 2281 do_action( 'retreive_password', $user->user_login ); 2282 2283 /** 2284 * Fires before a new password is retrieved. 2285 * 2286 * @since 1.5.1 2287 * 2288 * @param string $user_login The user login name. 2289 */ 2290 do_action( 'retrieve_password', $user->user_login ); 2291 2292 $allow = true; 2293 if ( is_multisite() && is_user_spammy( $user ) ) { 2294 $allow = false; 2295 } 2296 2297 /** 2298 * Filters whether to allow a password to be reset. 2299 * 2300 * @since 2.7.0 2301 * 2302 * @param bool $allow Whether to allow the password to be reset. Default true. 2303 * @param int $user_data->ID The ID of the user attempting to reset a password. 2304 */ 2305 $allow = apply_filters( 'allow_password_reset', $allow, $user->ID ); 2306 2307 if ( ! $allow ) { 2308 return new WP_Error( 'no_password_reset', __( 'Password reset is not allowed for this user' ) ); 2309 } elseif ( is_wp_error( $allow ) ) { 2310 return $allow; 2311 } 2312 2313 // Generate something random for a password reset key. 2314 $key = wp_generate_password( 20, false ); 2315 2316 /** 2317 * Fires when a password reset key is generated. 2318 * 2319 * @since 2.5.0 2320 * 2321 * @param string $user_login The username for the user. 2322 * @param string $key The generated password reset key. 2323 */ 2324 do_action( 'retrieve_password_key', $user->user_login, $key ); 2325 2326 // Now insert the key, hashed, into the DB. 2327 if ( empty( $wp_hasher ) ) { 2328 require_once ABSPATH . WPINC . '/class-phpass.php'; 2329 $wp_hasher = new PasswordHash( 8, true ); 2330 } 2331 2332 $hashed = time() . ':' . $wp_hasher->HashPassword( $key ); 2333 2334 $key_saved = wp_update_user( 2335 array( 2336 'ID' => $user->ID, 2337 'user_activation_key' => $hashed, 2338 ) 2339 ); 2340 2341 if ( is_wp_error( $key_saved ) ) { 2342 return $key_saved; 2343 } 2344 2345 return $key; 2346 } 2347 2348 /** 2349 * Retrieves a user row based on password reset key and login 2350 * 2351 * A key is considered 'expired' if it exactly matches the value of the 2352 * user_activation_key field, rather than being matched after going through the 2353 * hashing process. This field is now hashed; old values are no longer accepted 2354 * but have a different WP_Error code so good user feedback can be provided. 2355 * 2356 * @since 3.1.0 2357 * 2358 * @global wpdb $wpdb WordPress database object for queries. 2359 * @global PasswordHash $wp_hasher Portable PHP password hashing framework instance. 2360 * 2361 * @param string $key Hash to validate sending user's password. 2362 * @param string $login The user login. 2363 * @return WP_User|WP_Error WP_User object on success, WP_Error object for invalid or expired keys. 2364 */ 2365 function check_password_reset_key( $key, $login ) { 2366 global $wpdb, $wp_hasher; 2367 2368 $key = preg_replace( '/[^a-z0-9]/i', '', $key ); 2369 2370 if ( empty( $key ) || ! is_string( $key ) ) { 2371 return new WP_Error( 'invalid_key', __( 'Invalid key.' ) ); 2372 } 2373 2374 if ( empty( $login ) || ! is_string( $login ) ) { 2375 return new WP_Error( 'invalid_key', __( 'Invalid key.' ) ); 2376 } 2377 2378 $user = get_user_by( 'login', $login ); 2379 2380 if ( ! $user ) { 2381 return new WP_Error( 'invalid_key', __( 'Invalid key.' ) ); 2382 } 2383 2384 if ( empty( $wp_hasher ) ) { 2385 require_once ABSPATH . WPINC . '/class-phpass.php'; 2386 $wp_hasher = new PasswordHash( 8, true ); 2387 } 2388 2389 /** 2390 * Filters the expiration time of password reset keys. 2391 * 2392 * @since 4.3.0 2393 * 2394 * @param int $expiration The expiration time in seconds. 2395 */ 2396 $expiration_duration = apply_filters( 'password_reset_expiration', DAY_IN_SECONDS ); 2397 2398 if ( false !== strpos( $user->user_activation_key, ':' ) ) { 2399 list( $pass_request_time, $pass_key ) = explode( ':', $user->user_activation_key, 2 ); 2400 $expiration_time = $pass_request_time + $expiration_duration; 2401 } else { 2402 $pass_key = $user->user_activation_key; 2403 $expiration_time = false; 2404 } 2405 2406 if ( ! $pass_key ) { 2407 return new WP_Error( 'invalid_key', __( 'Invalid key.' ) ); 2408 } 2409 2410 $hash_is_correct = $wp_hasher->CheckPassword( $key, $pass_key ); 2411 2412 if ( $hash_is_correct && $expiration_time && time() < $expiration_time ) { 2413 return $user; 2414 } elseif ( $hash_is_correct && $expiration_time ) { 2415 // Key has an expiration time that's passed 2416 return new WP_Error( 'expired_key', __( 'Invalid key.' ) ); 2417 } 2418 2419 if ( hash_equals( $user->user_activation_key, $key ) || ( $hash_is_correct && ! $expiration_time ) ) { 2420 $return = new WP_Error( 'expired_key', __( 'Invalid key.' ) ); 2421 $user_id = $user->ID; 2422 2423 /** 2424 * Filters the return value of check_password_reset_key() when an 2425 * old-style key is used. 2426 * 2427 * @since 3.7.0 Previously plain-text keys were stored in the database. 2428 * @since 4.3.0 Previously key hashes were stored without an expiration time. 2429 * 2430 * @param WP_Error $return A WP_Error object denoting an expired key. 2431 * Return a WP_User object to validate the key. 2432 * @param int $user_id The matched user ID. 2433 */ 2434 return apply_filters( 'password_reset_key_expired', $return, $user_id ); 2435 } 2436 2437 return new WP_Error( 'invalid_key', __( 'Invalid key.' ) ); 2438 } 2439 2440 /** 2441 * Handles resetting the user's password. 2442 * 2443 * @since 2.5.0 2444 * 2445 * @param WP_User $user The user 2446 * @param string $new_pass New password for the user in plaintext 2447 */ 2448 function reset_password( $user, $new_pass ) { 2449 /** 2450 * Fires before the user's password is reset. 2451 * 2452 * @since 1.5.0 2453 * 2454 * @param object $user The user. 2455 * @param string $new_pass New user password. 2456 */ 2457 do_action( 'password_reset', $user, $new_pass ); 2458 2459 wp_set_password( $new_pass, $user->ID ); 2460 update_user_option( $user->ID, 'default_password_nag', false, true ); 2461 2462 /** 2463 * Fires after the user's password is reset. 2464 * 2465 * @since 4.4.0 2466 * 2467 * @param WP_User $user The user. 2468 * @param string $new_pass New user password. 2469 */ 2470 do_action( 'after_password_reset', $user, $new_pass ); 2471 } 2472 2473 /** 2474 * Handles registering a new user. 2475 * 2476 * @since 2.5.0 2477 * 2478 * @param string $user_login User's username for logging in 2479 * @param string $user_email User's email address to send password and add 2480 * @return int|WP_Error Either user's ID or error on failure. 2481 */ 2482 function register_new_user( $user_login, $user_email ) { 2483 $errors = new WP_Error(); 2484 2485 $sanitized_user_login = sanitize_user( $user_login ); 2486 /** 2487 * Filters the email address of a user being registered. 2488 * 2489 * @since 2.1.0 2490 * 2491 * @param string $user_email The email address of the new user. 2492 */ 2493 $user_email = apply_filters( 'user_registration_email', $user_email ); 2494 2495 // Check the username 2496 if ( $sanitized_user_login == '' ) { 2497 $errors->add( 'empty_username', __( '<strong>ERROR</strong>: Please enter a username.' ) ); 2498 } elseif ( ! validate_username( $user_login ) ) { 2499 $errors->add( 'invalid_username', __( '<strong>ERROR</strong>: This username is invalid because it uses illegal characters. Please enter a valid username.' ) ); 2500 $sanitized_user_login = ''; 2501 } elseif ( username_exists( $sanitized_user_login ) ) { 2502 $errors->add( 'username_exists', __( '<strong>ERROR</strong>: This username is already registered. Please choose another one.' ) ); 2503 2504 } else { 2505 /** This filter is documented in wp-includes/user.php */ 2506 $illegal_user_logins = (array) apply_filters( 'illegal_user_logins', array() ); 2507 if ( in_array( strtolower( $sanitized_user_login ), array_map( 'strtolower', $illegal_user_logins ) ) ) { 2508 $errors->add( 'invalid_username', __( '<strong>ERROR</strong>: Sorry, that username is not allowed.' ) ); 2509 } 2510 } 2511 2512 // Check the email address 2513 if ( $user_email == '' ) { 2514 $errors->add( 'empty_email', __( '<strong>ERROR</strong>: Please type your email address.' ) ); 2515 } elseif ( ! is_email( $user_email ) ) { 2516 $errors->add( 'invalid_email', __( '<strong>ERROR</strong>: The email address isn’t correct.' ) ); 2517 $user_email = ''; 2518 } elseif ( email_exists( $user_email ) ) { 2519 $errors->add( 'email_exists', __( '<strong>ERROR</strong>: This email is already registered, please choose another one.' ) ); 2520 } 2521 2522 /** 2523 * Fires when submitting registration form data, before the user is created. 2524 * 2525 * @since 2.1.0 2526 * 2527 * @param string $sanitized_user_login The submitted username after being sanitized. 2528 * @param string $user_email The submitted email. 2529 * @param WP_Error $errors Contains any errors with submitted username and email, 2530 * e.g., an empty field, an invalid username or email, 2531 * or an existing username or email. 2532 */ 2533 do_action( 'register_post', $sanitized_user_login, $user_email, $errors ); 2534 2535 /** 2536 * Filters the errors encountered when a new user is being registered. 2537 * 2538 * The filtered WP_Error object may, for example, contain errors for an invalid 2539 * or existing username or email address. A WP_Error object should always returned, 2540 * but may or may not contain errors. 2541 * 2542 * If any errors are present in $errors, this will abort the user's registration. 2543 * 2544 * @since 2.1.0 2545 * 2546 * @param WP_Error $errors A WP_Error object containing any errors encountered 2547 * during registration. 2548 * @param string $sanitized_user_login User's username after it has been sanitized. 2549 * @param string $user_email User's email. 2550 */ 2551 $errors = apply_filters( 'registration_errors', $errors, $sanitized_user_login, $user_email ); 2552 2553 if ( $errors->has_errors() ) { 2554 return $errors; 2555 } 2556 2557 $user_pass = wp_generate_password( 12, false ); 2558 $user_id = wp_create_user( $sanitized_user_login, $user_pass, $user_email ); 2559 if ( ! $user_id || is_wp_error( $user_id ) ) { 2560 $errors->add( 2561 'registerfail', 2562 sprintf( 2563 /* translators: %s: Admin email address. */ 2564 __( '<strong>ERROR</strong>: Couldn’t register you… please contact the <a href="mailto:%s">webmaster</a> !' ), 2565 get_option( 'admin_email' ) 2566 ) 2567 ); 2568 return $errors; 2569 } 2570 2571 update_user_option( $user_id, 'default_password_nag', true, true ); //Set up the Password change nag. 2572 2573 /** 2574 * Fires after a new user registration has been recorded. 2575 * 2576 * @since 4.4.0 2577 * 2578 * @param int $user_id ID of the newly registered user. 2579 */ 2580 do_action( 'register_new_user', $user_id ); 2581 2582 return $user_id; 2583 } 2584 2585 /** 2586 * Initiates email notifications related to the creation of new users. 2587 * 2588 * Notifications are sent both to the site admin and to the newly created user. 2589 * 2590 * @since 4.4.0 2591 * @since 4.6.0 Converted the `$notify` parameter to accept 'user' for sending 2592 * notifications only to the user created. 2593 * 2594 * @param int $user_id ID of the newly created user. 2595 * @param string $notify Optional. Type of notification that should happen. Accepts 'admin' 2596 * or an empty string (admin only), 'user', or 'both' (admin and user). 2597 * Default 'both'. 2598 */ 2599 function wp_send_new_user_notifications( $user_id, $notify = 'both' ) { 2600 wp_new_user_notification( $user_id, null, $notify ); 2601 } 2602 2603 /** 2604 * Retrieve the current session token from the logged_in cookie. 2605 * 2606 * @since 4.0.0 2607 * 2608 * @return string Token. 2609 */ 2610 function wp_get_session_token() { 2611 $cookie = wp_parse_auth_cookie( '', 'logged_in' ); 2612 return ! empty( $cookie['token'] ) ? $cookie['token'] : ''; 2613 } 2614 2615 /** 2616 * Retrieve a list of sessions for the current user. 2617 * 2618 * @since 4.0.0 2619 * @return array Array of sessions. 2620 */ 2621 function wp_get_all_sessions() { 2622 $manager = WP_Session_Tokens::get_instance( get_current_user_id() ); 2623 return $manager->get_all(); 2624 } 2625 2626 /** 2627 * Remove the current session token from the database. 2628 * 2629 * @since 4.0.0 2630 */ 2631 function wp_destroy_current_session() { 2632 $token = wp_get_session_token(); 2633 if ( $token ) { 2634 $manager = WP_Session_Tokens::get_instance( get_current_user_id() ); 2635 $manager->destroy( $token ); 2636 } 2637 } 2638 2639 /** 2640 * Remove all but the current session token for the current user for the database. 2641 * 2642 * @since 4.0.0 2643 */ 2644 function wp_destroy_other_sessions() { 2645 $token = wp_get_session_token(); 2646 if ( $token ) { 2647 $manager = WP_Session_Tokens::get_instance( get_current_user_id() ); 2648 $manager->destroy_others( $token ); 2649 } 2650 } 2651 2652 /** 2653 * Remove all session tokens for the current user from the database. 2654 * 2655 * @since 4.0.0 2656 */ 2657 function wp_destroy_all_sessions() { 2658 $manager = WP_Session_Tokens::get_instance( get_current_user_id() ); 2659 $manager->destroy_all(); 2660 } 2661 2662 /** 2663 * Get the user IDs of all users with no role on this site. 2664 * 2665 * @since 4.4.0 2666 * @since 4.9.0 The `$site_id` parameter was added to support multisite. 2667 * 2668 * @param int|null $site_id Optional. The site ID to get users with no role for. Defaults to the current site. 2669 * @return array Array of user IDs. 2670 */ 2671 function wp_get_users_with_no_role( $site_id = null ) { 2672 global $wpdb; 2673 2674 if ( ! $site_id ) { 2675 $site_id = get_current_blog_id(); 2676 } 2677 2678 $prefix = $wpdb->get_blog_prefix( $site_id ); 2679 2680 if ( is_multisite() && $site_id != get_current_blog_id() ) { 2681 switch_to_blog( $site_id ); 2682 $role_names = wp_roles()->get_names(); 2683 restore_current_blog(); 2684 } else { 2685 $role_names = wp_roles()->get_names(); 2686 } 2687 2688 $regex = implode( '|', array_keys( $role_names ) ); 2689 $regex = preg_replace( '/[^a-zA-Z_\|-]/', '', $regex ); 2690 $users = $wpdb->get_col( 2691 $wpdb->prepare( 2692 " 2693 SELECT user_id 2694 FROM $wpdb->usermeta 2695 WHERE meta_key = '{$prefix}capabilities' 2696 AND meta_value NOT REGEXP %s 2697 ", 2698 $regex 2699 ) 2700 ); 2701 2702 return $users; 2703 } 2704 2705 /** 2706 * Retrieves the current user object. 2707 * 2708 * Will set the current user, if the current user is not set. The current user 2709 * will be set to the logged-in person. If no user is logged-in, then it will 2710 * set the current user to 0, which is invalid and won't have any permissions. 2711 * 2712 * This function is used by the pluggable functions wp_get_current_user() and 2713 * get_currentuserinfo(), the latter of which is deprecated but used for backward 2714 * compatibility. 2715 * 2716 * @since 4.5.0 2717 * @access private 2718 * 2719 * @see wp_get_current_user() 2720 * @global WP_User $current_user Checks if the current user is set. 2721 * 2722 * @return WP_User Current WP_User instance. 2723 */ 2724 function _wp_get_current_user() { 2725 global $current_user; 2726 2727 if ( ! empty( $current_user ) ) { 2728 if ( $current_user instanceof WP_User ) { 2729 return $current_user; 2730 } 2731 2732 // Upgrade stdClass to WP_User 2733 if ( is_object( $current_user ) && isset( $current_user->ID ) ) { 2734 $cur_id = $current_user->ID; 2735 $current_user = null; 2736 wp_set_current_user( $cur_id ); 2737 return $current_user; 2738 } 2739 2740 // $current_user has a junk value. Force to WP_User with ID 0. 2741 $current_user = null; 2742 wp_set_current_user( 0 ); 2743 return $current_user; 2744 } 2745 2746 if ( defined( 'XMLRPC_REQUEST' ) && XMLRPC_REQUEST ) { 2747 wp_set_current_user( 0 ); 2748 return $current_user; 2749 } 2750 2751 /** 2752 * Filters the current user. 2753 * 2754 * The default filters use this to determine the current user from the 2755 * request's cookies, if available. 2756 * 2757 * Returning a value of false will effectively short-circuit setting 2758 * the current user. 2759 * 2760 * @since 3.9.0 2761 * 2762 * @param int|bool $user_id User ID if one has been determined, false otherwise. 2763 */ 2764 $user_id = apply_filters( 'determine_current_user', false ); 2765 if ( ! $user_id ) { 2766 wp_set_current_user( 0 ); 2767 return $current_user; 2768 } 2769 2770 wp_set_current_user( $user_id ); 2771 2772 return $current_user; 2773 } 2774 2775 /** 2776 * Send a confirmation request email when a change of user email address is attempted. 2777 * 2778 * @since 3.0.0 2779 * @since 4.9.0 This function was moved from wp-admin/includes/ms.php so it's no longer Multisite specific. 2780 * 2781 * @global WP_Error $errors WP_Error object. 2782 */ 2783 function send_confirmation_on_profile_email() { 2784 global $errors; 2785 2786 $current_user = wp_get_current_user(); 2787 if ( ! is_object( $errors ) ) { 2788 $errors = new WP_Error(); 2789 } 2790 2791 if ( $current_user->ID != $_POST['user_id'] ) { 2792 return false; 2793 } 2794 2795 if ( $current_user->user_email != $_POST['email'] ) { 2796 if ( ! is_email( $_POST['email'] ) ) { 2797 $errors->add( 2798 'user_email', 2799 __( '<strong>ERROR</strong>: The email address isn’t correct.' ), 2800 array( 2801 'form-field' => 'email', 2802 ) 2803 ); 2804 2805 return; 2806 } 2807 2808 if ( email_exists( $_POST['email'] ) ) { 2809 $errors->add( 2810 'user_email', 2811 __( '<strong>ERROR</strong>: The email address is already used.' ), 2812 array( 2813 'form-field' => 'email', 2814 ) 2815 ); 2816 delete_user_meta( $current_user->ID, '_new_email' ); 2817 2818 return; 2819 } 2820 2821 $hash = md5( $_POST['email'] . time() . wp_rand() ); 2822 $new_user_email = array( 2823 'hash' => $hash, 2824 'newemail' => $_POST['email'], 2825 ); 2826 update_user_meta( $current_user->ID, '_new_email', $new_user_email ); 2827 2828 $sitename = wp_specialchars_decode( get_option( 'blogname' ), ENT_QUOTES ); 2829 2830 /* translators: Do not translate USERNAME, ADMIN_URL, EMAIL, SITENAME, SITEURL: those are placeholders. */ 2831 $email_text = __( 2832 'Howdy ###USERNAME###, 2833 2834 You recently requested to have the email address on your account changed. 2835 2836 If this is correct, please click on the following link to change it: 2837 ###ADMIN_URL### 2838 2839 You can safely ignore and delete this email if you do not want to 2840 take this action. 2841 2842 This email has been sent to ###EMAIL### 2843 2844 Regards, 2845 All at ###SITENAME### 2846 ###SITEURL###' 2847 ); 2848 2849 /** 2850 * Filters the text of the email sent when a change of user email address is attempted. 2851 * 2852 * The following strings have a special meaning and will get replaced dynamically: 2853 * ###USERNAME### The current user's username. 2854 * ###ADMIN_URL### The link to click on to confirm the email change. 2855 * ###EMAIL### The new email. 2856 * ###SITENAME### The name of the site. 2857 * ###SITEURL### The URL to the site. 2858 * 2859 * @since MU (3.0.0) 2860 * @since 4.9.0 This filter is no longer Multisite specific. 2861 * 2862 * @param string $email_text Text in the email. 2863 * @param array $new_user_email { 2864 * Data relating to the new user email address. 2865 * 2866 * @type string $hash The secure hash used in the confirmation link URL. 2867 * @type string $newemail The proposed new email address. 2868 * } 2869 */ 2870 $content = apply_filters( 'new_user_email_content', $email_text, $new_user_email ); 2871 2872 $content = str_replace( '###USERNAME###', $current_user->user_login, $content ); 2873 $content = str_replace( '###ADMIN_URL###', esc_url( admin_url( 'profile.php?newuseremail=' . $hash ) ), $content ); 2874 $content = str_replace( '###EMAIL###', $_POST['email'], $content ); 2875 $content = str_replace( '###SITENAME###', $sitename, $content ); 2876 $content = str_replace( '###SITEURL###', home_url(), $content ); 2877 2878 /* translators: New email address notification email subject. %s: Site title. */ 2879 wp_mail( $_POST['email'], sprintf( __( '[%s] Email Change Request' ), $sitename ), $content ); 2880 2881 $_POST['email'] = $current_user->user_email; 2882 } 2883 } 2884 2885 /** 2886 * Adds an admin notice alerting the user to check for confirmation request email 2887 * after email address change. 2888 * 2889 * @since 3.0.0 2890 * @since 4.9.0 This function was moved from wp-admin/includes/ms.php so it's no longer Multisite specific. 2891 * 2892 * @global string $pagenow 2893 */ 2894 function new_user_email_admin_notice() { 2895 global $pagenow; 2896 2897 if ( 'profile.php' === $pagenow && isset( $_GET['updated'] ) ) { 2898 $email = get_user_meta( get_current_user_id(), '_new_email', true ); 2899 if ( $email ) { 2900 /* translators: %s: New email address. */ 2901 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>'; 2902 } 2903 } 2904 } 2905 2906 /** 2907 * Get all user privacy request types. 2908 * 2909 * @since 4.9.6 2910 * @access private 2911 * 2912 * @return array List of core privacy action types. 2913 */ 2914 function _wp_privacy_action_request_types() { 2915 return array( 2916 'export_personal_data', 2917 'remove_personal_data', 2918 ); 2919 } 2920 2921 /** 2922 * Registers the personal data exporter for users. 2923 * 2924 * @since 4.9.6 2925 * 2926 * @param array $exporters An array of personal data exporters. 2927 * @return array An array of personal data exporters. 2928 */ 2929 function wp_register_user_personal_data_exporter( $exporters ) { 2930 $exporters['wordpress-user'] = array( 2931 'exporter_friendly_name' => __( 'WordPress User' ), 2932 'callback' => 'wp_user_personal_data_exporter', 2933 ); 2934 2935 return $exporters; 2936 } 2937 2938 /** 2939 * Finds and exports personal data associated with an email address from the user and user_meta table. 2940 * 2941 * @since 4.9.6 2942 * 2943 * @param string $email_address The users email address. 2944 * @return array An array of personal data. 2945 */ 2946 function wp_user_personal_data_exporter( $email_address ) { 2947 $email_address = trim( $email_address ); 2948 2949 $data_to_export = array(); 2950 2951 $user = get_user_by( 'email', $email_address ); 2952 2953 if ( ! $user ) { 2954 return array( 2955 'data' => array(), 2956 'done' => true, 2957 ); 2958 } 2959 2960 $user_meta = get_user_meta( $user->ID ); 2961 2962 $user_prop_to_export = array( 2963 'ID' => __( 'User ID' ), 2964 'user_login' => __( 'User Login Name' ), 2965 'user_nicename' => __( 'User Nice Name' ), 2966 'user_email' => __( 'User Email' ), 2967 'user_url' => __( 'User URL' ), 2968 'user_registered' => __( 'User Registration Date' ), 2969 'display_name' => __( 'User Display Name' ), 2970 'nickname' => __( 'User Nickname' ), 2971 'first_name' => __( 'User First Name' ), 2972 'last_name' => __( 'User Last Name' ), 2973 'description' => __( 'User Description' ), 2974 ); 2975 2976 $user_data_to_export = array(); 2977 2978 foreach ( $user_prop_to_export as $key => $name ) { 2979 $value = ''; 2980 2981 switch ( $key ) { 2982 case 'ID': 2983 case 'user_login': 2984 case 'user_nicename': 2985 case 'user_email': 2986 case 'user_url': 2987 case 'user_registered': 2988 case 'display_name': 2989 $value = $user->data->$key; 2990 break; 2991 case 'nickname': 2992 case 'first_name': 2993 case 'last_name': 2994 case 'description': 2995 $value = $user_meta[ $key ][0]; 2996 break; 2997 } 2998 2999 if ( ! empty( $value ) ) { 3000 $user_data_to_export[] = array( 3001 'name' => $name, 3002 'value' => $value, 3003 ); 3004 } 3005 } 3006 3007 $data_to_export[] = array( 3008 'group_id' => 'user', 3009 'group_label' => __( 'User' ), 3010 'group_description' => __( 'User’s profile data.' ), 3011 'item_id' => "user-{$user->ID}", 3012 'data' => $user_data_to_export, 3013 ); 3014 3015 return array( 3016 'data' => $data_to_export, 3017 'done' => true, 3018 ); 3019 } 3020 3021 /** 3022 * Update log when privacy request is confirmed. 3023 * 3024 * @since 4.9.6 3025 * @access private 3026 * 3027 * @param int $request_id ID of the request. 3028 */ 3029 function _wp_privacy_account_request_confirmed( $request_id ) { 3030 $request = wp_get_user_request_data( $request_id ); 3031 3032 if ( ! $request ) { 3033 return; 3034 } 3035 3036 if ( ! in_array( $request->status, array( 'request-pending', 'request-failed' ), true ) ) { 3037 return; 3038 } 3039 3040 update_post_meta( $request_id, '_wp_user_request_confirmed_timestamp', time() ); 3041 wp_update_post( 3042 array( 3043 'ID' => $request_id, 3044 'post_status' => 'request-confirmed', 3045 ) 3046 ); 3047 } 3048 3049 /** 3050 * Notify the site administrator via email when a request is confirmed. 3051 * 3052 * Without this, the admin would have to manually check the site to see if any 3053 * action was needed on their part yet. 3054 * 3055 * @since 4.9.6 3056 * 3057 * @param int $request_id The ID of the request. 3058 */ 3059 function _wp_privacy_send_request_confirmation_notification( $request_id ) { 3060 $request = wp_get_user_request_data( $request_id ); 3061 3062 if ( ! is_a( $request, 'WP_User_Request' ) || 'request-confirmed' !== $request->status ) { 3063 return; 3064 } 3065 3066 $already_notified = (bool) get_post_meta( $request_id, '_wp_admin_notified', true ); 3067 3068 if ( $already_notified ) { 3069 return; 3070 } 3071 3072 $manage_url = add_query_arg( 'page', $request->action_name, admin_url( 'tools.php' ) ); 3073 $action_description = wp_user_request_action_description( $request->action_name ); 3074 3075 /** 3076 * Filters the recipient of the data request confirmation notification. 3077 * 3078 * In a Multisite environment, this will default to the email address of the 3079 * network admin because, by default, single site admins do not have the 3080 * capabilities required to process requests. Some networks may wish to 3081 * delegate those capabilities to a single-site admin, or a dedicated person 3082 * responsible for managing privacy requests. 3083 * 3084 * @since 4.9.6 3085 * 3086 * @param string $admin_email The email address of the notification recipient. 3087 * @param WP_User_Request $request The request that is initiating the notification. 3088 */ 3089 $admin_email = apply_filters( 'user_request_confirmed_email_to', get_site_option( 'admin_email' ), $request ); 3090 3091 $email_data = array( 3092 'request' => $request, 3093 'user_email' => $request->email, 3094 'description' => $action_description, 3095 'manage_url' => $manage_url, 3096 'sitename' => wp_specialchars_decode( get_option( 'blogname' ), ENT_QUOTES ), 3097 'siteurl' => home_url(), 3098 'admin_email' => $admin_email, 3099 ); 3100 3101 /* translators: Do not translate SITENAME, USER_EMAIL, DESCRIPTION, MANAGE_URL, SITEURL; those are placeholders. */ 3102 $email_text = __( 3103 'Howdy, 3104 3105 A user data privacy request has been confirmed on ###SITENAME###: 3106 3107 User: ###USER_EMAIL### 3108 Request: ###DESCRIPTION### 3109 3110 You can view and manage these data privacy requests here: 3111 3112 ###MANAGE_URL### 3113 3114 Regards, 3115 All at ###SITENAME### 3116 ###SITEURL###' 3117 ); 3118 3119 /** 3120 * Filters the body of the user request confirmation email. 3121 * 3122 * The email is sent to an administrator when an user request is confirmed. 3123 * The following strings have a special meaning and will get replaced dynamically: 3124 * 3125 * ###SITENAME### The name of the site. 3126 * ###USER_EMAIL### The user email for the request. 3127 * ###DESCRIPTION### Description of the action being performed so the user knows what the email is for. 3128 * ###MANAGE_URL### The URL to manage requests. 3129 * ###SITEURL### The URL to the site. 3130 * 3131 * @since 4.9.6 3132 * 3133 * @param string $email_text Text in the email. 3134 * @param array $email_data { 3135 * Data relating to the account action email. 3136 * 3137 * @type WP_User_Request $request User request object. 3138 * @type string $user_email The email address confirming a request 3139 * @type string $description Description of the action being performed so the user knows what the email is for. 3140 * @type string $manage_url The link to click manage privacy requests of this type. 3141 * @type string $sitename The site name sending the mail. 3142 * @type string $siteurl The site URL sending the mail. 3143 * @type string $admin_email The administrator email receiving the mail. 3144 * } 3145 */ 3146 $content = apply_filters( 'user_confirmed_action_email_content', $email_text, $email_data ); 3147 3148 $content = str_replace( '###SITENAME###', $email_data['sitename'], $content ); 3149 $content = str_replace( '###USER_EMAIL###', $email_data['user_email'], $content ); 3150 $content = str_replace( '###DESCRIPTION###', $email_data['description'], $content ); 3151 $content = str_replace( '###MANAGE_URL###', esc_url_raw( $email_data['manage_url'] ), $content ); 3152 $content = str_replace( '###SITEURL###', esc_url_raw( $email_data['siteurl'] ), $content ); 3153 3154 $subject = sprintf( 3155 /* translators: Privacy data request confirmed notification email subject. 1: Site title, 2: Name of the confirmed action. */ 3156 __( '[%1$s] Action Confirmed: %2$s' ), 3157 $email_data['sitename'], 3158 $action_description 3159 ); 3160 3161 /** 3162 * Filters the subject of the user request confirmation email. 3163 * 3164 * @since 4.9.8 3165 * 3166 * @param string $subject The email subject. 3167 * @param string $sitename The name of the site. 3168 * @param array $email_data { 3169 * Data relating to the account action email. 3170 * 3171 * @type WP_User_Request $request User request object. 3172 * @type string $user_email The email address confirming a request 3173 * @type string $description Description of the action being performed so the user knows what the email is for. 3174 * @type string $manage_url The link to click manage privacy requests of this type. 3175 * @type string $sitename The site name sending the mail. 3176 * @type string $siteurl The site URL sending the mail. 3177 * @type string $admin_email The administrator email receiving the mail. 3178 * } 3179 */ 3180 $subject = apply_filters( 'user_request_confirmed_email_subject', $subject, $email_data['sitename'], $email_data ); 3181 3182 $email_sent = wp_mail( $email_data['admin_email'], $subject, $content ); 3183 3184 if ( $email_sent ) { 3185 update_post_meta( $request_id, '_wp_admin_notified', true ); 3186 } 3187 } 3188 3189 /** 3190 * Notify the user when their erasure request is fulfilled. 3191 * 3192 * Without this, the user would never know if their data was actually erased. 3193 * 3194 * @since 4.9.6 3195 * 3196 * @param int $request_id The privacy request post ID associated with this request. 3197 */ 3198 function _wp_privacy_send_erasure_fulfillment_notification( $request_id ) { 3199 $request = wp_get_user_request_data( $request_id ); 3200 3201 if ( ! is_a( $request, 'WP_User_Request' ) || 'request-completed' !== $request->status ) { 3202 return; 3203 } 3204 3205 $already_notified = (bool) get_post_meta( $request_id, '_wp_user_notified', true ); 3206 3207 if ( $already_notified ) { 3208 return; 3209 } 3210 3211 // Localize message content for user; fallback to site default for visitors. 3212 if ( ! empty( $request->user_id ) ) { 3213 $locale = get_user_locale( $request->user_id ); 3214 } else { 3215 $locale = get_locale(); 3216 } 3217 3218 $switched_locale = switch_to_locale( $locale ); 3219 3220 /** 3221 * Filters the recipient of the data erasure fulfillment notification. 3222 * 3223 * @since 4.9.6 3224 * 3225 * @param string $user_email The email address of the notification recipient. 3226 * @param WP_User_Request $request The request that is initiating the notification. 3227 */ 3228 $user_email = apply_filters( 'user_erasure_fulfillment_email_to', $request->email, $request ); 3229 3230 $email_data = array( 3231 'request' => $request, 3232 'message_recipient' => $user_email, 3233 'privacy_policy_url' => get_privacy_policy_url(), 3234 'sitename' => wp_specialchars_decode( get_option( 'blogname' ), ENT_QUOTES ), 3235 'siteurl' => home_url(), 3236 ); 3237 3238 $subject = sprintf( 3239 /* translators: Erasure request fulfilled notification email subject. %s: Site title. */ 3240 __( '[%s] Erasure Request Fulfilled' ), 3241 $email_data['sitename'] 3242 ); 3243 3244 /** 3245 * Filters the subject of the email sent when an erasure request is completed. 3246 * 3247 * @since 4.9.8 3248 * 3249 * @param string $subject The email subject. 3250 * @param string $sitename The name of the site. 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 $subject = apply_filters( 'user_erasure_complete_email_subject', $subject, $email_data['sitename'], $email_data ); 3264 3265 if ( empty( $email_data['privacy_policy_url'] ) ) { 3266 /* translators: Do not translate SITENAME, SITEURL; those are placeholders. */ 3267 $email_text = __( 3268 'Howdy, 3269 3270 Your request to erase your personal data on ###SITENAME### has been completed. 3271 3272 If you have any follow-up questions or concerns, please contact the site administrator. 3273 3274 Regards, 3275 All at ###SITENAME### 3276 ###SITEURL###' 3277 ); 3278 } else { 3279 /* translators: Do not translate SITENAME, SITEURL, PRIVACY_POLICY_URL; those are placeholders. */ 3280 $email_text = __( 3281 'Howdy, 3282 3283 Your request to erase your personal data on ###SITENAME### has been completed. 3284 3285 If you have any follow-up questions or concerns, please contact the site administrator. 3286 3287 For more information, you can also read our privacy policy: ###PRIVACY_POLICY_URL### 3288 3289 Regards, 3290 All at ###SITENAME### 3291 ###SITEURL###' 3292 ); 3293 } 3294 3295 /** 3296 * Filters the body of the data erasure fulfillment notification. 3297 * 3298 * The email is sent to a user when a their data erasure request is fulfilled 3299 * by an administrator. 3300 * 3301 * The following strings have a special meaning and will get replaced dynamically: 3302 * 3303 * ###SITENAME### The name of the site. 3304 * ###PRIVACY_POLICY_URL### Privacy policy page URL. 3305 * ###SITEURL### The URL to the site. 3306 * 3307 * @since 4.9.6 3308 * 3309 * @param string $email_text Text in the email. 3310 * @param array $email_data { 3311 * Data relating to the account action email. 3312 * 3313 * @type WP_User_Request $request User request object. 3314 * @type string $message_recipient The address that the email will be sent to. Defaults 3315 * to the value of `$request->email`, but can be changed 3316 * by the `user_erasure_fulfillment_email_to` filter. 3317 * @type string $privacy_policy_url Privacy policy URL. 3318 * @type string $sitename The site name sending the mail. 3319 * @type string $siteurl The site URL sending the mail. 3320 * } 3321 */ 3322 $content = apply_filters( 'user_confirmed_action_email_content', $email_text, $email_data ); 3323 3324 $content = str_replace( '###SITENAME###', $email_data['sitename'], $content ); 3325 $content = str_replace( '###PRIVACY_POLICY_URL###', $email_data['privacy_policy_url'], $content ); 3326 $content = str_replace( '###SITEURL###', esc_url_raw( $email_data['siteurl'] ), $content ); 3327 3328 $email_sent = wp_mail( $user_email, $subject, $content ); 3329 3330 if ( $switched_locale ) { 3331 restore_previous_locale(); 3332 } 3333 3334 if ( $email_sent ) { 3335 update_post_meta( $request_id, '_wp_user_notified', true ); 3336 } 3337 } 3338 3339 /** 3340 * Return request confirmation message HTML. 3341 * 3342 * @since 4.9.6 3343 * @access private 3344 * 3345 * @param int $request_id The request ID being confirmed. 3346 * @return string $message The confirmation message. 3347 */ 3348 function _wp_privacy_account_request_confirmed_message( $request_id ) { 3349 $request = wp_get_user_request_data( $request_id ); 3350 3351 $message = '<p class="success">' . __( 'Action has been confirmed.' ) . '</p>'; 3352 $message .= '<p>' . __( 'The site administrator has been notified and will fulfill your request as soon as possible.' ) . '</p>'; 3353 3354 if ( $request && in_array( $request->action_name, _wp_privacy_action_request_types(), true ) ) { 3355 if ( 'export_personal_data' === $request->action_name ) { 3356 $message = '<p class="success">' . __( 'Thanks for confirming your export request.' ) . '</p>'; 3357 $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>'; 3358 } elseif ( 'remove_personal_data' === $request->action_name ) { 3359 $message = '<p class="success">' . __( 'Thanks for confirming your erasure request.' ) . '</p>'; 3360 $message .= '<p>' . __( 'The site administrator has been notified. You will receive an email confirmation when they erase your data.' ) . '</p>'; 3361 } 3362 } 3363 3364 /** 3365 * Filters the message displayed to a user when they confirm a data request. 3366 * 3367 * @since 4.9.6 3368 * 3369 * @param string $message The message to the user. 3370 * @param int $request_id The ID of the request being confirmed. 3371 */ 3372 $message = apply_filters( 'user_request_action_confirmed_message', $message, $request_id ); 3373 3374 return $message; 3375 } 3376 3377 /** 3378 * Create and log a user request to perform a specific action. 3379 * 3380 * Requests are stored inside a post type named `user_request` since they can apply to both 3381 * users on the site, or guests without a user account. 3382 * 3383 * @since 4.9.6 3384 * 3385 * @param string $email_address User email address. This can be the address of a registered or non-registered user. 3386 * @param string $action_name Name of the action that is being confirmed. Required. 3387 * @param array $request_data Misc data you want to send with the verification request and pass to the actions once the request is confirmed. 3388 * @return int|WP_Error Returns the request ID if successful, or a WP_Error object on failure. 3389 */ 3390 function wp_create_user_request( $email_address = '', $action_name = '', $request_data = array() ) { 3391 $email_address = sanitize_email( $email_address ); 3392 $action_name = sanitize_key( $action_name ); 3393 3394 if ( ! is_email( $email_address ) ) { 3395 return new WP_Error( 'invalid_email', __( 'Invalid email address.' ) ); 3396 } 3397 3398 if ( ! $action_name ) { 3399 return new WP_Error( 'invalid_action', __( 'Invalid action name.' ) ); 3400 } 3401 3402 $user = get_user_by( 'email', $email_address ); 3403 $user_id = $user && ! is_wp_error( $user ) ? $user->ID : 0; 3404 3405 // Check for duplicates. 3406 $requests_query = new WP_Query( 3407 array( 3408 'post_type' => 'user_request', 3409 'post_name__in' => array( $action_name ), // Action name stored in post_name column. 3410 'title' => $email_address, // Email address stored in post_title column. 3411 'post_status' => array( 3412 'request-pending', 3413 'request-confirmed', 3414 ), 3415 'fields' => 'ids', 3416 ) 3417 ); 3418 3419 if ( $requests_query->found_posts ) { 3420 return new WP_Error( 'duplicate_request', __( 'An incomplete request for this email address already exists.' ) ); 3421 } 3422 3423 $request_id = wp_insert_post( 3424 array( 3425 'post_author' => $user_id, 3426 'post_name' => $action_name, 3427 'post_title' => $email_address, 3428 'post_content' => wp_json_encode( $request_data ), 3429 'post_status' => 'request-pending', 3430 'post_type' => 'user_request', 3431 'post_date' => current_time( 'mysql', false ), 3432 'post_date_gmt' => current_time( 'mysql', true ), 3433 ), 3434 true 3435 ); 3436 3437 return $request_id; 3438 } 3439 3440 /** 3441 * Get action description from the name and return a string. 3442 * 3443 * @since 4.9.6 3444 * 3445 * @param string $action_name Action name of the request. 3446 * @return string Human readable action name. 3447 */ 3448 function wp_user_request_action_description( $action_name ) { 3449 switch ( $action_name ) { 3450 case 'export_personal_data': 3451 $description = __( 'Export Personal Data' ); 3452 break; 3453 case 'remove_personal_data': 3454 $description = __( 'Erase Personal Data' ); 3455 break; 3456 default: 3457 /* translators: %s: Action name. */ 3458 $description = sprintf( __( 'Confirm the "%s" action' ), $action_name ); 3459 break; 3460 } 3461 3462 /** 3463 * Filters the user action description. 3464 * 3465 * @since 4.9.6 3466 * 3467 * @param string $description The default description. 3468 * @param string $action_name The name of the request. 3469 */ 3470 return apply_filters( 'user_request_action_description', $description, $action_name ); 3471 } 3472 3473 /** 3474 * Send a confirmation request email to confirm an action. 3475 * 3476 * If the request is not already pending, it will be updated. 3477 * 3478 * @since 4.9.6 3479 * 3480 * @param string $request_id ID of the request created via wp_create_user_request(). 3481 * @return bool|WP_Error True on success, `WP_Error` on failure. 3482 */ 3483 function wp_send_user_request( $request_id ) { 3484 $request_id = absint( $request_id ); 3485 $request = wp_get_user_request_data( $request_id ); 3486 3487 if ( ! $request ) { 3488 return new WP_Error( 'invalid_request', __( 'Invalid user request.' ) ); 3489 } 3490 3491 // Localize message content for user; fallback to site default for visitors. 3492 if ( ! empty( $request->user_id ) ) { 3493 $locale = get_user_locale( $request->user_id ); 3494 } else { 3495 $locale = get_locale(); 3496 } 3497 3498 $switched_locale = switch_to_locale( $locale ); 3499 3500 $email_data = array( 3501 'request' => $request, 3502 'email' => $request->email, 3503 'description' => wp_user_request_action_description( $request->action_name ), 3504 'confirm_url' => add_query_arg( 3505 array( 3506 'action' => 'confirmaction', 3507 'request_id' => $request_id, 3508 'confirm_key' => wp_generate_user_request_key( $request_id ), 3509 ), 3510 wp_login_url() 3511 ), 3512 'sitename' => wp_specialchars_decode( get_option( 'blogname' ), ENT_QUOTES ), 3513 'siteurl' => home_url(), 3514 ); 3515 3516 /* translators: Do not translate DESCRIPTION, CONFIRM_URL, SITENAME, SITEURL: those are placeholders. */ 3517 $email_text = __( 3518 'Howdy, 3519 3520 A request has been made to perform the following action on your account: 3521 3522 ###DESCRIPTION### 3523 3524 To confirm this, please click on the following link: 3525 ###CONFIRM_URL### 3526 3527 You can safely ignore and delete this email if you do not want to 3528 take this action. 3529 3530 Regards, 3531 All at ###SITENAME### 3532 ###SITEURL###' 3533 ); 3534 3535 /** 3536 * Filters the text of the email sent when an account action is attempted. 3537 * 3538 * The following strings have a special meaning and will get replaced dynamically: 3539 * 3540 * ###DESCRIPTION### Description of the action being performed so the user knows what the email is for. 3541 * ###CONFIRM_URL### The link to click on to confirm the account action. 3542 * ###SITENAME### The name of the site. 3543 * ###SITEURL### The URL to the site. 3544 * 3545 * @since 4.9.6 3546 * 3547 * @param string $email_text Text in the email. 3548 * @param array $email_data { 3549 * Data relating to the account action email. 3550 * 3551 * @type WP_User_Request $request User request object. 3552 * @type string $email The email address this is being sent to. 3553 * @type string $description Description of the action being performed so the user knows what the email is for. 3554 * @type string $confirm_url The link to click on to confirm the account action. 3555 * @type string $sitename The site name sending the mail. 3556 * @type string $siteurl The site URL sending the mail. 3557 * } 3558 */ 3559 $content = apply_filters( 'user_request_action_email_content', $email_text, $email_data ); 3560 3561 $content = str_replace( '###DESCRIPTION###', $email_data['description'], $content ); 3562 $content = str_replace( '###CONFIRM_URL###', esc_url_raw( $email_data['confirm_url'] ), $content ); 3563 $content = str_replace( '###EMAIL###', $email_data['email'], $content ); 3564 $content = str_replace( '###SITENAME###', $email_data['sitename'], $content ); 3565 $content = str_replace( '###SITEURL###', esc_url_raw( $email_data['siteurl'] ), $content ); 3566 3567 /* translators: Confirm privacy data request notification email subject. 1: Site title, 2: Name of the action. */ 3568 $subject = sprintf( __( '[%1$s] Confirm Action: %2$s' ), $email_data['sitename'], $email_data['description'] ); 3569 3570 /** 3571 * Filters the subject of the email sent when an account action is attempted. 3572 * 3573 * @since 4.9.6 3574 * 3575 * @param string $subject The email subject. 3576 * @param string $sitename The name of the site. 3577 * @param array $email_data { 3578 * Data relating to the account action email. 3579 * 3580 * @type WP_User_Request $request User request object. 3581 * @type string $email The email address this is being sent to. 3582 * @type string $description Description of the action being performed so the user knows what the email is for. 3583 * @type string $confirm_url The link to click on to confirm the account action. 3584 * @type string $sitename The site name sending the mail. 3585 * @type string $siteurl The site URL sending the mail. 3586 * } 3587 */ 3588 $subject = apply_filters( 'user_request_action_email_subject', $subject, $email_data['sitename'], $email_data ); 3589 3590 $email_sent = wp_mail( $email_data['email'], $subject, $content ); 3591 3592 if ( $switched_locale ) { 3593 restore_previous_locale(); 3594 } 3595 3596 if ( ! $email_sent ) { 3597 return new WP_Error( 'privacy_email_error', __( 'Unable to send personal data export confirmation email.' ) ); 3598 } 3599 3600 return true; 3601 } 3602 3603 /** 3604 * Returns a confirmation key for a user action and stores the hashed version for future comparison. 3605 * 3606 * @since 4.9.6 3607 * 3608 * @param int $request_id Request ID. 3609 * @return string Confirmation key. 3610 */ 3611 function wp_generate_user_request_key( $request_id ) { 3612 global $wp_hasher; 3613 3614 // Generate something random for a confirmation key. 3615 $key = wp_generate_password( 20, false ); 3616 3617 // Return the key, hashed. 3618 if ( empty( $wp_hasher ) ) { 3619 require_once ABSPATH . WPINC . '/class-phpass.php'; 3620 $wp_hasher = new PasswordHash( 8, true ); 3621 } 3622 3623 wp_update_post( 3624 array( 3625 'ID' => $request_id, 3626 'post_status' => 'request-pending', 3627 'post_password' => $wp_hasher->HashPassword( $key ), 3628 ) 3629 ); 3630 3631 return $key; 3632 } 3633 3634 /** 3635 * Validate a user request by comparing the key with the request's key. 3636 * 3637 * @since 4.9.6 3638 * 3639 * @param string $request_id ID of the request being confirmed. 3640 * @param string $key Provided key to validate. 3641 * @return bool|WP_Error WP_Error on failure, true on success. 3642 */ 3643 function wp_validate_user_request_key( $request_id, $key ) { 3644 global $wp_hasher; 3645 3646 $request_id = absint( $request_id ); 3647 $request = wp_get_user_request_data( $request_id ); 3648 3649 if ( ! $request ) { 3650 return new WP_Error( 'invalid_request', __( 'Invalid request.' ) ); 3651 } 3652 3653 if ( ! in_array( $request->status, array( 'request-pending', 'request-failed' ), true ) ) { 3654 return new WP_Error( 'expired_link', __( 'This link has expired.' ) ); 3655 } 3656 3657 if ( empty( $key ) ) { 3658 return new WP_Error( 'missing_key', __( 'Missing confirm key.' ) ); 3659 } 3660 3661 if ( empty( $wp_hasher ) ) { 3662 require_once ABSPATH . WPINC . '/class-phpass.php'; 3663 $wp_hasher = new PasswordHash( 8, true ); 3664 } 3665 3666 $key_request_time = $request->modified_timestamp; 3667 $saved_key = $request->confirm_key; 3668 3669 if ( ! $saved_key ) { 3670 return new WP_Error( 'invalid_key', __( 'Invalid key.' ) ); 3671 } 3672 3673 if ( ! $key_request_time ) { 3674 return new WP_Error( 'invalid_key', __( 'Invalid action.' ) ); 3675 } 3676 3677 /** 3678 * Filters the expiration time of confirm keys. 3679 * 3680 * @since 4.9.6 3681 * 3682 * @param int $expiration The expiration time in seconds. 3683 */ 3684 $expiration_duration = (int) apply_filters( 'user_request_key_expiration', DAY_IN_SECONDS ); 3685 $expiration_time = $key_request_time + $expiration_duration; 3686 3687 if ( ! $wp_hasher->CheckPassword( $key, $saved_key ) ) { 3688 return new WP_Error( 'invalid_key', __( 'Invalid key.' ) ); 3689 } 3690 3691 if ( ! $expiration_time || time() > $expiration_time ) { 3692 return new WP_Error( 'expired_key', __( 'The confirmation email has expired.' ) ); 3693 } 3694 3695 return true; 3696 } 3697 3698 /** 3699 * Return data about a user request. 3700 * 3701 * @since 4.9.6 3702 * 3703 * @param int $request_id Request ID to get data about. 3704 * @return WP_User_Request|false 3705 */ 3706 function wp_get_user_request_data( $request_id ) { 3707 $request_id = absint( $request_id ); 3708 $post = get_post( $request_id ); 3709 3710 if ( ! $post || 'user_request' !== $post->post_type ) { 3711 return false; 3712 } 3713 3714 return new WP_User_Request( $post ); 3715 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated: Sat Sep 21 01:00:03 2019 | Cross-referenced by PHPXref 0.7.1 |