| [ Index ] |
PHP Cross Reference of WordPress Trunk (Updated Daily) |
[Summary view] [Print] [Text view]
1 <?php 2 /** 3 * REST API: WP_REST_Users_Controller class 4 * 5 * @package WordPress 6 * @subpackage REST_API 7 * @since 4.7.0 8 */ 9 10 /** 11 * Core class used to manage users via the REST API. 12 * 13 * @since 4.7.0 14 * 15 * @see WP_REST_Controller 16 */ 17 class WP_REST_Users_Controller extends WP_REST_Controller { 18 19 /** 20 * Instance of a user meta fields object. 21 * 22 * @since 4.7.0 23 * @var WP_REST_User_Meta_Fields 24 */ 25 protected $meta; 26 27 /** 28 * Constructor. 29 * 30 * @since 4.7.0 31 */ 32 public function __construct() { 33 $this->namespace = 'wp/v2'; 34 $this->rest_base = 'users'; 35 36 $this->meta = new WP_REST_User_Meta_Fields(); 37 } 38 39 /** 40 * Registers the routes for users. 41 * 42 * @since 4.7.0 43 * 44 * @see register_rest_route() 45 */ 46 public function register_routes() { 47 48 register_rest_route( 49 $this->namespace, 50 '/' . $this->rest_base, 51 array( 52 array( 53 'methods' => WP_REST_Server::READABLE, 54 'callback' => array( $this, 'get_items' ), 55 'permission_callback' => array( $this, 'get_items_permissions_check' ), 56 'args' => $this->get_collection_params(), 57 ), 58 array( 59 'methods' => WP_REST_Server::CREATABLE, 60 'callback' => array( $this, 'create_item' ), 61 'permission_callback' => array( $this, 'create_item_permissions_check' ), 62 'args' => $this->get_endpoint_args_for_item_schema( WP_REST_Server::CREATABLE ), 63 ), 64 'schema' => array( $this, 'get_public_item_schema' ), 65 ) 66 ); 67 68 register_rest_route( 69 $this->namespace, 70 '/' . $this->rest_base . '/(?P<id>[\d]+)', 71 array( 72 'args' => array( 73 'id' => array( 74 'description' => __( 'Unique identifier for the user.' ), 75 'type' => 'integer', 76 ), 77 ), 78 array( 79 'methods' => WP_REST_Server::READABLE, 80 'callback' => array( $this, 'get_item' ), 81 'permission_callback' => array( $this, 'get_item_permissions_check' ), 82 'args' => array( 83 'context' => $this->get_context_param( array( 'default' => 'view' ) ), 84 ), 85 ), 86 array( 87 'methods' => WP_REST_Server::EDITABLE, 88 'callback' => array( $this, 'update_item' ), 89 'permission_callback' => array( $this, 'update_item_permissions_check' ), 90 'args' => $this->get_endpoint_args_for_item_schema( WP_REST_Server::EDITABLE ), 91 ), 92 array( 93 'methods' => WP_REST_Server::DELETABLE, 94 'callback' => array( $this, 'delete_item' ), 95 'permission_callback' => array( $this, 'delete_item_permissions_check' ), 96 'args' => array( 97 'force' => array( 98 'type' => 'boolean', 99 'default' => false, 100 'description' => __( 'Required to be true, as users do not support trashing.' ), 101 ), 102 'reassign' => array( 103 'type' => 'integer', 104 'description' => __( 'Reassign the deleted user\'s posts and links to this user ID.' ), 105 'required' => true, 106 'sanitize_callback' => array( $this, 'check_reassign' ), 107 ), 108 ), 109 ), 110 'schema' => array( $this, 'get_public_item_schema' ), 111 ) 112 ); 113 114 register_rest_route( 115 $this->namespace, 116 '/' . $this->rest_base . '/me', 117 array( 118 array( 119 'methods' => WP_REST_Server::READABLE, 120 'permission_callback' => '__return_true', 121 'callback' => array( $this, 'get_current_item' ), 122 'args' => array( 123 'context' => $this->get_context_param( array( 'default' => 'view' ) ), 124 ), 125 ), 126 array( 127 'methods' => WP_REST_Server::EDITABLE, 128 'callback' => array( $this, 'update_current_item' ), 129 'permission_callback' => array( $this, 'update_current_item_permissions_check' ), 130 'args' => $this->get_endpoint_args_for_item_schema( WP_REST_Server::EDITABLE ), 131 ), 132 array( 133 'methods' => WP_REST_Server::DELETABLE, 134 'callback' => array( $this, 'delete_current_item' ), 135 'permission_callback' => array( $this, 'delete_current_item_permissions_check' ), 136 'args' => array( 137 'force' => array( 138 'type' => 'boolean', 139 'default' => false, 140 'description' => __( 'Required to be true, as users do not support trashing.' ), 141 ), 142 'reassign' => array( 143 'type' => 'integer', 144 'description' => __( 'Reassign the deleted user\'s posts and links to this user ID.' ), 145 'required' => true, 146 'sanitize_callback' => array( $this, 'check_reassign' ), 147 ), 148 ), 149 ), 150 'schema' => array( $this, 'get_public_item_schema' ), 151 ) 152 ); 153 } 154 155 /** 156 * Checks for a valid value for the reassign parameter when deleting users. 157 * 158 * The value can be an integer, 'false', false, or ''. 159 * 160 * @since 4.7.0 161 * 162 * @param int|bool $value The value passed to the reassign parameter. 163 * @param WP_REST_Request $request Full details about the request. 164 * @param string $param The parameter that is being sanitized. 165 * @return int|bool|WP_Error 166 */ 167 public function check_reassign( $value, $request, $param ) { 168 if ( is_numeric( $value ) ) { 169 return $value; 170 } 171 172 if ( empty( $value ) || false === $value || 'false' === $value ) { 173 return false; 174 } 175 176 return new WP_Error( 177 'rest_invalid_param', 178 __( 'Invalid user parameter(s).' ), 179 array( 'status' => 400 ) 180 ); 181 } 182 183 /** 184 * Permissions check for getting all users. 185 * 186 * @since 4.7.0 187 * 188 * @param WP_REST_Request $request Full details about the request. 189 * @return true|WP_Error True if the request has read access, otherwise WP_Error object. 190 */ 191 public function get_items_permissions_check( $request ) { 192 // Check if roles is specified in GET request and if user can list users. 193 if ( ! empty( $request['roles'] ) && ! current_user_can( 'list_users' ) ) { 194 return new WP_Error( 195 'rest_user_cannot_view', 196 __( 'Sorry, you are not allowed to filter users by role.' ), 197 array( 'status' => rest_authorization_required_code() ) 198 ); 199 } 200 201 // Check if capabilities is specified in GET request and if user can list users. 202 if ( ! empty( $request['capabilities'] ) && ! current_user_can( 'list_users' ) ) { 203 return new WP_Error( 204 'rest_user_cannot_view', 205 __( 'Sorry, you are not allowed to filter users by capability.' ), 206 array( 'status' => rest_authorization_required_code() ) 207 ); 208 } 209 210 if ( 'edit' === $request['context'] && ! current_user_can( 'list_users' ) ) { 211 return new WP_Error( 212 'rest_forbidden_context', 213 __( 'Sorry, you are not allowed to list users.' ), 214 array( 'status' => rest_authorization_required_code() ) 215 ); 216 } 217 218 if ( in_array( $request['orderby'], array( 'email', 'registered_date' ), true ) && ! current_user_can( 'list_users' ) ) { 219 return new WP_Error( 220 'rest_forbidden_orderby', 221 __( 'Sorry, you are not allowed to order users by this parameter.' ), 222 array( 'status' => rest_authorization_required_code() ) 223 ); 224 } 225 226 if ( 'authors' === $request['who'] ) { 227 $types = get_post_types( array( 'show_in_rest' => true ), 'objects' ); 228 229 foreach ( $types as $type ) { 230 if ( post_type_supports( $type->name, 'author' ) 231 && current_user_can( $type->cap->edit_posts ) ) { 232 return true; 233 } 234 } 235 236 return new WP_Error( 237 'rest_forbidden_who', 238 __( 'Sorry, you are not allowed to query users by this parameter.' ), 239 array( 'status' => rest_authorization_required_code() ) 240 ); 241 } 242 243 return true; 244 } 245 246 /** 247 * Retrieves all users. 248 * 249 * @since 4.7.0 250 * 251 * @param WP_REST_Request $request Full details about the request. 252 * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure. 253 */ 254 public function get_items( $request ) { 255 256 // Retrieve the list of registered collection query parameters. 257 $registered = $this->get_collection_params(); 258 259 /* 260 * This array defines mappings between public API query parameters whose 261 * values are accepted as-passed, and their internal WP_Query parameter 262 * name equivalents (some are the same). Only values which are also 263 * present in $registered will be set. 264 */ 265 $parameter_mappings = array( 266 'exclude' => 'exclude', 267 'include' => 'include', 268 'order' => 'order', 269 'per_page' => 'number', 270 'search' => 'search', 271 'roles' => 'role__in', 272 'capabilities' => 'capability__in', 273 'slug' => 'nicename__in', 274 ); 275 276 $prepared_args = array(); 277 278 /* 279 * For each known parameter which is both registered and present in the request, 280 * set the parameter's value on the query $prepared_args. 281 */ 282 foreach ( $parameter_mappings as $api_param => $wp_param ) { 283 if ( isset( $registered[ $api_param ], $request[ $api_param ] ) ) { 284 $prepared_args[ $wp_param ] = $request[ $api_param ]; 285 } 286 } 287 288 if ( isset( $registered['offset'] ) && ! empty( $request['offset'] ) ) { 289 $prepared_args['offset'] = $request['offset']; 290 } else { 291 $prepared_args['offset'] = ( $request['page'] - 1 ) * $prepared_args['number']; 292 } 293 294 if ( isset( $registered['orderby'] ) ) { 295 $orderby_possibles = array( 296 'id' => 'ID', 297 'include' => 'include', 298 'name' => 'display_name', 299 'registered_date' => 'registered', 300 'slug' => 'user_nicename', 301 'include_slugs' => 'nicename__in', 302 'email' => 'user_email', 303 'url' => 'user_url', 304 ); 305 $prepared_args['orderby'] = $orderby_possibles[ $request['orderby'] ]; 306 } 307 308 if ( isset( $registered['who'] ) && ! empty( $request['who'] ) && 'authors' === $request['who'] ) { 309 $prepared_args['who'] = 'authors'; 310 } elseif ( ! current_user_can( 'list_users' ) ) { 311 $prepared_args['has_published_posts'] = get_post_types( array( 'show_in_rest' => true ), 'names' ); 312 } 313 314 if ( ! empty( $request['has_published_posts'] ) ) { 315 $prepared_args['has_published_posts'] = ( true === $request['has_published_posts'] ) 316 ? get_post_types( array( 'show_in_rest' => true ), 'names' ) 317 : (array) $request['has_published_posts']; 318 } 319 320 if ( ! empty( $prepared_args['search'] ) ) { 321 if ( ! current_user_can( 'list_users' ) ) { 322 $prepared_args['search_columns'] = array( 'ID', 'user_login', 'user_nicename', 'display_name' ); 323 } 324 $prepared_args['search'] = '*' . $prepared_args['search'] . '*'; 325 } 326 /** 327 * Filters WP_User_Query arguments when querying users via the REST API. 328 * 329 * @link https://developer.wordpress.org/reference/classes/wp_user_query/ 330 * 331 * @since 4.7.0 332 * 333 * @param array $prepared_args Array of arguments for WP_User_Query. 334 * @param WP_REST_Request $request The REST API request. 335 */ 336 $prepared_args = apply_filters( 'rest_user_query', $prepared_args, $request ); 337 338 $query = new WP_User_Query( $prepared_args ); 339 340 $users = array(); 341 342 foreach ( $query->results as $user ) { 343 $data = $this->prepare_item_for_response( $user, $request ); 344 $users[] = $this->prepare_response_for_collection( $data ); 345 } 346 347 $response = rest_ensure_response( $users ); 348 349 // Store pagination values for headers then unset for count query. 350 $per_page = (int) $prepared_args['number']; 351 $page = (int) ceil( ( ( (int) $prepared_args['offset'] ) / $per_page ) + 1 ); 352 353 $prepared_args['fields'] = 'ID'; 354 355 $total_users = $query->get_total(); 356 357 if ( $total_users < 1 ) { 358 // Out-of-bounds, run the query again without LIMIT for total count. 359 unset( $prepared_args['number'], $prepared_args['offset'] ); 360 $count_query = new WP_User_Query( $prepared_args ); 361 $total_users = $count_query->get_total(); 362 } 363 364 $response->header( 'X-WP-Total', (int) $total_users ); 365 366 $max_pages = (int) ceil( $total_users / $per_page ); 367 368 $response->header( 'X-WP-TotalPages', $max_pages ); 369 370 $base = add_query_arg( urlencode_deep( $request->get_query_params() ), rest_url( sprintf( '%s/%s', $this->namespace, $this->rest_base ) ) ); 371 if ( $page > 1 ) { 372 $prev_page = $page - 1; 373 374 if ( $prev_page > $max_pages ) { 375 $prev_page = $max_pages; 376 } 377 378 $prev_link = add_query_arg( 'page', $prev_page, $base ); 379 $response->link_header( 'prev', $prev_link ); 380 } 381 if ( $max_pages > $page ) { 382 $next_page = $page + 1; 383 $next_link = add_query_arg( 'page', $next_page, $base ); 384 385 $response->link_header( 'next', $next_link ); 386 } 387 388 return $response; 389 } 390 391 /** 392 * Get the user, if the ID is valid. 393 * 394 * @since 4.7.2 395 * 396 * @param int $id Supplied ID. 397 * @return WP_User|WP_Error True if ID is valid, WP_Error otherwise. 398 */ 399 protected function get_user( $id ) { 400 $error = new WP_Error( 401 'rest_user_invalid_id', 402 __( 'Invalid user ID.' ), 403 array( 'status' => 404 ) 404 ); 405 406 if ( (int) $id <= 0 ) { 407 return $error; 408 } 409 410 $user = get_userdata( (int) $id ); 411 if ( empty( $user ) || ! $user->exists() ) { 412 return $error; 413 } 414 415 if ( is_multisite() && ! is_user_member_of_blog( $user->ID ) ) { 416 return $error; 417 } 418 419 return $user; 420 } 421 422 /** 423 * Checks if a given request has access to read a user. 424 * 425 * @since 4.7.0 426 * 427 * @param WP_REST_Request $request Full details about the request. 428 * @return true|WP_Error True if the request has read access for the item, otherwise WP_Error object. 429 */ 430 public function get_item_permissions_check( $request ) { 431 $user = $this->get_user( $request['id'] ); 432 if ( is_wp_error( $user ) ) { 433 return $user; 434 } 435 436 $types = get_post_types( array( 'show_in_rest' => true ), 'names' ); 437 438 if ( get_current_user_id() === $user->ID ) { 439 return true; 440 } 441 442 if ( 'edit' === $request['context'] && ! current_user_can( 'list_users' ) ) { 443 return new WP_Error( 444 'rest_user_cannot_view', 445 __( 'Sorry, you are not allowed to list users.' ), 446 array( 'status' => rest_authorization_required_code() ) 447 ); 448 } elseif ( ! count_user_posts( $user->ID, $types ) && ! current_user_can( 'edit_user', $user->ID ) && ! current_user_can( 'list_users' ) ) { 449 return new WP_Error( 450 'rest_user_cannot_view', 451 __( 'Sorry, you are not allowed to list users.' ), 452 array( 'status' => rest_authorization_required_code() ) 453 ); 454 } 455 456 return true; 457 } 458 459 /** 460 * Retrieves a single user. 461 * 462 * @since 4.7.0 463 * 464 * @param WP_REST_Request $request Full details about the request. 465 * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure. 466 */ 467 public function get_item( $request ) { 468 $user = $this->get_user( $request['id'] ); 469 if ( is_wp_error( $user ) ) { 470 return $user; 471 } 472 473 $user = $this->prepare_item_for_response( $user, $request ); 474 $response = rest_ensure_response( $user ); 475 476 return $response; 477 } 478 479 /** 480 * Retrieves the current user. 481 * 482 * @since 4.7.0 483 * 484 * @param WP_REST_Request $request Full details about the request. 485 * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure. 486 */ 487 public function get_current_item( $request ) { 488 $current_user_id = get_current_user_id(); 489 490 if ( empty( $current_user_id ) ) { 491 return new WP_Error( 492 'rest_not_logged_in', 493 __( 'You are not currently logged in.' ), 494 array( 'status' => 401 ) 495 ); 496 } 497 498 $user = wp_get_current_user(); 499 $response = $this->prepare_item_for_response( $user, $request ); 500 $response = rest_ensure_response( $response ); 501 502 return $response; 503 } 504 505 /** 506 * Checks if a given request has access create users. 507 * 508 * @since 4.7.0 509 * 510 * @param WP_REST_Request $request Full details about the request. 511 * @return true|WP_Error True if the request has access to create items, WP_Error object otherwise. 512 */ 513 public function create_item_permissions_check( $request ) { 514 515 if ( ! current_user_can( 'create_users' ) ) { 516 return new WP_Error( 517 'rest_cannot_create_user', 518 __( 'Sorry, you are not allowed to create new users.' ), 519 array( 'status' => rest_authorization_required_code() ) 520 ); 521 } 522 523 return true; 524 } 525 526 /** 527 * Creates a single user. 528 * 529 * @since 4.7.0 530 * 531 * @param WP_REST_Request $request Full details about the request. 532 * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure. 533 */ 534 public function create_item( $request ) { 535 if ( ! empty( $request['id'] ) ) { 536 return new WP_Error( 537 'rest_user_exists', 538 __( 'Cannot create existing user.' ), 539 array( 'status' => 400 ) 540 ); 541 } 542 543 $schema = $this->get_item_schema(); 544 545 if ( ! empty( $request['roles'] ) && ! empty( $schema['properties']['roles'] ) ) { 546 $check_permission = $this->check_role_update( $request['id'], $request['roles'] ); 547 548 if ( is_wp_error( $check_permission ) ) { 549 return $check_permission; 550 } 551 } 552 553 $user = $this->prepare_item_for_database( $request ); 554 555 if ( is_multisite() ) { 556 $ret = wpmu_validate_user_signup( $user->user_login, $user->user_email ); 557 558 if ( is_wp_error( $ret['errors'] ) && $ret['errors']->has_errors() ) { 559 $error = new WP_Error( 560 'rest_invalid_param', 561 __( 'Invalid user parameter(s).' ), 562 array( 'status' => 400 ) 563 ); 564 565 foreach ( $ret['errors']->errors as $code => $messages ) { 566 foreach ( $messages as $message ) { 567 $error->add( $code, $message ); 568 } 569 570 $error_data = $error->get_error_data( $code ); 571 572 if ( $error_data ) { 573 $error->add_data( $error_data, $code ); 574 } 575 } 576 return $error; 577 } 578 } 579 580 if ( is_multisite() ) { 581 $user_id = wpmu_create_user( $user->user_login, $user->user_pass, $user->user_email ); 582 583 if ( ! $user_id ) { 584 return new WP_Error( 585 'rest_user_create', 586 __( 'Error creating new user.' ), 587 array( 'status' => 500 ) 588 ); 589 } 590 591 $user->ID = $user_id; 592 $user_id = wp_update_user( wp_slash( (array) $user ) ); 593 594 if ( is_wp_error( $user_id ) ) { 595 return $user_id; 596 } 597 598 $result = add_user_to_blog( get_site()->id, $user_id, '' ); 599 if ( is_wp_error( $result ) ) { 600 return $result; 601 } 602 } else { 603 $user_id = wp_insert_user( wp_slash( (array) $user ) ); 604 605 if ( is_wp_error( $user_id ) ) { 606 return $user_id; 607 } 608 } 609 610 $user = get_user_by( 'id', $user_id ); 611 612 /** 613 * Fires immediately after a user is created or updated via the REST API. 614 * 615 * @since 4.7.0 616 * 617 * @param WP_User $user Inserted or updated user object. 618 * @param WP_REST_Request $request Request object. 619 * @param bool $creating True when creating a user, false when updating. 620 */ 621 do_action( 'rest_insert_user', $user, $request, true ); 622 623 if ( ! empty( $request['roles'] ) && ! empty( $schema['properties']['roles'] ) ) { 624 array_map( array( $user, 'add_role' ), $request['roles'] ); 625 } 626 627 if ( ! empty( $schema['properties']['meta'] ) && isset( $request['meta'] ) ) { 628 $meta_update = $this->meta->update_value( $request['meta'], $user_id ); 629 630 if ( is_wp_error( $meta_update ) ) { 631 return $meta_update; 632 } 633 } 634 635 $user = get_user_by( 'id', $user_id ); 636 $fields_update = $this->update_additional_fields_for_object( $user, $request ); 637 638 if ( is_wp_error( $fields_update ) ) { 639 return $fields_update; 640 } 641 642 $request->set_param( 'context', 'edit' ); 643 644 /** 645 * Fires after a user is completely created or updated via the REST API. 646 * 647 * @since 5.0.0 648 * 649 * @param WP_User $user Inserted or updated user object. 650 * @param WP_REST_Request $request Request object. 651 * @param bool $creating True when creating a user, false when updating. 652 */ 653 do_action( 'rest_after_insert_user', $user, $request, true ); 654 655 $response = $this->prepare_item_for_response( $user, $request ); 656 $response = rest_ensure_response( $response ); 657 658 $response->set_status( 201 ); 659 $response->header( 'Location', rest_url( sprintf( '%s/%s/%d', $this->namespace, $this->rest_base, $user_id ) ) ); 660 661 return $response; 662 } 663 664 /** 665 * Checks if a given request has access to update a user. 666 * 667 * @since 4.7.0 668 * 669 * @param WP_REST_Request $request Full details about the request. 670 * @return true|WP_Error True if the request has access to update the item, WP_Error object otherwise. 671 */ 672 public function update_item_permissions_check( $request ) { 673 $user = $this->get_user( $request['id'] ); 674 if ( is_wp_error( $user ) ) { 675 return $user; 676 } 677 678 if ( ! empty( $request['roles'] ) ) { 679 if ( ! current_user_can( 'promote_user', $user->ID ) ) { 680 return new WP_Error( 681 'rest_cannot_edit_roles', 682 __( 'Sorry, you are not allowed to edit roles of this user.' ), 683 array( 'status' => rest_authorization_required_code() ) 684 ); 685 } 686 687 $request_params = array_keys( $request->get_params() ); 688 sort( $request_params ); 689 /* 690 * If only 'id' and 'roles' are specified (we are only trying to 691 * edit roles), then only the 'promote_user' cap is required. 692 */ 693 if ( array( 'id', 'roles' ) === $request_params ) { 694 return true; 695 } 696 } 697 698 if ( ! current_user_can( 'edit_user', $user->ID ) ) { 699 return new WP_Error( 700 'rest_cannot_edit', 701 __( 'Sorry, you are not allowed to edit this user.' ), 702 array( 'status' => rest_authorization_required_code() ) 703 ); 704 } 705 706 return true; 707 } 708 709 /** 710 * Updates a single user. 711 * 712 * @since 4.7.0 713 * 714 * @param WP_REST_Request $request Full details about the request. 715 * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure. 716 */ 717 public function update_item( $request ) { 718 $user = $this->get_user( $request['id'] ); 719 if ( is_wp_error( $user ) ) { 720 return $user; 721 } 722 723 $id = $user->ID; 724 725 $owner_id = false; 726 if ( is_string( $request['email'] ) ) { 727 $owner_id = email_exists( $request['email'] ); 728 } 729 730 if ( $owner_id && $owner_id !== $id ) { 731 return new WP_Error( 732 'rest_user_invalid_email', 733 __( 'Invalid email address.' ), 734 array( 'status' => 400 ) 735 ); 736 } 737 738 if ( ! empty( $request['username'] ) && $request['username'] !== $user->user_login ) { 739 return new WP_Error( 740 'rest_user_invalid_argument', 741 __( 'Username is not editable.' ), 742 array( 'status' => 400 ) 743 ); 744 } 745 746 if ( ! empty( $request['slug'] ) && $request['slug'] !== $user->user_nicename && get_user_by( 'slug', $request['slug'] ) ) { 747 return new WP_Error( 748 'rest_user_invalid_slug', 749 __( 'Invalid slug.' ), 750 array( 'status' => 400 ) 751 ); 752 } 753 754 if ( ! empty( $request['roles'] ) ) { 755 $check_permission = $this->check_role_update( $id, $request['roles'] ); 756 757 if ( is_wp_error( $check_permission ) ) { 758 return $check_permission; 759 } 760 } 761 762 $user = $this->prepare_item_for_database( $request ); 763 764 // Ensure we're operating on the same user we already checked. 765 $user->ID = $id; 766 767 $user_id = wp_update_user( wp_slash( (array) $user ) ); 768 769 if ( is_wp_error( $user_id ) ) { 770 return $user_id; 771 } 772 773 $user = get_user_by( 'id', $user_id ); 774 775 /** This action is documented in wp-includes/rest-api/endpoints/class-wp-rest-users-controller.php */ 776 do_action( 'rest_insert_user', $user, $request, false ); 777 778 if ( ! empty( $request['roles'] ) ) { 779 array_map( array( $user, 'add_role' ), $request['roles'] ); 780 } 781 782 $schema = $this->get_item_schema(); 783 784 if ( ! empty( $schema['properties']['meta'] ) && isset( $request['meta'] ) ) { 785 $meta_update = $this->meta->update_value( $request['meta'], $id ); 786 787 if ( is_wp_error( $meta_update ) ) { 788 return $meta_update; 789 } 790 } 791 792 $user = get_user_by( 'id', $user_id ); 793 $fields_update = $this->update_additional_fields_for_object( $user, $request ); 794 795 if ( is_wp_error( $fields_update ) ) { 796 return $fields_update; 797 } 798 799 $request->set_param( 'context', 'edit' ); 800 801 /** This action is documented in wp-includes/rest-api/endpoints/class-wp-rest-users-controller.php */ 802 do_action( 'rest_after_insert_user', $user, $request, false ); 803 804 $response = $this->prepare_item_for_response( $user, $request ); 805 $response = rest_ensure_response( $response ); 806 807 return $response; 808 } 809 810 /** 811 * Checks if a given request has access to update the current user. 812 * 813 * @since 4.7.0 814 * 815 * @param WP_REST_Request $request Full details about the request. 816 * @return true|WP_Error True if the request has access to update the item, WP_Error object otherwise. 817 */ 818 public function update_current_item_permissions_check( $request ) { 819 $request['id'] = get_current_user_id(); 820 821 return $this->update_item_permissions_check( $request ); 822 } 823 824 /** 825 * Updates the current user. 826 * 827 * @since 4.7.0 828 * 829 * @param WP_REST_Request $request Full details about the request. 830 * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure. 831 */ 832 public function update_current_item( $request ) { 833 $request['id'] = get_current_user_id(); 834 835 return $this->update_item( $request ); 836 } 837 838 /** 839 * Checks if a given request has access delete a user. 840 * 841 * @since 4.7.0 842 * 843 * @param WP_REST_Request $request Full details about the request. 844 * @return true|WP_Error True if the request has access to delete the item, WP_Error object otherwise. 845 */ 846 public function delete_item_permissions_check( $request ) { 847 $user = $this->get_user( $request['id'] ); 848 if ( is_wp_error( $user ) ) { 849 return $user; 850 } 851 852 if ( ! current_user_can( 'delete_user', $user->ID ) ) { 853 return new WP_Error( 854 'rest_user_cannot_delete', 855 __( 'Sorry, you are not allowed to delete this user.' ), 856 array( 'status' => rest_authorization_required_code() ) 857 ); 858 } 859 860 return true; 861 } 862 863 /** 864 * Deletes a single user. 865 * 866 * @since 4.7.0 867 * 868 * @param WP_REST_Request $request Full details about the request. 869 * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure. 870 */ 871 public function delete_item( $request ) { 872 // We don't support delete requests in multisite. 873 if ( is_multisite() ) { 874 return new WP_Error( 875 'rest_cannot_delete', 876 __( 'The user cannot be deleted.' ), 877 array( 'status' => 501 ) 878 ); 879 } 880 881 $user = $this->get_user( $request['id'] ); 882 883 if ( is_wp_error( $user ) ) { 884 return $user; 885 } 886 887 $id = $user->ID; 888 $reassign = false === $request['reassign'] ? null : absint( $request['reassign'] ); 889 $force = isset( $request['force'] ) ? (bool) $request['force'] : false; 890 891 // We don't support trashing for users. 892 if ( ! $force ) { 893 return new WP_Error( 894 'rest_trash_not_supported', 895 /* translators: %s: force=true */ 896 sprintf( __( "Users do not support trashing. Set '%s' to delete." ), 'force=true' ), 897 array( 'status' => 501 ) 898 ); 899 } 900 901 if ( ! empty( $reassign ) ) { 902 if ( $reassign === $id || ! get_userdata( $reassign ) ) { 903 return new WP_Error( 904 'rest_user_invalid_reassign', 905 __( 'Invalid user ID for reassignment.' ), 906 array( 'status' => 400 ) 907 ); 908 } 909 } 910 911 $request->set_param( 'context', 'edit' ); 912 913 $previous = $this->prepare_item_for_response( $user, $request ); 914 915 // Include user admin functions to get access to wp_delete_user(). 916 require_once ABSPATH . 'wp-admin/includes/user.php'; 917 918 $result = wp_delete_user( $id, $reassign ); 919 920 if ( ! $result ) { 921 return new WP_Error( 922 'rest_cannot_delete', 923 __( 'The user cannot be deleted.' ), 924 array( 'status' => 500 ) 925 ); 926 } 927 928 $response = new WP_REST_Response(); 929 $response->set_data( 930 array( 931 'deleted' => true, 932 'previous' => $previous->get_data(), 933 ) 934 ); 935 936 /** 937 * Fires immediately after a user is deleted via the REST API. 938 * 939 * @since 4.7.0 940 * 941 * @param WP_User $user The user data. 942 * @param WP_REST_Response $response The response returned from the API. 943 * @param WP_REST_Request $request The request sent to the API. 944 */ 945 do_action( 'rest_delete_user', $user, $response, $request ); 946 947 return $response; 948 } 949 950 /** 951 * Checks if a given request has access to delete the current user. 952 * 953 * @since 4.7.0 954 * 955 * @param WP_REST_Request $request Full details about the request. 956 * @return true|WP_Error True if the request has access to delete the item, WP_Error object otherwise. 957 */ 958 public function delete_current_item_permissions_check( $request ) { 959 $request['id'] = get_current_user_id(); 960 961 return $this->delete_item_permissions_check( $request ); 962 } 963 964 /** 965 * Deletes the current user. 966 * 967 * @since 4.7.0 968 * 969 * @param WP_REST_Request $request Full details about the request. 970 * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure. 971 */ 972 public function delete_current_item( $request ) { 973 $request['id'] = get_current_user_id(); 974 975 return $this->delete_item( $request ); 976 } 977 978 /** 979 * Prepares a single user output for response. 980 * 981 * @since 4.7.0 982 * @since 5.9.0 Renamed `$user` to `$item` to match parent class for PHP 8 named parameter support. 983 * 984 * @param WP_User $item User object. 985 * @param WP_REST_Request $request Request object. 986 * @return WP_REST_Response Response object. 987 */ 988 public function prepare_item_for_response( $item, $request ) { 989 // Restores the more descriptive, specific name for use within this method. 990 $user = $item; 991 992 $fields = $this->get_fields_for_response( $request ); 993 $data = array(); 994 995 if ( in_array( 'id', $fields, true ) ) { 996 $data['id'] = $user->ID; 997 } 998 999 if ( in_array( 'username', $fields, true ) ) { 1000 $data['username'] = $user->user_login; 1001 } 1002 1003 if ( in_array( 'name', $fields, true ) ) { 1004 $data['name'] = $user->display_name; 1005 } 1006 1007 if ( in_array( 'first_name', $fields, true ) ) { 1008 $data['first_name'] = $user->first_name; 1009 } 1010 1011 if ( in_array( 'last_name', $fields, true ) ) { 1012 $data['last_name'] = $user->last_name; 1013 } 1014 1015 if ( in_array( 'email', $fields, true ) ) { 1016 $data['email'] = $user->user_email; 1017 } 1018 1019 if ( in_array( 'url', $fields, true ) ) { 1020 $data['url'] = $user->user_url; 1021 } 1022 1023 if ( in_array( 'description', $fields, true ) ) { 1024 $data['description'] = $user->description; 1025 } 1026 1027 if ( in_array( 'link', $fields, true ) ) { 1028 $data['link'] = get_author_posts_url( $user->ID, $user->user_nicename ); 1029 } 1030 1031 if ( in_array( 'locale', $fields, true ) ) { 1032 $data['locale'] = get_user_locale( $user ); 1033 } 1034 1035 if ( in_array( 'nickname', $fields, true ) ) { 1036 $data['nickname'] = $user->nickname; 1037 } 1038 1039 if ( in_array( 'slug', $fields, true ) ) { 1040 $data['slug'] = $user->user_nicename; 1041 } 1042 1043 if ( in_array( 'roles', $fields, true ) ) { 1044 // Defensively call array_values() to ensure an array is returned. 1045 $data['roles'] = array_values( $user->roles ); 1046 } 1047 1048 if ( in_array( 'registered_date', $fields, true ) ) { 1049 $data['registered_date'] = gmdate( 'c', strtotime( $user->user_registered ) ); 1050 } 1051 1052 if ( in_array( 'capabilities', $fields, true ) ) { 1053 $data['capabilities'] = (object) $user->allcaps; 1054 } 1055 1056 if ( in_array( 'extra_capabilities', $fields, true ) ) { 1057 $data['extra_capabilities'] = (object) $user->caps; 1058 } 1059 1060 if ( in_array( 'avatar_urls', $fields, true ) ) { 1061 $data['avatar_urls'] = rest_get_avatar_urls( $user ); 1062 } 1063 1064 if ( in_array( 'meta', $fields, true ) ) { 1065 $data['meta'] = $this->meta->get_value( $user->ID, $request ); 1066 } 1067 1068 $context = ! empty( $request['context'] ) ? $request['context'] : 'embed'; 1069 1070 $data = $this->add_additional_fields_to_object( $data, $request ); 1071 $data = $this->filter_response_by_context( $data, $context ); 1072 1073 // Wrap the data in a response object. 1074 $response = rest_ensure_response( $data ); 1075 1076 if ( rest_is_field_included( '_links', $fields ) || rest_is_field_included( '_embedded', $fields ) ) { 1077 $response->add_links( $this->prepare_links( $user ) ); 1078 } 1079 1080 /** 1081 * Filters user data returned from the REST API. 1082 * 1083 * @since 4.7.0 1084 * 1085 * @param WP_REST_Response $response The response object. 1086 * @param WP_User $user User object used to create response. 1087 * @param WP_REST_Request $request Request object. 1088 */ 1089 return apply_filters( 'rest_prepare_user', $response, $user, $request ); 1090 } 1091 1092 /** 1093 * Prepares links for the user request. 1094 * 1095 * @since 4.7.0 1096 * 1097 * @param WP_User $user User object. 1098 * @return array Links for the given user. 1099 */ 1100 protected function prepare_links( $user ) { 1101 $links = array( 1102 'self' => array( 1103 'href' => rest_url( sprintf( '%s/%s/%d', $this->namespace, $this->rest_base, $user->ID ) ), 1104 ), 1105 'collection' => array( 1106 'href' => rest_url( sprintf( '%s/%s', $this->namespace, $this->rest_base ) ), 1107 ), 1108 ); 1109 1110 return $links; 1111 } 1112 1113 /** 1114 * Prepares a single user for creation or update. 1115 * 1116 * @since 4.7.0 1117 * 1118 * @param WP_REST_Request $request Request object. 1119 * @return object User object. 1120 */ 1121 protected function prepare_item_for_database( $request ) { 1122 $prepared_user = new stdClass(); 1123 1124 $schema = $this->get_item_schema(); 1125 1126 // Required arguments. 1127 if ( isset( $request['email'] ) && ! empty( $schema['properties']['email'] ) ) { 1128 $prepared_user->user_email = $request['email']; 1129 } 1130 1131 if ( isset( $request['username'] ) && ! empty( $schema['properties']['username'] ) ) { 1132 $prepared_user->user_login = $request['username']; 1133 } 1134 1135 if ( isset( $request['password'] ) && ! empty( $schema['properties']['password'] ) ) { 1136 $prepared_user->user_pass = $request['password']; 1137 } 1138 1139 // Optional arguments. 1140 if ( isset( $request['id'] ) ) { 1141 $prepared_user->ID = absint( $request['id'] ); 1142 } 1143 1144 if ( isset( $request['name'] ) && ! empty( $schema['properties']['name'] ) ) { 1145 $prepared_user->display_name = $request['name']; 1146 } 1147 1148 if ( isset( $request['first_name'] ) && ! empty( $schema['properties']['first_name'] ) ) { 1149 $prepared_user->first_name = $request['first_name']; 1150 } 1151 1152 if ( isset( $request['last_name'] ) && ! empty( $schema['properties']['last_name'] ) ) { 1153 $prepared_user->last_name = $request['last_name']; 1154 } 1155 1156 if ( isset( $request['nickname'] ) && ! empty( $schema['properties']['nickname'] ) ) { 1157 $prepared_user->nickname = $request['nickname']; 1158 } 1159 1160 if ( isset( $request['slug'] ) && ! empty( $schema['properties']['slug'] ) ) { 1161 $prepared_user->user_nicename = $request['slug']; 1162 } 1163 1164 if ( isset( $request['description'] ) && ! empty( $schema['properties']['description'] ) ) { 1165 $prepared_user->description = $request['description']; 1166 } 1167 1168 if ( isset( $request['url'] ) && ! empty( $schema['properties']['url'] ) ) { 1169 $prepared_user->user_url = $request['url']; 1170 } 1171 1172 if ( isset( $request['locale'] ) && ! empty( $schema['properties']['locale'] ) ) { 1173 $prepared_user->locale = $request['locale']; 1174 } 1175 1176 // Setting roles will be handled outside of this function. 1177 if ( isset( $request['roles'] ) ) { 1178 $prepared_user->role = false; 1179 } 1180 1181 /** 1182 * Filters user data before insertion via the REST API. 1183 * 1184 * @since 4.7.0 1185 * 1186 * @param object $prepared_user User object. 1187 * @param WP_REST_Request $request Request object. 1188 */ 1189 return apply_filters( 'rest_pre_insert_user', $prepared_user, $request ); 1190 } 1191 1192 /** 1193 * Determines if the current user is allowed to make the desired roles change. 1194 * 1195 * @since 4.7.0 1196 * 1197 * @global WP_Roles $wp_roles WordPress role management object. 1198 * 1199 * @param int $user_id User ID. 1200 * @param array $roles New user roles. 1201 * @return true|WP_Error True if the current user is allowed to make the role change, 1202 * otherwise a WP_Error object. 1203 */ 1204 protected function check_role_update( $user_id, $roles ) { 1205 global $wp_roles; 1206 1207 foreach ( $roles as $role ) { 1208 1209 if ( ! isset( $wp_roles->role_objects[ $role ] ) ) { 1210 return new WP_Error( 1211 'rest_user_invalid_role', 1212 /* translators: %s: Role key. */ 1213 sprintf( __( 'The role %s does not exist.' ), $role ), 1214 array( 'status' => 400 ) 1215 ); 1216 } 1217 1218 $potential_role = $wp_roles->role_objects[ $role ]; 1219 1220 /* 1221 * Don't let anyone with 'edit_users' (admins) edit their own role to something without it. 1222 * Multisite super admins can freely edit their blog roles -- they possess all caps. 1223 */ 1224 if ( ! ( is_multisite() 1225 && current_user_can( 'manage_sites' ) ) 1226 && get_current_user_id() === $user_id 1227 && ! $potential_role->has_cap( 'edit_users' ) 1228 ) { 1229 return new WP_Error( 1230 'rest_user_invalid_role', 1231 __( 'Sorry, you are not allowed to give users that role.' ), 1232 array( 'status' => rest_authorization_required_code() ) 1233 ); 1234 } 1235 1236 // Include user admin functions to get access to get_editable_roles(). 1237 require_once ABSPATH . 'wp-admin/includes/user.php'; 1238 1239 // The new role must be editable by the logged-in user. 1240 $editable_roles = get_editable_roles(); 1241 1242 if ( empty( $editable_roles[ $role ] ) ) { 1243 return new WP_Error( 1244 'rest_user_invalid_role', 1245 __( 'Sorry, you are not allowed to give users that role.' ), 1246 array( 'status' => 403 ) 1247 ); 1248 } 1249 } 1250 1251 return true; 1252 } 1253 1254 /** 1255 * Check a username for the REST API. 1256 * 1257 * Performs a couple of checks like edit_user() in wp-admin/includes/user.php. 1258 * 1259 * @since 4.7.0 1260 * 1261 * @param string $value The username submitted in the request. 1262 * @param WP_REST_Request $request Full details about the request. 1263 * @param string $param The parameter name. 1264 * @return string|WP_Error The sanitized username, if valid, otherwise an error. 1265 */ 1266 public function check_username( $value, $request, $param ) { 1267 $username = (string) $value; 1268 1269 if ( ! validate_username( $username ) ) { 1270 return new WP_Error( 1271 'rest_user_invalid_username', 1272 __( 'This username is invalid because it uses illegal characters. Please enter a valid username.' ), 1273 array( 'status' => 400 ) 1274 ); 1275 } 1276 1277 /** This filter is documented in wp-includes/user.php */ 1278 $illegal_logins = (array) apply_filters( 'illegal_user_logins', array() ); 1279 1280 if ( in_array( strtolower( $username ), array_map( 'strtolower', $illegal_logins ), true ) ) { 1281 return new WP_Error( 1282 'rest_user_invalid_username', 1283 __( 'Sorry, that username is not allowed.' ), 1284 array( 'status' => 400 ) 1285 ); 1286 } 1287 1288 return $username; 1289 } 1290 1291 /** 1292 * Check a user password for the REST API. 1293 * 1294 * Performs a couple of checks like edit_user() in wp-admin/includes/user.php. 1295 * 1296 * @since 4.7.0 1297 * 1298 * @param string $value The password submitted in the request. 1299 * @param WP_REST_Request $request Full details about the request. 1300 * @param string $param The parameter name. 1301 * @return string|WP_Error The sanitized password, if valid, otherwise an error. 1302 */ 1303 public function check_user_password( $value, $request, $param ) { 1304 $password = (string) $value; 1305 1306 if ( empty( $password ) ) { 1307 return new WP_Error( 1308 'rest_user_invalid_password', 1309 __( 'Passwords cannot be empty.' ), 1310 array( 'status' => 400 ) 1311 ); 1312 } 1313 1314 if ( str_contains( $password, '\\' ) ) { 1315 return new WP_Error( 1316 'rest_user_invalid_password', 1317 sprintf( 1318 /* translators: %s: The '\' character. */ 1319 __( 'Passwords cannot contain the "%s" character.' ), 1320 '\\' 1321 ), 1322 array( 'status' => 400 ) 1323 ); 1324 } 1325 1326 return $password; 1327 } 1328 1329 /** 1330 * Retrieves the user's schema, conforming to JSON Schema. 1331 * 1332 * @since 4.7.0 1333 * 1334 * @return array Item schema data. 1335 */ 1336 public function get_item_schema() { 1337 if ( $this->schema ) { 1338 return $this->add_additional_fields_schema( $this->schema ); 1339 } 1340 1341 $schema = array( 1342 '$schema' => 'http://json-schema.org/draft-04/schema#', 1343 'title' => 'user', 1344 'type' => 'object', 1345 'properties' => array( 1346 'id' => array( 1347 'description' => __( 'Unique identifier for the user.' ), 1348 'type' => 'integer', 1349 'context' => array( 'embed', 'view', 'edit' ), 1350 'readonly' => true, 1351 ), 1352 'username' => array( 1353 'description' => __( 'Login name for the user.' ), 1354 'type' => 'string', 1355 'context' => array( 'edit' ), 1356 'required' => true, 1357 'arg_options' => array( 1358 'sanitize_callback' => array( $this, 'check_username' ), 1359 ), 1360 ), 1361 'name' => array( 1362 'description' => __( 'Display name for the user.' ), 1363 'type' => 'string', 1364 'context' => array( 'embed', 'view', 'edit' ), 1365 'arg_options' => array( 1366 'sanitize_callback' => 'sanitize_text_field', 1367 ), 1368 ), 1369 'first_name' => array( 1370 'description' => __( 'First name for the user.' ), 1371 'type' => 'string', 1372 'context' => array( 'edit' ), 1373 'arg_options' => array( 1374 'sanitize_callback' => 'sanitize_text_field', 1375 ), 1376 ), 1377 'last_name' => array( 1378 'description' => __( 'Last name for the user.' ), 1379 'type' => 'string', 1380 'context' => array( 'edit' ), 1381 'arg_options' => array( 1382 'sanitize_callback' => 'sanitize_text_field', 1383 ), 1384 ), 1385 'email' => array( 1386 'description' => __( 'The email address for the user.' ), 1387 'type' => 'string', 1388 'format' => 'email', 1389 'context' => array( 'edit' ), 1390 'required' => true, 1391 ), 1392 'url' => array( 1393 'description' => __( 'URL of the user.' ), 1394 'type' => 'string', 1395 'format' => 'uri', 1396 'context' => array( 'embed', 'view', 'edit' ), 1397 ), 1398 'description' => array( 1399 'description' => __( 'Description of the user.' ), 1400 'type' => 'string', 1401 'context' => array( 'embed', 'view', 'edit' ), 1402 ), 1403 'link' => array( 1404 'description' => __( 'Author URL of the user.' ), 1405 'type' => 'string', 1406 'format' => 'uri', 1407 'context' => array( 'embed', 'view', 'edit' ), 1408 'readonly' => true, 1409 ), 1410 'locale' => array( 1411 'description' => __( 'Locale for the user.' ), 1412 'type' => 'string', 1413 'enum' => array_merge( array( '', 'en_US' ), get_available_languages() ), 1414 'context' => array( 'edit' ), 1415 ), 1416 'nickname' => array( 1417 'description' => __( 'The nickname for the user.' ), 1418 'type' => 'string', 1419 'context' => array( 'edit' ), 1420 'arg_options' => array( 1421 'sanitize_callback' => 'sanitize_text_field', 1422 ), 1423 ), 1424 'slug' => array( 1425 'description' => __( 'An alphanumeric identifier for the user.' ), 1426 'type' => 'string', 1427 'context' => array( 'embed', 'view', 'edit' ), 1428 'arg_options' => array( 1429 'sanitize_callback' => array( $this, 'sanitize_slug' ), 1430 ), 1431 ), 1432 'registered_date' => array( 1433 'description' => __( 'Registration date for the user.' ), 1434 'type' => 'string', 1435 'format' => 'date-time', 1436 'context' => array( 'edit' ), 1437 'readonly' => true, 1438 ), 1439 'roles' => array( 1440 'description' => __( 'Roles assigned to the user.' ), 1441 'type' => 'array', 1442 'items' => array( 1443 'type' => 'string', 1444 ), 1445 'context' => array( 'edit' ), 1446 ), 1447 'password' => array( 1448 'description' => __( 'Password for the user (never included).' ), 1449 'type' => 'string', 1450 'context' => array(), // Password is never displayed. 1451 'required' => true, 1452 'arg_options' => array( 1453 'sanitize_callback' => array( $this, 'check_user_password' ), 1454 ), 1455 ), 1456 'capabilities' => array( 1457 'description' => __( 'All capabilities assigned to the user.' ), 1458 'type' => 'object', 1459 'context' => array( 'edit' ), 1460 'readonly' => true, 1461 ), 1462 'extra_capabilities' => array( 1463 'description' => __( 'Any extra capabilities assigned to the user.' ), 1464 'type' => 'object', 1465 'context' => array( 'edit' ), 1466 'readonly' => true, 1467 ), 1468 ), 1469 ); 1470 1471 if ( get_option( 'show_avatars' ) ) { 1472 $avatar_properties = array(); 1473 1474 $avatar_sizes = rest_get_avatar_sizes(); 1475 1476 foreach ( $avatar_sizes as $size ) { 1477 $avatar_properties[ $size ] = array( 1478 /* translators: %d: Avatar image size in pixels. */ 1479 'description' => sprintf( __( 'Avatar URL with image size of %d pixels.' ), $size ), 1480 'type' => 'string', 1481 'format' => 'uri', 1482 'context' => array( 'embed', 'view', 'edit' ), 1483 ); 1484 } 1485 1486 $schema['properties']['avatar_urls'] = array( 1487 'description' => __( 'Avatar URLs for the user.' ), 1488 'type' => 'object', 1489 'context' => array( 'embed', 'view', 'edit' ), 1490 'readonly' => true, 1491 'properties' => $avatar_properties, 1492 ); 1493 } 1494 1495 $schema['properties']['meta'] = $this->meta->get_field_schema(); 1496 1497 $this->schema = $schema; 1498 1499 return $this->add_additional_fields_schema( $this->schema ); 1500 } 1501 1502 /** 1503 * Retrieves the query params for collections. 1504 * 1505 * @since 4.7.0 1506 * 1507 * @return array Collection parameters. 1508 */ 1509 public function get_collection_params() { 1510 $query_params = parent::get_collection_params(); 1511 1512 $query_params['context']['default'] = 'view'; 1513 1514 $query_params['exclude'] = array( 1515 'description' => __( 'Ensure result set excludes specific IDs.' ), 1516 'type' => 'array', 1517 'items' => array( 1518 'type' => 'integer', 1519 ), 1520 'default' => array(), 1521 ); 1522 1523 $query_params['include'] = array( 1524 'description' => __( 'Limit result set to specific IDs.' ), 1525 'type' => 'array', 1526 'items' => array( 1527 'type' => 'integer', 1528 ), 1529 'default' => array(), 1530 ); 1531 1532 $query_params['offset'] = array( 1533 'description' => __( 'Offset the result set by a specific number of items.' ), 1534 'type' => 'integer', 1535 ); 1536 1537 $query_params['order'] = array( 1538 'default' => 'asc', 1539 'description' => __( 'Order sort attribute ascending or descending.' ), 1540 'enum' => array( 'asc', 'desc' ), 1541 'type' => 'string', 1542 ); 1543 1544 $query_params['orderby'] = array( 1545 'default' => 'name', 1546 'description' => __( 'Sort collection by user attribute.' ), 1547 'enum' => array( 1548 'id', 1549 'include', 1550 'name', 1551 'registered_date', 1552 'slug', 1553 'include_slugs', 1554 'email', 1555 'url', 1556 ), 1557 'type' => 'string', 1558 ); 1559 1560 $query_params['slug'] = array( 1561 'description' => __( 'Limit result set to users with one or more specific slugs.' ), 1562 'type' => 'array', 1563 'items' => array( 1564 'type' => 'string', 1565 ), 1566 ); 1567 1568 $query_params['roles'] = array( 1569 'description' => __( 'Limit result set to users matching at least one specific role provided. Accepts csv list or single role.' ), 1570 'type' => 'array', 1571 'items' => array( 1572 'type' => 'string', 1573 ), 1574 ); 1575 1576 $query_params['capabilities'] = array( 1577 'description' => __( 'Limit result set to users matching at least one specific capability provided. Accepts csv list or single capability.' ), 1578 'type' => 'array', 1579 'items' => array( 1580 'type' => 'string', 1581 ), 1582 ); 1583 1584 $query_params['who'] = array( 1585 'description' => __( 'Limit result set to users who are considered authors.' ), 1586 'type' => 'string', 1587 'enum' => array( 1588 'authors', 1589 ), 1590 ); 1591 1592 $query_params['has_published_posts'] = array( 1593 'description' => __( 'Limit result set to users who have published posts.' ), 1594 'type' => array( 'boolean', 'array' ), 1595 'items' => array( 1596 'type' => 'string', 1597 'enum' => get_post_types( array( 'show_in_rest' => true ), 'names' ), 1598 ), 1599 ); 1600 1601 /** 1602 * Filters REST API collection parameters for the users controller. 1603 * 1604 * This filter registers the collection parameter, but does not map the 1605 * collection parameter to an internal WP_User_Query parameter. Use the 1606 * `rest_user_query` filter to set WP_User_Query arguments. 1607 * 1608 * @since 4.7.0 1609 * 1610 * @param array $query_params JSON Schema-formatted collection parameters. 1611 */ 1612 return apply_filters( 'rest_user_collection_params', $query_params ); 1613 } 1614 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated : Thu Apr 25 08:20:02 2024 | Cross-referenced by PHPXref |