WordPress.org
Get WordPress

Make WordPress Core


Ignore:
Timestamp:
10/27/2021 06:42:13 PM (3 years ago)
Author:
swissspidy
Message:

Role/Capability: Add support for capability queries in WP_User_Query.

Similar to the existing role/role__in/role__not_in query arguments, this adds support for three new query arguments in WP_User_Query:

  • capability
  • capability__in
  • capability__not_in

These can be used to fetch users with (or without) a specific set of capabilities, for example to get all users
with the capability to edit a certain post type.

Under the hood, this will check all existing roles on the site and perform a LIKE query against the capabilities user meta field to find:

  • all users with a role that has this capability
  • all users with the capability being assigned directly

Note: In WordPress, not all capabilities are stored in the database. Capabilities can also be modified using filters like map_meta_cap. These new query arguments do NOT work for such capabilities.

The prime use case for capability queries is to get all "authors", i.e. users with the capability to edit a certain post type.

Until now, 'who' => 'authors' was used for this, which relies on user levels. However, user levels were deprecated a long time ago and thus never added to custom roles. This led to constant frustration due to users with custom roles missing from places like author dropdowns.

This updates any usage of 'who' => 'authors' in core to use capability queries instead.

Subsequently, 'who' => 'authors' queries are being deprecated in favor of these new query arguments.

Also adds a new capabilities parameter (mapping to capability__in in WP_User_Query) to the REST API users controller.

Also updates twentyfourteen_list_authors() in Twenty Fourteen to make use of this new functionality, adding a new twentyfourteen_list_authors_query_args filter to make it easier to override this behavior.

Props scribu, lgladdly, boonebgorges, spacedmonkey, peterwilsoncc, SergeyBiryukov, swissspidy.
Fixes #16841.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/tests/phpunit/tests/rest-api/rest-users-controller.php

    r51568 r51943  
    1616    protected static $draft_editor;
    1717    protected static $subscriber;
     18    protected static $author;
    1819
    1920    protected static $authors     = array();
    … …  
    5455                'display_name' => 'subscriber',
    5556                'user_email'   => 'subscriber@example.com',
     57            )
     58        );
     59        self::$author       = $factory->user->create(
     60            array(
     61                'display_name' => 'author',
     62                'role'         => 'author',
     63                'user_email'   => 'author@example.com',
    5664            )
    5765        );
    … …  
    108116
    109117        // Set up users for pagination tests.
    110         for ( $i = 0; $i < self::$total_users - 10; $i++ ) {
     118        for ( $i = 0; $i < self::$total_users - 11; $i++ ) {
    111119            self::$user_ids[] = $factory->user->create(
    112120                array(
    … …  
    122130        self::delete_user( self::$editor );
    123131        self::delete_user( self::$draft_editor );
     132        self::delete_user( self::$author );
    124133
    125134        foreach ( self::$posts as $post ) {
    … …  
    184193        $data     = $response->get_data();
    185194        $keys     = array_keys( $data['endpoints'][0]['args'] );
    186         sort( $keys );
    187         $this->assertSame(
     195        $this->assertEqualSets(
    188196            array(
    189197                'context',
    … …  
    196204                'per_page',
    197205                'roles',
     206                'capabilities',
    198207                'search',
    199208                'slug',
    … …  
    796805        wp_set_current_user( self::$user );
    797806
    798         $tango = $this->factory->user->create(
    799             array(
    800                 'display_name' => 'tango',
    801                 'role'         => 'subscriber',
    802             )
    803         );
    804         $yolo  = $this->factory->user->create(
    805             array(
    806                 'display_name' => 'yolo',
    807                 'role'         => 'author',
    808             )
    809         );
    810 
    811807        $request = new WP_REST_Request( 'GET', '/wp/v2/users' );
    812808        $request->set_param( 'roles', 'author,subscriber' );
    813809        $response = rest_get_server()->dispatch( $request );
    814810        $data     = $response->get_data();
    815         $this->assertCount( 3, $data );
    816         $this->assertSame( $tango, $data[1]['id'] );
    817         $this->assertSame( $yolo, $data[2]['id'] );
     811        $this->assertCount( 2, $data );
     812        $this->assertSame( self::$author, $data[0]['id'] );
     813        $this->assertSame( self::$subscriber, $data[1]['id'] );
    818814
    819815        $request->set_param( 'roles', 'author' );
    … …  
    821817        $data     = $response->get_data();
    822818        $this->assertCount( 1, $data );
    823         $this->assertSame( $yolo, $data[0]['id'] );
     819        $this->assertSame( self::$author, $data[0]['id'] );
    824820
    825821        wp_set_current_user( 0 );
    … …  
    839835        wp_set_current_user( self::$user );
    840836
    841         $lolz = $this->factory->user->create(
    842             array(
    843                 'display_name' => 'lolz',
    844                 'role'         => 'author',
    845             )
    846         );
    847 
    848837        $request = new WP_REST_Request( 'GET', '/wp/v2/users' );
    849838        $request->set_param( 'roles', 'ilovesteak,author' );
    … …  
    851840        $data     = $response->get_data();
    852841        $this->assertCount( 1, $data );
    853         $this->assertSame( $lolz, $data[0]['id'] );
     842        $this->assertSame( self::$author, $data[0]['id'] );
    854843
    855844        $request = new WP_REST_Request( 'GET', '/wp/v2/users' );
    … …  
    857846        $response = rest_get_server()->dispatch( $request );
    858847        $data     = $response->get_data();
    859         $this->assertCount( 0, $data );
    860         $this->assertSame( array(), $data );
    861     }
    862 
     848        $this->assertIsArray( $data );
     849        $this->assertEmpty( $data );
     850    }
     851
     852    /**
     853     * @ticket 16841
     854     */
     855    public function test_get_items_capabilities() {
     856        wp_set_current_user( self::$user );
     857
     858        $request = new WP_REST_Request( 'GET', '/wp/v2/users' );
     859        $request->set_param( 'capabilities', 'edit_posts' );
     860        $response = rest_get_server()->dispatch( $request );
     861        $data     = $response->get_data();
     862
     863        $this->assertNotEmpty( $data );
     864        foreach ( $data as $user ) {
     865            $this->assertTrue( user_can( $user['id'], 'edit_posts' ) );
     866        }
     867    }
     868
     869    /**
     870     * @ticket 16841
     871     */
     872    public function test_get_items_capabilities_no_permission_no_user() {
     873        wp_set_current_user( 0 );
     874
     875        $request = new WP_REST_Request( 'GET', '/wp/v2/users' );
     876        $request->set_param( 'capabilities', 'edit_posts' );
     877        $response = rest_get_server()->dispatch( $request );
     878        $this->assertErrorResponse( 'rest_user_cannot_view', $response, 401 );
     879    }
     880
     881    /**
     882     * @ticket 16841
     883     */
     884    public function test_get_items_capabilities_no_permission_editor() {
     885        wp_set_current_user( self::$editor );
     886
     887        $request = new WP_REST_Request( 'GET', '/wp/v2/users' );
     888        $request->set_param( 'capabilities', 'edit_posts' );
     889        $response = rest_get_server()->dispatch( $request );
     890        $this->assertErrorResponse( 'rest_user_cannot_view', $response, 403 );
     891    }
     892
     893    /**
     894     * @ticket 16841
     895     */
     896    public function test_get_items_invalid_capabilities() {
     897        wp_set_current_user( self::$user );
     898
     899        $request = new WP_REST_Request( 'GET', '/wp/v2/users' );
     900        $request->set_param( 'roles', 'ilovesteak,author' );
     901        $response = rest_get_server()->dispatch( $request );
     902        $data     = $response->get_data();
     903        $this->assertCount( 1, $data );
     904        $this->assertSame( self::$author, $data[0]['id'] );
     905
     906        $request = new WP_REST_Request( 'GET', '/wp/v2/users' );
     907        $request->set_param( 'capabilities', 'steakisgood' );
     908        $response = rest_get_server()->dispatch( $request );
     909        $data     = $response->get_data();
     910        $this->assertIsArray( $data );
     911        $this->assertEmpty( $data );
     912    }
     913
     914    /**
     915     * @expectedDeprecated WP_User_Query
     916     */
    863917    public function test_get_items_who_author_query() {
    864918        wp_set_current_user( self::$superadmin );
Note: See TracChangeset for help on using the changeset viewer.