Problem/Motivation

The hook_user_role_*() docs in user.api.php are not consistent with other documentation like hook_node_insert(). @Dave Reid pointed out in #1119158-6: user_role_save() doesn't implement a presave hook that these usually start with "Act on…".

Proposed resolution

Update the docblocks of these hooks.

Remaining tasks

Contributor tasks needed
Task Novice task? Contributor instructions Complete?
Create a patch Yes Instructions No

User interface changes

n/a

API changes

n/a

Original report by @skwashd

Some of the language in user.api.inc is a little clunky and not consistent with others parts of core. This was raised during the review of #1119158: user_role_save() doesn't implement a presave hook.

An example of this is the docs for the hook_user_role_*() functions.

/**
 * Inform other modules that a user role has been added.
 *
...
Support from Acquia helps fund testing for Drupal Acquia logo

Comments

star-szr’s picture

Title: user.api.inc docs need some polish » user.api.php hook summary lines should be more consistent with other entity hooks
Issue summary: View changes
Issue tags: +Novice
Parent issue: » #1119158: user_role_save() doesn't implement a presave hook

Updating the issue summary, after some digging this looks like a good novice documentation issue because the changes proposed are not massive.

er.pushpinderrana’s picture

Assigned: Unassigned » er.pushpinderrana
Status: Active » Needs work
er.pushpinderrana’s picture

Status: Needs work » Needs review
FileSize
1.77 KB

Did changes in user.api.php documentation to make it more consistent like other core functions.

star-szr’s picture

Thanks for taking this on @er.pushpinderrana :)

  1. +++ b/core/modules/user/user.api.php
    @@ -371,11 +371,15 @@ function hook_user_view_alter(array &$build, \Drupal\user\UserInterface $account
    + * Note that when this hook is invoked, the changes have not yet been written to
    + * the database, because a database transaction is still in progress. The
    + * transaction is not finalized until the save operation is entirely completed.
    + *
    

    I don't think this is true for presave, at least not if you compare to hook_node_presave(). I don't think any transaction would be in progress at this point.

  2. +++ b/core/modules/user/user.api.php
    @@ -390,7 +394,7 @@ function hook_user_role_presave($role) {
    - * Inform other modules that a user role has been added.
    + * Act on a user role being inserted or updated.
    

    "updated" doesn't apply to insert operations.

Looks at more of the examples in node.api.php "Respond to" also looks like an acceptable substitution for "Act on" if you wish.

It might be helpful to review #629518: hook_node_insert() and other node hooks have imprecise/misleading descriptions.

er.pushpinderrana’s picture

Status: Needs work » Needs review
FileSize
1.47 KB

Incorporated your suggested changes in this patch. If something missing please suggest.

star-szr’s picture

Status: Needs review » Reviewed & tested by the community

Looks good to me, certainly an improvement. Thanks!

er.pushpinderrana’s picture

Version: 8.x-dev » 7.x-dev
Status: Reviewed & tested by the community » Needs review
FileSize
1.67 KB

Re-rolled #5 patch for D7 too. Please review once.

star-szr’s picture

Version: 7.x-dev » 8.x-dev
Status: Needs review » Reviewed & tested by the community

That's great but we need to get the 8.x patch in first and then backport once the status is "Patch (to be ported)" :)

https://www.drupal.org/contributor-tasks/backport

+++ b/.gitignore
@@ -4,3 +4,4 @@ sites/*/settings*.php
 # Ignore paths that contain user-generated content.
 sites/*/files
 sites/*/private
+/nbproject/private/
\ No newline at end of file

This should be removed from the D7 patch.

er.pushpinderrana’s picture

@Cottser, thankyou for guiding me.

I would surely removed these extra line code from D7 patch and tested manually, once the thread status come to "Patch (to be ported)".

Status: Reviewed & tested by the community » Needs work

The last submitted patch, 7: drupal7-user-role-documentation-1120440-7.patch, failed testing.

er.pushpinderrana’s picture

Version: 8.x-dev » 7.x-dev
Status: Needs work » Needs review
FileSize
1.41 KB

Rerolled patch #7 for D7 and removed unused lines from this patch.

Status: Needs review » Needs work

The last submitted patch, 11: drupal7-user-role-documentation-1120440-11.patch, failed testing.

er.pushpinderrana’s picture

Version: 7.x-dev » 8.x-dev
Status: Needs work » Needs review

@Cottser, please suggest on this how to deal with this situation because D8 patch is still under review and D7 patch is going for automate testing. Not sure, how to avoid/remove D7 patch until D8 patch get fixed.

star-szr’s picture

Status: Needs review » Reviewed & tested by the community

Sure :) This will not get committed to 7.x until it's committed to 8.x. It will not be committed to 8.x unless it is RTBC. So I suggest hiding the 7.x patches and waiting. You can hide patches from the issue summary using the files fieldset below the comment form.

Committers, #5 is the D8 patch here.

alexpott’s picture

Status: Reviewed & tested by the community » Fixed

Committed 310065c and pushed to 8.x. Thanks!

  • alexpott committed 310065c on 8.x
    Issue #1120440 by er.pushpinderrana | skwashd: Fixed user.api.php hook...
star-szr’s picture

Status: Fixed » Patch (to be ported)

Back to D7 for backport :)

er.pushpinderrana’s picture

Version: 8.x-dev » 7.x-dev
Assigned: er.pushpinderrana » Unassigned
FileSize
1.41 KB

Here is patch for D7. Please review.

er.pushpinderrana’s picture

Status: Patch (to be ported) » Needs review
star-szr’s picture

Status: Needs review » Reviewed & tested by the community

Missed the version dropdown, patch looks good! Thanks @er.pushpinderrana.

Status: Reviewed & tested by the community » Needs work

The last submitted patch, 18: drupal7-user-role-documentation-1120440-18.patch, failed testing.

Status: Needs work » Needs review

Status: Needs review » Needs work

The last submitted patch, 18: drupal7-user-role-documentation-1120440-18.patch, failed testing.

Status: Needs work » Needs review
David_Rothstein’s picture

Status: Needs review » Reviewed & tested by the community

Testbot failure.

Status: Reviewed & tested by the community » Needs work

The last submitted patch, 18: drupal7-user-role-documentation-1120440-18.patch, failed testing.

Status: Needs work » Needs review
star-szr’s picture

Status: Needs review » Reviewed & tested by the community

Status: Reviewed & tested by the community » Needs work

The last submitted patch, 18: drupal7-user-role-documentation-1120440-18.patch, failed testing.

Status: Needs work » Needs review
dcam’s picture

Status: Needs review » Reviewed & tested by the community

Status: Reviewed & tested by the community » Needs work

The last submitted patch, 18: drupal7-user-role-documentation-1120440-18.patch, failed testing.

Status: Needs work » Needs review
dcam’s picture

Status: Needs review » Reviewed & tested by the community

Status: Reviewed & tested by the community » Needs work

The last submitted patch, 18: drupal7-user-role-documentation-1120440-18.patch, failed testing.

Status: Needs work » Needs review
dcam’s picture

Status: Needs review » Reviewed & tested by the community

  • David_Rothstein committed ea1c7a9 on 7.x
    Issue #1120440 by er.pushpinderrana | skwashd: Fixed user.api.php hook...
David_Rothstein’s picture

Status: Reviewed & tested by the community » Fixed

Committed to 7.x - thanks!

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.