class-wp-rest-users-controller.php 46 KB

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