<?php

/**

 * REST API: WP_REST_Users_Controller class

 *

 * @package WordPress

 * @subpackage REST_API

 * @since 4.7.0

 */

/**

 * Core class used to manage users via the REST API.

 *

 * @since 4.7.0

 *

 * @see WP_REST_Controller

 */

class WP_REST_Users_Controller extends WP_REST_Controller {

	/**

	 * Instance of a user meta fields object.

	 *

	 * @since 4.7.0

	 * @var WP_REST_User_Meta_Fields

	 */

	protected $meta;

	/**

	 * Constructor.

	 *

	 * @since 4.7.0

	 */

	public function __construct() {

		$this->namespace = 'wp/v2';

		$this->rest_base = 'users';

		$this->meta = new WP_REST_User_Meta_Fields();

	}

	/**

	 * Registers the routes for users.

	 *

	 * @since 4.7.0

	 *

	 * @see register_rest_route()

	 */

	public function register_routes() {

		register_rest_route(

			$this->namespace,

			'/' . $this->rest_base,

			array(

				array(

					'methods'             => WP_REST_Server::READABLE,

					'callback'            => array( $this, 'get_items' ),

					'permission_callback' => array( $this, 'get_items_permissions_check' ),

					'args'                => $this->get_collection_params(),

				),

				array(

					'methods'             => WP_REST_Server::CREATABLE,

					'callback'            => array( $this, 'create_item' ),

					'permission_callback' => array( $this, 'create_item_permissions_check' ),

					'args'                => $this->get_endpoint_args_for_item_schema( WP_REST_Server::CREATABLE ),

				),

				'schema' => array( $this, 'get_public_item_schema' ),

			)

		);

		register_rest_route(

			$this->namespace,

			'/' . $this->rest_base . '/(?P<id>[\d]+)',

			array(

				'args'   => array(

					'id' => array(

						'description' => __( 'Unique identifier for the user.' ),

						'type'        => 'integer',

					),

				),

				array(

					'methods'             => WP_REST_Server::READABLE,

					'callback'            => array( $this, 'get_item' ),

					'permission_callback' => array( $this, 'get_item_permissions_check' ),

					'args'                => array(

						'context' => $this->get_context_param( array( 'default' => 'view' ) ),

					),

				),

				array(

					'methods'             => WP_REST_Server::EDITABLE,

					'callback'            => array( $this, 'update_item' ),

					'permission_callback' => array( $this, 'update_item_permissions_check' ),

					'args'                => $this->get_endpoint_args_for_item_schema( WP_REST_Server::EDITABLE ),

				),

				array(

					'methods'             => WP_REST_Server::DELETABLE,

					'callback'            => array( $this, 'delete_item' ),

					'permission_callback' => array( $this, 'delete_item_permissions_check' ),

					'args'                => array(

						'force'    => array(

							'type'        => 'boolean',

							'default'     => false,

							'description' => __( 'Required to be true, as users do not support trashing.' ),

						),

						'reassign' => array(

							'type'              => 'integer',

							'description'       => __( 'Reassign the deleted user\'s posts and links to this user ID.' ),

							'required'          => true,

							'sanitize_callback' => array( $this, 'check_reassign' ),

						),

					),

				),

				'schema' => array( $this, 'get_public_item_schema' ),

			)

		);

		register_rest_route(

			$this->namespace,

			'/' . $this->rest_base . '/me',

			array(

				array(

					'methods'             => WP_REST_Server::READABLE,

					'permission_callback' => '__return_true',

					'callback'            => array( $this, 'get_current_item' ),

					'args'                => array(

						'context' => $this->get_context_param( array( 'default' => 'view' ) ),

					),

				),

				array(

					'methods'             => WP_REST_Server::EDITABLE,

					'callback'            => array( $this, 'update_current_item' ),

					'permission_callback' => array( $this, 'update_current_item_permissions_check' ),

					'args'                => $this->get_endpoint_args_for_item_schema( WP_REST_Server::EDITABLE ),

				),

				array(

					'methods'             => WP_REST_Server::DELETABLE,

					'callback'            => array( $this, 'delete_current_item' ),

					'permission_callback' => array( $this, 'delete_current_item_permissions_check' ),

					'args'                => array(

						'force'    => array(

							'type'        => 'boolean',

							'default'     => false,

							'description' => __( 'Required to be true, as users do not support trashing.' ),

						),

						'reassign' => array(

							'type'              => 'integer',

							'description'       => __( 'Reassign the deleted user\'s posts and links to this user ID.' ),

							'required'          => true,

							'sanitize_callback' => array( $this, 'check_reassign' ),

						),

					),

				),

				'schema' => array( $this, 'get_public_item_schema' ),

			)

		);

	}

	/**

	 * Checks for a valid value for the reassign parameter when deleting users.

	 *

	 * The value can be an integer, 'false', false, or ''.

	 *

	 * @since 4.7.0

	 *

	 * @param int|bool        $value   The value passed to the reassign parameter.

	 * @param WP_REST_Request $request Full details about the request.

	 * @param string          $param   The parameter that is being sanitized.

	 * @return int|bool|WP_Error

	 */

	public function check_reassign( $value, $request, $param ) {

		if ( is_numeric( $value ) ) {

			return $value;

		}

		if ( empty( $value ) || false === $value || 'false' === $value ) {

			return false;

		}

		return new WP_Error(

			'rest_invalid_param',

			__( 'Invalid user parameter(s).' ),

			array( 'status' => 400 )

		);

	}

	/**

	 * Permissions check for getting all users.

	 *

	 * @since 4.7.0

	 *

	 * @param WP_REST_Request $request Full details about the request.

	 * @return true|WP_Error True if the request has read access, otherwise WP_Error object.

	 */

	public function get_items_permissions_check( $request ) {

		// Check if roles is specified in GET request and if user can list users.

		if ( ! empty( $request['roles'] ) && ! current_user_can( 'list_users' ) ) {

			return new WP_Error(

				'rest_user_cannot_view',

				__( 'Sorry, you are not allowed to filter users by role.' ),

				array( 'status' => rest_authorization_required_code() )

			);

		}

		if ( 'edit' === $request['context'] && ! current_user_can( 'list_users' ) ) {

			return new WP_Error(

				'rest_forbidden_context',

				__( 'Sorry, you are not allowed to list users.' ),

				array( 'status' => rest_authorization_required_code() )

			);

		}

		if ( in_array( $request['orderby'], array( 'email', 'registered_date' ), true ) && ! current_user_can( 'list_users' ) ) {

			return new WP_Error(

				'rest_forbidden_orderby',

				__( 'Sorry, you are not allowed to order users by this parameter.' ),

				array( 'status' => rest_authorization_required_code() )

			);

		}

		if ( 'authors' === $request['who'] ) {

			$types = get_post_types( array( 'show_in_rest' => true ), 'objects' );

			foreach ( $types as $type ) {

				if ( post_type_supports( $type->name, 'author' )

					&& current_user_can( $type->cap->edit_posts ) ) {

					return true;

				}

			}

			return new WP_Error(

				'rest_forbidden_who',

				__( 'Sorry, you are not allowed to query users by this parameter.' ),

				array( 'status' => rest_authorization_required_code() )

			);

		}

		return true;

	}

	/**

	 * Retrieves all users.

	 *

	 * @since 4.7.0

	 *

	 * @param WP_REST_Request $request Full details about the request.

	 * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.

	 */

	public function get_items( $request ) {

		// Retrieve the list of registered collection query parameters.

		$registered = $this->get_collection_params();

		/*

		 * This array defines mappings between public API query parameters whose

		 * values are accepted as-passed, and their internal WP_Query parameter

		 * name equivalents (some are the same). Only values which are also

		 * present in $registered will be set.

		 */

		$parameter_mappings = array(

		);

		$prepared_args = array();

		/*

		 * For each known parameter which is both registered and present in the request,

		 * set the parameter's value on the query $prepared_args.

		 */

		foreach ( $parameter_mappings as $api_param => $wp_param ) {

			if ( isset( $registered[ $api_param ], $request[ $api_param ] ) ) {

				$prepared_args[ $wp_param ] = $request[ $api_param ];

			}

		}

		if ( isset( $registered['offset'] ) && ! empty( $request['offset'] ) ) {

			$prepared_args['offset'] = $request['offset'];

		} else {

			$prepared_args['offset'] = ( $request['page'] - 1 ) * $prepared_args['number'];

		}

		if ( isset( $registered['orderby'] ) ) {

			$orderby_possibles        = array(

				'id'              => 'ID',

				'include'         => 'include',

				'name'            => 'display_name',

				'registered_date' => 'registered',

				'slug'            => 'user_nicename',

				'include_slugs'   => 'nicename__in',

				'email'           => 'user_email',

				'url'             => 'user_url',

			);

			$prepared_args['orderby'] = $orderby_possibles[ $request['orderby'] ];

		}

		if ( isset( $registered['who'] ) && ! empty( $request['who'] ) && 'authors' === $request['who'] ) {

			$prepared_args['who'] = 'authors';

		} elseif ( ! current_user_can( 'list_users' ) ) {

			$prepared_args['has_published_posts'] = get_post_types( array( 'show_in_rest' => true ), 'names' );

		}

		if ( ! empty( $prepared_args['search'] ) ) {

			$prepared_args['search'] = '*' . $prepared_args['search'] . '*';

		}

		/**

		 * Filters WP_User_Query arguments when querying users via the REST API.

		 *

		 * @link https://developer.wordpress.org/reference/classes/wp_user_query/

		 *

		 * @since 4.7.0

		 *

		 * @param array           $prepared_args Array of arguments for WP_User_Query.

		 * @param WP_REST_Request $request       The REST API request.

		 */

		$prepared_args = apply_filters( 'rest_user_query', $prepared_args, $request );

		$query = new WP_User_Query( $prepared_args );

		$users = array();

		foreach ( $query->results as $user ) {

			$data    = $this->prepare_item_for_response( $user, $request );

			$users[] = $this->prepare_response_for_collection( $data );

		}

		$response = rest_ensure_response( $users );

		// Store pagination values for headers then unset for count query.

		$per_page = (int) $prepared_args['number'];

		$page     = ceil( ( ( (int) $prepared_args['offset'] ) / $per_page ) + 1 );

		$prepared_args['fields'] = 'ID';

		$total_users = $query->get_total();

		if ( $total_users < 1 ) {

			// Out-of-bounds, run the query again without LIMIT for total count.

			unset( $prepared_args['number'], $prepared_args['offset'] );

			$count_query = new WP_User_Query( $prepared_args );

			$total_users = $count_query->get_total();

		}

		$response->header( 'X-WP-Total', (int) $total_users );

		$max_pages = ceil( $total_users / $per_page );

		$response->header( 'X-WP-TotalPages', (int) $max_pages );

		$base = add_query_arg( urlencode_deep( $request->get_query_params() ), rest_url( sprintf( '%s/%s', $this->namespace, $this->rest_base ) ) );

		if ( $page > 1 ) {

			$prev_page = $page - 1;

			if ( $prev_page > $max_pages ) {

				$prev_page = $max_pages;

			}

			$prev_link = add_query_arg( 'page', $prev_page, $base );

			$response->link_header( 'prev', $prev_link );

		}

		if ( $max_pages > $page ) {

			$next_page = $page + 1;

			$next_link = add_query_arg( 'page', $next_page, $base );

			$response->link_header( 'next', $next_link );

		}

		return $response;

	}

	/**

	 * Get the user, if the ID is valid.

	 *

	 * @since 4.7.2

	 *

	 * @param int $id Supplied ID.

	 * @return WP_User|WP_Error True if ID is valid, WP_Error otherwise.

	 */

	protected function get_user( $id ) {

		$error = new WP_Error(

			'rest_user_invalid_id',

			__( 'Invalid user ID.' ),

			array( 'status' => 404 )

		);

		if ( (int) $id <= 0 ) {

			return $error;

		}

		$user = get_userdata( (int) $id );

		if ( empty( $user ) || ! $user->exists() ) {

			return $error;

		}