<?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;

	/**

	 * Whether the controller supports batching.

	 *

	 * @since 6.6.0

	 * @var array

	 */

	protected $allow_batch = array( 'v1' => true );

	/**

	 * 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 ),

				),

				'allow_batch' => $this->allow_batch,

				'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' ),

						),

					),

				),

				'allow_batch' => $this->allow_batch,

				'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() )

			);

		}

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

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

			return new WP_Error(

				'rest_user_cannot_view',

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

				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

	 * @since 6.8.0 Added support for the search_columns query param.

	 *

	 * @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(

			'exclude'      => 'exclude',

			'include'      => 'include',

			'order'        => 'order',

			'per_page'     => 'number',

			'search'       => 'search',

			'roles'        => 'role__in',

			'capabilities' => 'capability__in',

			'slug'         => 'nicename__in',

		);

		$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( $request['has_published_posts'] ) ) {

			$prepared_args['has_published_posts'] = ( true === $request['has_published_posts'] )

				? get_post_types( array( 'show_in_rest' => true ), 'names' )

				: (array) $request['has_published_posts'];

		}

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

			if ( ! current_user_can( 'list_users' ) ) {

				$prepared_args['search_columns'] = array( 'ID', 'user_login', 'user_nicename', 'display_name' );

			}

			$search_columns         = $request->get_param( 'search_columns' );

			$valid_columns          = isset( $prepared_args['search_columns'] )

				? $prepared_args['search_columns']

				: array( 'ID', 'user_login', 'user_nicename', 'user_email', 'display_name' );

			$search_columns_mapping = array(

				'id'       => 'ID',

				'username' => 'user_login',

				'slug'     => 'user_nicename',

				'email'    => 'user_email',

				'name'     => 'display_name',

			);

			$search_columns         = array_map(

				static function ( $column ) use ( $search_columns_mapping ) {

					return $search_columns_mapping[ $column ];

				},

				$search_columns

			);

			$search_columns         = array_intersect( $search_columns, $valid_columns );

			if ( ! empty( $search_columns ) ) {

				$prepared_args['search_columns'] = $search_columns;

			}

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

		}

		$is_head_request = $request->is_method( 'HEAD' );

		if ( $is_head_request ) {

			// Force the 'fields' argument. For HEAD requests, only user IDs are required.

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

		}

		/**

		 * 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 );

		if ( ! $is_head_request ) {

			$users = array();

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

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

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

			}

		}

		$response = $is_head_request ? new WP_REST_Response( array() ) : rest_ensure_response( $users );

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

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

		$page     = (int) 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 = (int) ceil( $total_users / $per_page );