[wp-trac] [WordPress Trac] #54572: Add a function for updating the existing role instead of removing, then adding one

[WordPress Trac]

#54572: Add a function for updating the existing role instead of removing, then
adding one
-------------------------------------------------+-------------------------
 Reporter:  maksimkuzmin                         |       Owner:
                                                 |  davidbaumwald
     Type:  enhancement                          |      Status:  reopened
 Priority:  normal                               |   Milestone:  6.1
Component:  Role/Capability                      |     Version:
 Severity:  normal                               |  Resolution:
 Keywords:  has-patch has-unit-tests needs-dev-  |     Focuses:
  note                                           |
-------------------------------------------------+-------------------------
Changes (by manfcarlo):

 * status:  closed => reopened
 * resolution:  fixed =>


Comment:

 I feel a little bit silly that I didn't notice earlier, but there already
 exist [https://developer.wordpress.org/reference/classes/wp_roles/add_cap/
 add_cap] and
 [https://developer.wordpress.org/reference/classes/wp_roles/remove_cap/
 remove_cap] methods for updating the capabilities of a role.

 It seems that using the aforementioned methods is the officially supported
 way of updating the capabilities of a role, not the workaround of removing
 and re-adding the role that was described in the ticket description. It
 also probably explains why an update method was missing for so long with
 no request for it to be added.

 Replying to [comment:27 davidbaumwald]:
 > I think adding this will be great for //new// developers

 Confusion about why there are two ways to do the same thing, and which one
 to use, is not great for new developers. There might be a good reason it
 was implemented the way it was.

 If adding or removing multiple capabilities, using the older methods
 causes multiple database queries to achieve what is possible with just
 one. However, it is mentioned in the
 [https://developer.wordpress.org/reference/classes/wp_roles/remove_cap/
 remove_cap] documentation that the method should only be called once, so
 the performance cost is negligible. I think it's also highly questionable
 why a role that is already assigned to users should be re-defined from
 scratch beyond the incremental tweaks that the older methods are suitable
 for.

 I previously did not want to re-open the ticket a third time, for the sake
 of being co-operative, but I think it is justified given that the
 existence of the older methods was previously undiscussed. Sorry for the
 hassle and I would have brought it up earlier if I had noticed.

 My new suggestion is to designate the `update_role` method only for
 updating the display name. The docblock for the `update_role` method could
 indicate that the `add_cap` and `remove_cap` methods are to be used for
 updating the capabilities of a role.

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/54572#comment:29>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform