Change register_page_header_buttons hook to pass a user argument instead of page_perms

docs/reference/hooks.md

@@ -551,7 +551,7 @@ This example will add a simple button to the secondary dropdown menu:
 from wagtail.admin import widgets as wagtailadmin_widgets
 
 @hooks.register('register_page_header_buttons')
-def page_header_buttons(page, page_perms, next_url=None):
+def page_header_buttons(page, user, next_url=None):
     yield wagtailadmin_widgets.Button(
         'A dropdown button',
         '/goes/to/a/url/',
@@ -562,11 +562,15 @@ def page_header_buttons(page, page_perms, next_url=None):
 The arguments passed to the hook are as follows:
 
 -   `page` - the page object to generate the button for
--   `page_perms` - a `PagePermissionTester` object that can be queried to determine the current user's permissions on the given page
+-   `user` - the logged-in user
 -   `next_url` - the URL that the linked action should redirect back to on completion of the action, if the view supports it
 
 The `priority` argument controls the order the buttons are displayed in the dropdown. Buttons are ordered from low to high priority, so a button with `priority=10` will be displayed before a button with `priority=60`.
 
+```{versionchanged} 5.2
+The hook function now receives a `user` argument instead of a `page_perms` argument. To check the user's permissions on the page, use `page.permissions_for_user(user)`.
+```
+
 ## Editor workflow
 
 Hooks for customising the way users are directed through the process of creating page content.

wagtail/admin/templates/wagtailadmin/pages/page_listing_header.html

@@ -11,7 +11,7 @@
     {# Actions divider #}
     <div class="w-w-px w-h-[30px] w-ml-auto sm:w-ml-0 w-bg-border-furniture"></div>
     {# Page actions dropdown #}
-    {% page_header_buttons parent_page page_perms=page_perms %}
+    {% page_header_buttons parent_page user=request.user %}
 {% endblock %}
 {% block actions %}
     {% if not parent_page.is_root %}

wagtail/admin/templates/wagtailadmin/shared/headers/page_edit_header.html

@@ -11,7 +11,7 @@
     {# Actions divider #}
     <div class="w-w-px w-h-[30px] w-ml-auto sm:w-ml-0 w-bg-border-furniture"></div>
     {# Page actions dropdown #}
-    {% page_header_buttons page page_perms=page_perms %}
+    {% page_header_buttons page user=request.user %}
 {% endblock %}
 
 {% block actions %}

wagtail/admin/templatetags/wagtailadmin_tags.py

@@ -505,13 +505,25 @@ def page_listing_buttons(context, page, user):
 @register.inclusion_tag(
     "wagtailadmin/pages/listing/_page_header_buttons.html", takes_context=True
 )
-def page_header_buttons(context, page, page_perms):
+def page_header_buttons(context, page, user):
     next_url = context["request"].path
+    page_perms = page.permissions_for_user(user)
     button_hooks = hooks.get_hooks("register_page_header_buttons")
 
     buttons = []
     for hook in button_hooks:
-        buttons.extend(hook(page, page_perms, next_url))
+        if accepts_kwarg(hook, "user"):
+            buttons.extend(hook(page=page, user=user, next_url=next_url))
+        else:
+            # old-style hook that accepts page_perms instead of user
+            warn(
+                "`register_page_header_buttons` hook functions should accept a `user` argument instead of `page_perms` -"
+                f" {hook.__module__}.{hook.__name__} needs to be updated",
+                category=RemovedInWagtail60Warning,
+            )
+
+            page_perms = page.permissions_for_user(user)
+            buttons.extend(hook(page, page_perms, next_url))
 
     buttons = [b for b in buttons if b.show]
     buttons.sort()

wagtail/admin/tests/test_buttons_hooks.py

@@ -321,12 +321,38 @@ class TestPageListingMoreButtonsHooks(TestButtonsHooks):
 
 
 class TestPageHeaderButtonsHooks(TestButtonsHooks):
-    def test_register_page_header_buttons(self):
+    def test_register_page_header_buttons_old_signature(self):
         def custom_page_header_buttons(page, page_perms, next_url=None):
             yield wagtailadmin_widgets.Button(
                 "Another useless header button", "/custom-url", priority=10
             )
 
+        with hooks.register_temporarily(
+            "register_page_header_buttons", custom_page_header_buttons
+        ), self.assertWarnsMessage(
+            RemovedInWagtail60Warning,
+            "`register_page_header_buttons` hook functions should accept a `user` argument instead of `page_perms`",
+        ):
+            response = self.client.get(
+                reverse("wagtailadmin_pages:edit", args=(self.root_page.id,))
+            )
+
+        self.assertEqual(response.status_code, 200)
+        self.assertTemplateUsed(
+            response, "wagtailadmin/pages/listing/_page_header_buttons.html"
+        )
+
+        self.assertContains(response, "Another useless header button")
+
+    def test_register_page_header_buttons_new_signature(self):
+        def custom_page_header_buttons(page, user, next_url=None):
+            if not isinstance(user, AbstractBaseUser):
+                raise TypeError("expected a user instance")
+
+            yield wagtailadmin_widgets.Button(
+                "Another useless header button", "/custom-url", priority=10
+            )
+
         with hooks.register_temporarily(
             "register_page_header_buttons", custom_page_header_buttons
         ):
@@ -347,13 +373,12 @@ class TestPageHeaderButtonsHooks(TestButtonsHooks):
         """
 
         page = self.root_page
-        page_perms = page.permissions_for_user(self.user)
         base_url = reverse("wagtailadmin_pages:delete", args=[page.id])
 
         next_url = "a/random/url/"
         full_url = base_url + "?" + urlencode({"next": next_url})
 
-        buttons = page_header_buttons(page, page_perms, next_url=next_url)
+        buttons = page_header_buttons(page, self.user, next_url=next_url)
         delete_button = next(button for button in buttons if button.label == "Delete")
 
         self.assertEqual(delete_button.url, full_url)
@@ -366,12 +391,11 @@ class TestPageHeaderButtonsHooks(TestButtonsHooks):
         """
 
         page = self.root_page
-        page_perms = page.permissions_for_user(self.user)
 
         base_url = reverse("wagtailadmin_pages:delete", args=[page.id])
         next_url = reverse("wagtailadmin_explore", args=[page.id])
 
-        buttons = page_header_buttons(page, page_perms, next_url=next_url)
+        buttons = page_header_buttons(page, self.user, next_url=next_url)
 
         delete_button = next(button for button in buttons if button.label == "Delete")
 
@@ -381,7 +405,7 @@ class TestPageHeaderButtonsHooks(TestButtonsHooks):
         base_url = reverse("wagtailadmin_pages:delete", args=[page.id])
         next_url = reverse("wagtailadmin_pages:edit", args=[page.id])
 
-        buttons = page_header_buttons(page, page_perms, next_url=next_url)
+        buttons = page_header_buttons(page, self.user, next_url=next_url)
 
         delete_button = next(button for button in buttons if button.label == "Delete")
 

wagtail/admin/wagtail_hooks.py

@@ -442,7 +442,8 @@ def page_listing_more_buttons(page, user, next_url=None):
 
 
 @hooks.register("register_page_header_buttons")
-def page_header_buttons(page, page_perms, next_url=None):
+def page_header_buttons(page, user, next_url=None):
+    page_perms = page.permissions_for_user(user)
     yield PageListingEditButton(
         page=page,
         page_perms=page_perms,

wagtail/contrib/simple_translation/wagtail_hooks.py

@@ -64,10 +64,8 @@ def page_listing_more_buttons(page, user, next_url=None):
 
 
 @hooks.register("register_page_header_buttons")
-def page_header_buttons(page, page_perms, next_url=None):
-    if not page.is_root() and page_perms.user.has_perm(
-        "simple_translation.submit_translation"
-    ):
+def page_header_buttons(page, user, next_url=None):
+    if not page.is_root() and user.has_perm("simple_translation.submit_translation"):
         # If there's at least one locale that we haven't translated into yet,
         # show "Translate this page" button
         has_locale_to_translate_to = Locale.objects.exclude(