WordPress.org
Get WordPress

Make WordPress Core

Changeset 39036


Ignore:
Timestamp:
10/30/2016 06:51:30 PM (8 years ago)
Author:
DrewAPicture
Message:

Docs: Add much more complete and syntactically correct documentation throughout the WP_REST_Users_Controller class.

Props Soean, mrahmadawais, flixos90.
See #38398.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-includes/rest-api/endpoints/class-wp-rest-users-controller.php

    r38990 r39036  
    11<?php
    2 
    32/**
    4  * Access users
     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
    516 */
    617class WP_REST_Users_Controller extends WP_REST_Controller {
    … …  
    920     * Instance of a user meta fields object.
    1021     *
     22     * @since 4.7.0
    1123     * @access protected
    1224     * @var WP_REST_User_Meta_Fields
    … …  
    1426    protected $meta;
    1527
     28    /**
     29     * Constructor.
     30     *
     31     * @since 4.7.0
     32     * @access public
     33     */
    1634    public function __construct() {
    1735        $this->namespace = 'wp/v2';
    … …  
    2240
    2341    /**
    24      * Register the routes for the objects of the controller.
     42     * Registers the routes for the objects of the controller.
     43     *
     44     * @since 4.7.0
     45     * @access public
     46     *
     47     * @see register_rest_route()
    2548     */
    2649    public function register_routes() {
    … …  
    2851        register_rest_route( $this->namespace, '/' . $this->rest_base, array(
    2952            array(
    30                 'methods'         => WP_REST_Server::READABLE,
    31                 'callback'        => array( $this, 'get_items' ),
     53                'methods'             => WP_REST_Server::READABLE,
     54                'callback'            => array( $this, 'get_items' ),
    3255                'permission_callback' => array( $this, 'get_items_permissions_check' ),
    33                 'args'            => $this->get_collection_params(),
     56                'args'                => $this->get_collection_params(),
    3457            ),
    3558            array(
    36                 'methods'         => WP_REST_Server::CREATABLE,
    37                 'callback'        => array( $this, 'create_item' ),
     59                'methods'             => WP_REST_Server::CREATABLE,
     60                'callback'            => array( $this, 'create_item' ),
    3861                'permission_callback' => array( $this, 'create_item_permissions_check' ),
    39                 'args'            => $this->get_endpoint_args_for_item_schema( WP_REST_Server::CREATABLE ),
     62                'args'                => $this->get_endpoint_args_for_item_schema( WP_REST_Server::CREATABLE ),
    4063            ),
    4164            'schema' => array( $this, 'get_public_item_schema' ),
    4265        ) );
     66
    4367        register_rest_route( $this->namespace, '/' . $this->rest_base . '/(?P<id>[\d]+)', array(
    4468            array(
    45                 'methods'         => WP_REST_Server::READABLE,
    46                 'callback'        => array( $this, 'get_item' ),
     69                'methods'             => WP_REST_Server::READABLE,
     70                'callback'            => array( $this, 'get_item' ),
    4771                'permission_callback' => array( $this, 'get_item_permissions_check' ),
    48                 'args'            => array(
    49                     'context'          => $this->get_context_param( array( 'default' => 'view' ) ),
     72                'args'                => array(
     73                    'context' => $this->get_context_param( array( 'default' => 'view' ) ),
    5074                ),
    5175            ),
    5276            array(
    53                 'methods'         => WP_REST_Server::EDITABLE,
    54                 'callback'        => array( $this, 'update_item' ),
     77                'methods'             => WP_REST_Server::EDITABLE,
     78                'callback'            => array( $this, 'update_item' ),
    5579                'permission_callback' => array( $this, 'update_item_permissions_check' ),
    56                 'args'            => $this->get_endpoint_args_for_item_schema( WP_REST_Server::EDITABLE ),
     80                'args'                => $this->get_endpoint_args_for_item_schema( WP_REST_Server::EDITABLE ),
    5781            ),
    5882            array(
    59                 'methods' => WP_REST_Server::DELETABLE,
    60                 'callback' => array( $this, 'delete_item' ),
     83                'methods'             => WP_REST_Server::DELETABLE,
     84                'callback'            => array( $this, 'delete_item' ),
    6185                'permission_callback' => array( $this, 'delete_item_permissions_check' ),
    62                 'args' => array(
     86                'args'                => array(
    6387                    'force'    => array(
    6488                        'default'     => false,
    … …  
    7296
    7397        register_rest_route( $this->namespace, '/' . $this->rest_base . '/me', array(
    74             'methods'         => WP_REST_Server::READABLE,
    75             'callback'        => array( $this, 'get_current_item' ),
    76             'args'            => array(
    77                 'context'          => array(),
     98            'methods'  => WP_REST_Server::READABLE,
     99            'callback' => array( $this, 'get_current_item' ),
     100            'args'     => array(
     101                'context' => array(),
    78102            ),
    79103            'schema' => array( $this, 'get_public_item_schema' ),
    … …  
    84108     * Permissions check for getting all users.
    85109     *
     110     * @since 4.7.0
     111     * @access public
     112     *
    86113     * @param WP_REST_Request $request Full details about the request.
    87      * @return WP_Error|boolean
     114     * @return true|WP_Error True if the request has read access, otherwise WP_Error object.
    88115     */
    89116    public function get_items_permissions_check( $request ) {
    … …  
    105132
    106133    /**
    107      * Get all users
     134     * Retrieves all users.
     135     *
     136     * @since 4.7.0
     137     * @access public
    108138     *
    109139     * @param WP_REST_Request $request Full details about the request.
    110      * @return WP_Error|WP_REST_Response
     140     * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
    111141     */
    112142    public function get_items( $request ) {
    … …  
    115145        $registered = $this->get_collection_params();
    116146
    117         // This array defines mappings between public API query parameters whose
    118         // values are accepted as-passed, and their internal WP_Query parameter
    119         // name equivalents (some are the same). Only values which are also
    120         // present in $registered will be set.
     147        /*
     148         * This array defines mappings between public API query parameters whose
     149         * values are accepted as-passed, and their internal WP_Query parameter
     150         * name equivalents (some are the same). Only values which are also
     151         * present in $registered will be set.
     152         */
    121153        $parameter_mappings = array(
    122154            'exclude'  => 'exclude',
    … …  
    130162        $prepared_args = array();
    131163
    132         // For each known parameter which is both registered and present in the request,
    133         // set the parameter's value on the query $prepared_args.
     164        /*
     165         * For each known parameter which is both registered and present in the request,
     166         * set the parameter's value on the query $prepared_args.
     167         */
    134168        foreach ( $parameter_mappings as $api_param => $wp_param ) {
    135169            if ( isset( $registered[ $api_param ], $request[ $api_param ] ) ) {
    … …  
    171205
    172206        /**
    173          * Filter arguments, before passing to WP_User_Query, when querying users via the REST API.
     207         * Filters WP_User_Query arguments when querying users via the REST API.
    174208         *
    175          * @see https://developer.wordpress.org/reference/classes/wp_user_query/
     209         * @link https://developer.wordpress.org/reference/classes/wp_user_query/
     210         *
     211         * @since 4.7.0
    176212         *
    177213         * @param array           $prepared_args Array of arguments for WP_User_Query.
    … …  
    183219
    184220        $users = array();
     221
    185222        foreach ( $query->results as $user ) {
    186223            $data = $this->prepare_item_for_response( $user, $request );
    … …  
    192229        // Store pagination values for headers then unset for count query.
    193230        $per_page = (int) $prepared_args['number'];
    194         $page = ceil( ( ( (int) $prepared_args['offset'] ) / $per_page ) + 1 );
     231        $page     = ceil( ( ( (int) $prepared_args['offset'] ) / $per_page ) + 1 );
    195232
    196233        $prepared_args['fields'] = 'ID';
    197234
    198235        $total_users = $query->get_total();
     236
    199237        if ( $total_users < 1 ) {
    200             // Out-of-bounds, run the query again without LIMIT for total count
     238            // Out-of-bounds, run the query again without LIMIT for total count.
    201239            unset( $prepared_args['number'], $prepared_args['offset'] );
    202240            $count_query = new WP_User_Query( $prepared_args );
    203241            $total_users = $count_query->get_total();
    204242        }
     243
    205244        $response->header( 'X-WP-Total', (int) $total_users );
     245
    206246        $max_pages = ceil( $total_users / $per_page );
     247
    207248        $response->header( 'X-WP-TotalPages', (int) $max_pages );
    208249
    … …  
    210251        if ( $page > 1 ) {
    211252            $prev_page = $page - 1;
     253
    212254            if ( $prev_page > $max_pages ) {
    213255                $prev_page = $max_pages;
    214256            }
     257
    215258            $prev_link = add_query_arg( 'page', $prev_page, $base );
    216259            $response->link_header( 'prev', $prev_link );
    … …  
    219262            $next_page = $page + 1;
    220263            $next_link = add_query_arg( 'page', $next_page, $base );
     264
    221265            $response->link_header( 'next', $next_link );
    222266        }
    … …  
    226270
    227271    /**
    228      * Check if a given request has access to read a user
    229      *
    230      * @param  WP_REST_Request $request Full details about the request.
    231      * @return WP_Error|boolean
     272     * Checks if a given request has access to read a user.
     273     *
     274     * @since 4.7.0
     275     * @access public
     276     *
     277     * @param WP_REST_Request $request Full details about the request.
     278     * @return true|WP_Error True if the request has read access for the item, otherwise WP_Error object.
    232279     */
    233280    public function get_item_permissions_check( $request ) {
    … …  
    255302
    256303    /**
    257      * Get a single user
     304     * Retrieves a single user.
     305     *
     306     * @since 4.7.0
     307     * @access public
    258308     *
    259309     * @param WP_REST_Request $request Full details about the request.
    260      * @return WP_Error|WP_REST_Response
     310     * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
    261311     */
    262312    public function get_item( $request ) {
    263         $id = (int) $request['id'];
     313        $id   = (int) $request['id'];
    264314        $user = get_userdata( $id );
    265315
    … …  
    275325
    276326    /**
    277      * Get the current user
     327     * Retrieves the current user.
     328     *
     329     * @since 4.7.0
     330     * @access public
    278331     *
    279332     * @param WP_REST_Request $request Full details about the request.
    280      * @return WP_Error|WP_REST_Response
     333     * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
    281334     */
    282335    public function get_current_item( $request ) {
    283336        $current_user_id = get_current_user_id();
     337
    284338        if ( empty( $current_user_id ) ) {
    285339            return new WP_Error( 'rest_not_logged_in', __( 'You are not currently logged in.' ), array( 'status' => 401 ) );
    286340        }
    287341
    288         $user = wp_get_current_user();
     342        $user     = wp_get_current_user();
    289343        $response = $this->prepare_item_for_response( $user, $request );
    290344        $response = rest_ensure_response( $response );
     345
    291346        $response->header( 'Location', rest_url( sprintf( '%s/%s/%d', $this->namespace, $this->rest_base, $current_user_id ) ) );
    292347        $response->set_status( 302 );
    … …  
    296351
    297352    /**
    298      * Check if a given request has access create users
    299      *
    300      * @param  WP_REST_Request $request Full details about the request.
    301      * @return WP_Error|boolean
     353     * Checks if a given request has access create users.
     354     *
     355     * @since 4.7.0
     356     * @access public
     357     *
     358     * @param WP_REST_Request $request Full details about the request.
     359     * @return true|WP_Error True if the request has access to create items, WP_Error object otherwise.
    302360     */
    303361    public function create_item_permissions_check( $request ) {
    … …  
    311369
    312370    /**
    313      * Create a single user
     371     * Creates a single user.
     372     *
     373     * @since 4.7.0
     374     * @access public
    314375     *
    315376     * @param WP_REST_Request $request Full details about the request.
    316      * @return WP_Error|WP_REST_Response
     377     * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
    317378     */
    318379    public function create_item( $request ) {
    … …  
    325386        if ( ! empty( $request['roles'] ) && ! empty( $schema['properties']['roles'] ) ) {
    326387            $check_permission = $this->check_role_update( $request['id'], $request['roles'] );
     388
    327389            if ( is_wp_error( $check_permission ) ) {
    328390                return $check_permission;
    … …  
    334396        if ( is_multisite() ) {
    335397            $ret = wpmu_validate_user_signup( $user->user_login, $user->user_email );
     398
    336399            if ( is_wp_error( $ret['errors'] ) && ! empty( $ret['errors']->errors ) ) {
    337400                return $ret['errors'];
    … …  
    341404        if ( is_multisite() ) {
    342405            $user_id = wpmu_create_user( $user->user_login, $user->user_pass, $user->user_email );
     406
    343407            if ( ! $user_id ) {
    344408                return new WP_Error( 'rest_user_create', __( 'Error creating new resource.' ), array( 'status' => 500 ) );
    345409            }
     410
    346411            $user->ID = $user_id;
    347             $user_id = wp_update_user( $user );
     412            $user_id  = wp_update_user( $user );
     413
    348414            if ( is_wp_error( $user_id ) ) {
    349415                return $user_id;
    … …  
    351417        } else {
    352418            $user_id = wp_insert_user( $user );
     419
    353420            if ( is_wp_error( $user_id ) ) {
    354421                return $user_id;
    … …  
    357424
    358425        $user = get_user_by( 'id', $user_id );
     426
    359427        if ( ! empty( $request['roles'] ) && ! empty( $schema['properties']['roles'] ) ) {
    360428            array_map( array( $user, 'add_role' ), $request['roles'] );
    … …  
    363431        if ( ! empty( $schema['properties']['meta'] ) && isset( $request['meta'] ) ) {
    364432            $meta_update = $this->meta->update_value( $request['meta'], $user_id );
     433
    365434            if ( is_wp_error( $meta_update ) ) {
    366435                return $meta_update;
    … …  
    369438
    370439        $fields_update = $this->update_additional_fields_for_object( $user, $request );
     440
    371441        if ( is_wp_error( $fields_update ) ) {
    372442            return $fields_update;
    … …  
    374444
    375445        /**
    376          * Fires after a user is created or updated via the REST API.
     446         * Fires immediately after a user is created or updated via the REST API.
    377447         *
    378          * @param WP_User         $user      Data used to create the user.
    379          * @param WP_REST_Request $request   Request object.
    380          * @param boolean         $creating  True when creating user, false when updating user.
     448         * @since 4.7.0
     449         *
     450         * @param WP_User         $user     Data used to create the user.
     451         * @param WP_REST_Request $request  Request object.
     452         * @param bool            $creating True when creating user, false when updating user.
    381453         */
    382454        do_action( 'rest_insert_user', $user, $request, true );
    383455
    384456        $request->set_param( 'context', 'edit' );
     457
    385458        $response = $this->prepare_item_for_response( $user, $request );
    386459        $response = rest_ensure_response( $response );
     460
    387461        $response->set_status( 201 );
    388462        $response->header( 'Location', rest_url( sprintf( '%s/%s/%d', $this->namespace, $this->rest_base, $user_id ) ) );
    … …  
    392466
    393467    /**
    394      * Check if a given request has access update a user
    395      *
    396      * @param  WP_REST_Request $request Full details about the request.
    397      * @return WP_Error|boolean
     468     * Checks if a given request has access to update a user.
     469     *
     470     * @since 4.7.0
     471     * @access public
     472     *
     473     * @param WP_REST_Request $request Full details about the request.
     474     * @return true|WP_Error True if the request has access to update the item, WP_Error object otherwise.
    398475     */
    399476    public function update_item_permissions_check( $request ) {
    … …  
    413490
    414491    /**
    415      * Update a single user
     492     * Updates a single user.
     493     *
     494     * @since 4.7.0
     495     * @access public
    416496     *
    417497     * @param WP_REST_Request $request Full details about the request.
    418      * @return WP_Error|WP_REST_Response
     498     * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
    419499     */
    420500    public function update_item( $request ) {
    421         $id = (int) $request['id'];
    422 
     501        $id   = (int) $request['id'];
    423502        $user = get_userdata( $id );
     503
    424504        if ( ! $user ) {
    425505            return new WP_Error( 'rest_user_invalid_id', __( 'Invalid resource id.' ), array( 'status' => 404 ) );
    … …  
    440520        if ( ! empty( $request['roles'] ) ) {
    441521            $check_permission = $this->check_role_update( $id, $request['roles'] );
     522
    442523            if ( is_wp_error( $check_permission ) ) {
    443524                return $check_permission;
    … …  
    447528        $user = $this->prepare_item_for_database( $request );
    448529
    449         // Ensure we're operating on the same user we already checked
     530        // Ensure we're operating on the same user we already checked.
    450531        $user->ID = $id;
    451532
    452533        $user_id = wp_update_user( $user );
     534
    453535        if ( is_wp_error( $user_id ) ) {
    454536            return $user_id;
    … …  
    456538
    457539        $user = get_user_by( 'id', $id );
     540
    458541        if ( ! empty( $request['roles'] ) ) {
    459542            array_map( array( $user, 'add_role' ), $request['roles'] );
    … …  
    461544
    462545        $schema = $this->get_item_schema();
     546
    463547        if ( ! empty( $schema['properties']['meta'] ) && isset( $request['meta'] ) ) {
    464548            $meta_update = $this->meta->update_value( $request['meta'], $id );
     549
    465550            if ( is_wp_error( $meta_update ) ) {
    466551                return $meta_update;
    … …  
    469554
    470555        $fields_update = $this->update_additional_fields_for_object( $user, $request );
     556
    471557        if ( is_wp_error( $fields_update ) ) {
    472558            return $fields_update;
    … …  
    477563
    478564        $request->set_param( 'context', 'edit' );
     565
    479566        $response = $this->prepare_item_for_response( $user, $request );
    480567        $response = rest_ensure_response( $response );
     568
    481569        return $response;
    482570    }
    483571
    484572    /**
    485      * Check if a given request has access delete a user
    486      *
    487      * @param  WP_REST_Request $request Full details about the request.
    488      * @return WP_Error|boolean
     573     * Checks if a given request has access delete a user.
     574     *
     575     * @since 4.7.0
     576     * @access public
     577     *
     578     * @param WP_REST_Request $request Full details about the request.
     579     * @return true|WP_Error True if the request has access to delete the item, WP_Error object otherwise.
    489580     */
    490581    public function delete_item_permissions_check( $request ) {
    … …  
    500591
    501592    /**
    502      * Delete a single user
     593     * Deletes a single user.
     594     *
     595     * @since 4.7.0
     596     * @access public
    503597     *
    504598     * @param WP_REST_Request $request Full details about the request.
    505      * @return WP_Error|WP_REST_Response
     599     * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
    506600     */
    507601    public function delete_item( $request ) {
    508         $id = (int) $request['id'];
     602        $id       = (int) $request['id'];
    509603        $reassign = isset( $request['reassign'] ) ? absint( $request['reassign'] ) : null;
    510         $force = isset( $request['force'] ) ? (bool) $request['force'] : false;
    511 
    512         // We don't support trashing for this type, error out
     604        $force    = isset( $request['force'] ) ? (bool) $request['force'] : false;
     605
     606        // We don't support trashing for this type, error out.
    513607        if ( ! $force ) {
    514608            return new WP_Error( 'rest_trash_not_supported', __( 'Users do not support trashing.' ), array( 'status' => 501 ) );
    … …  
    516610
    517611        $user = get_userdata( $id );
     612
    518613        if ( ! $user ) {
    519614            return new WP_Error( 'rest_user_invalid_id', __( 'Invalid resource id.' ), array( 'status' => 404 ) );
    … …  
    527622
    528623        $request->set_param( 'context', 'edit' );
     624
    529625        $response = $this->prepare_item_for_response( $user, $request );
    530626
    … …  
    539635
    540636        /**
    541          * Fires after a user is deleted via the REST API.
     637         * Fires immediately after a user is deleted via the REST API.
     638         *
     639         * @since 4.7.0
    542640         *
    543641         * @param WP_User          $user     The user data.
    … …  
    551649
    552650    /**
    553      * Prepare a single user output for response
    554      *
    555      * @param object $user User object.
     651     * Prepares a single user output for response.
     652     *
     653     * @since 4.7.0
     654     * @access public
     655     *
     656     * @param WP_User         $user    User object.
    556657     * @param WP_REST_Request $request Request object.
    557      * @return WP_REST_Response $response Response data.
     658     * @return WP_REST_Response Response object.
    558659     */
    559660    public function prepare_item_for_response( $user, $request ) {
    560661
    561         $data = array();
     662        $data   = array();
    562663        $schema = $this->get_item_schema();
     664
    563665        if ( ! empty( $schema['properties']['id'] ) ) {
    564666            $data['id'] = $user->ID;
    … …  
    635737        $data = $this->filter_response_by_context( $data, $context );
    636738
    637         // Wrap the data in a response object
     739        // Wrap the data in a response object.
    638740        $response = rest_ensure_response( $data );
    639741
    … …  
    641743
    642744        /**
    643          * Filter user data returned from the REST API.
     745         * Filters user data returned from the REST API.
    644746         *
    645          * @param WP_REST_Response $response  The response object.
    646          * @param object           $user      User object used to create response.
    647          * @param WP_REST_Request  $request   Request object.
     747         * @since 4.7.0
     748         *
     749         * @param WP_REST_Response $response The response object.
     750         * @param object           $user     User object used to create response.
     751         * @param WP_REST_Request  $request  Request object.
    648752         */
    649753        return apply_filters( 'rest_prepare_user', $response, $user, $request );
    … …  
    651755
    652756    /**
    653      * Prepare links for the request.
     757     * Prepares links for the user request.
     758     *
     759     * @since 4.7.0
     760     * @access protected
    654761     *
    655762     * @param WP_Post $user User object.
    … …  
    670777
    671778    /**
    672      * Prepare a single user for create or update
     779     * Prepares a single user for creation or update.
     780     *
     781     * @since 4.7.0
     782     * @access protected
    673783     *
    674784     * @param WP_REST_Request $request Request object.
    … …  
    684794            $prepared_user->user_email = $request['email'];
    685795        }
     796
    686797        if ( isset( $request['username'] ) && ! empty( $schema['properties']['username'] ) ) {
    687798            $prepared_user->user_login = $request['username'];
    688799        }
     800
    689801        if ( isset( $request['password'] ) && ! empty( $schema['properties']['password'] ) ) {
    690802            $prepared_user->user_pass = $request['password'];
    … …  
    695807            $prepared_user->ID = absint( $request['id'] );
    696808        }
     809
    697810        if ( isset( $request['name'] ) && ! empty( $schema['properties']['name'] ) ) {
    698811            $prepared_user->display_name = $request['name'];
    699812        }
     813
    700814        if ( isset( $request['first_name'] ) && ! empty( $schema['properties']['first_name'] ) ) {
    701815            $prepared_user->first_name = $request['first_name'];
    702816        }
     817
    703818        if ( isset( $request['last_name'] ) && ! empty( $schema['properties']['last_name'] ) ) {
    704819            $prepared_user->last_name = $request['last_name'];
    705820        }
     821
    706822        if ( isset( $request['nickname'] ) && ! empty( $schema['properties']['nickname'] ) ) {
    707823            $prepared_user->nickname = $request['nickname'];
    708824        }
     825
    709826        if ( isset( $request['slug'] ) && ! empty( $schema['properties']['slug'] ) ) {
    710827            $prepared_user->user_nicename = $request['slug'];
    711828        }
     829
    712830        if ( isset( $request['description'] ) && ! empty( $schema['properties']['description'] ) ) {
    713831            $prepared_user->description = $request['description'];
    … …  
    724842
    725843        /**
    726          * Filter user data before inserting user via the REST API.
     844         * Filters user data before insertion via the REST API.
     845         *
     846         * @since 4.7.0
    727847         *
    728848         * @param object          $prepared_user User object.
    … …  
    733853
    734854    /**
    735      * Determine if the current user is allowed to make the desired roles change.
     855     * Determines if the current user is allowed to make the desired roles change.
     856     *
     857     * @since 4.7.0
     858     * @access protected
    736859     *
    737860     * @param integer $user_id User ID.
    738861     * @param array   $roles   New user roles.
    739      * @return WP_Error|boolean
     862     * @return true|WP_Error True if the current user is allowed to make the role change,
     863     *                       otherwise a WP_Error object.
    740864     */
    741865    protected function check_role_update( $user_id, $roles ) {
    … …  
    749873
    750874            $potential_role = $wp_roles->role_objects[ $role ];
    751             // Don't let anyone with 'edit_users' (admins) edit their own role to something without it.
    752             // Multisite super admins can freely edit their blog roles -- they possess all caps.
    753             if ( ! ( is_multisite() && current_user_can( 'manage_sites' ) ) && get_current_user_id() === $user_id && ! $potential_role->has_cap( 'edit_users' ) ) {
     875
     876            /*
     877             * Don't let anyone with 'edit_users' (admins) edit their own role to something without it.
     878             * Multisite super admins can freely edit their blog roles -- they possess all caps.
     879             */
     880            if ( ! ( is_multisite()
     881                && current_user_can( 'manage_sites' ) )
     882                && get_current_user_id() === $user_id
     883                && ! $potential_role->has_cap( 'edit_users' )
     884            ) {
    754885                return new WP_Error( 'rest_user_invalid_role', __( 'You cannot give resource that role.' ), array( 'status' => rest_authorization_required_code() ) );
    755886            }
    756 
    757             // The new role must be editable by the logged-in user.
    758887
    759888            /** Include admin functions to get access to get_editable_roles() */
    760889            require_once ABSPATH . 'wp-admin/includes/admin.php';
    761890
     891            // The new role must be editable by the logged-in user.
    762892            $editable_roles = get_editable_roles();
     893
    763894            if ( empty( $editable_roles[ $role ] ) ) {
    764895                return new WP_Error( 'rest_user_invalid_role', __( 'You cannot give resource that role.' ), array( 'status' => 403 ) );
    … …  
    767898
    768899        return true;
    769 
    770     }
    771 
    772     /**
    773      * Get the User's schema, conforming to JSON Schema
    774      *
    775      * @return array
     900    }
     901
     902    /**
     903     * Retrieves the user's schema, conforming to JSON Schema.
     904     *
     905     * @since 4.7.0
     906     * @access public
     907     *
     908     * @return array Item schema data.
    776909     */
    777910    public function get_item_schema() {
    … …  
    8791012                    'description' => __( 'Password for the resource (never included).' ),
    8801013                    'type'        => 'string',
    881                     'context'     => array(), // Password is never displayed
     1014                    'context'     => array(), // Password is never displayed.
    8821015                    'required'    => true,
    8831016                ),
    … …  
    9011034
    9021035            $avatar_sizes = rest_get_avatar_sizes();
     1036
    9031037            foreach ( $avatar_sizes as $size ) {
    9041038                $avatar_properties[ $size ] = array(
    … …  
    9251059
    9261060    /**
    927      * Get the query params for collections
    928      *
    929      * @return array
     1061     * Retrieves the query params for collections.
     1062     *
     1063     * @since 4.7.0
     1064     * @access public
     1065     *
     1066     * @return array Collection parameters.
    9301067     */
    9311068    public function get_collection_params() {
    … …  
    9401077            'sanitize_callback'  => 'wp_parse_id_list',
    9411078        );
     1079
    9421080        $query_params['include'] = array(
    9431081            'description'        => __( 'Limit result set to specific ids.' ),
    … …  
    9461084            'sanitize_callback'  => 'wp_parse_id_list',
    9471085        );
     1086
    9481087        $query_params['offset'] = array(
    9491088            'description'        => __( 'Offset the result set by a specific number of items.' ),
    … …  
    9521091            'validate_callback'  => 'rest_validate_request_arg',
    9531092        );
     1093
    9541094        $query_params['order'] = array(
    9551095            'default'            => 'asc',
    … …  
    9601100            'validate_callback'  => 'rest_validate_request_arg',
    9611101        );
     1102
    9621103        $query_params['orderby'] = array(
    9631104            'default'            => 'name',
    … …  
    9761117            'validate_callback'  => 'rest_validate_request_arg',
    9771118        );
     1119
    9781120        $query_params['slug']    = array(
    9791121            'description'        => __( 'Limit result set to resources with a specific slug.' ),
    … …  
    9811123            'validate_callback'  => 'rest_validate_request_arg',
    9821124        );
     1125
    9831126        $query_params['roles']   = array(
    9841127            'description'        => __( 'Limit result set to resources matching at least one specific role provided. Accepts csv list or single role.' ),
    … …  
    9861129            'sanitize_callback'  => 'wp_parse_slug_list',
    9871130        );
     1131
    9881132        return $query_params;
    9891133    }
Note: See TracChangeset for help on using the changeset viewer.