From 2983f54144a91ec4483d06d5452bc06164fcc738 Mon Sep 17 00:00:00 2001 From: Duncan McClean Date: Mon, 20 Jul 2026 16:36:02 +0100 Subject: [PATCH 1/3] document `->hiddenBy()` option when registering permissions --- .../collections/pages/custom-permissions.md | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/content/collections/pages/custom-permissions.md b/content/collections/pages/custom-permissions.md index 8e2e04b7c..17af5e14b 100644 --- a/content/collections/pages/custom-permissions.md +++ b/content/collections/pages/custom-permissions.md @@ -72,6 +72,29 @@ Permission::register('view blog entries', function ($permission) { The second argument of the `register` method accepts a closure that allows you to modify the permission. +## Hiding permissions covered by a broader one + +Sometimes a broader permission already grants everything a more specific one does — for example, `configure asset containers` already grants every ability `view {container} assets` guards. Rather than show redundant checkboxes for both, you can hide a permission behind one or more others with `hiddenBy`: + +``` php +Permission::register('view {container} assets', function ($permission) { + $permission->hiddenBy('configure asset containers'); +}); +``` + +When any of the hiding permissions are checked in the roles UI, this permission — and its children — disappear. Unchecking brings them back, with their checked state intact. + +You may pass an array to hide a permission behind more than one: + +``` php +Permission::register('edit {form} form', function ($permission) { + $permission->hiddenBy(['configure forms', 'edit forms']); +}); +``` + +:::tip +`hiddenBy` is purely visual. It doesn't grant anything, and it doesn't establish a hierarchy between permissions the way `children` does — it just avoids showing checkboxes that a broader permission already covers. +::: ## Policy based permissions From da87cb0ed9a7ef34d4f45058d9484a31ca409760 Mon Sep 17 00:00:00 2001 From: Duncan McClean Date: Mon, 20 Jul 2026 16:40:37 +0100 Subject: [PATCH 2/3] tweak --- content/collections/pages/custom-permissions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/collections/pages/custom-permissions.md b/content/collections/pages/custom-permissions.md index 17af5e14b..2a9da7893 100644 --- a/content/collections/pages/custom-permissions.md +++ b/content/collections/pages/custom-permissions.md @@ -93,7 +93,7 @@ Permission::register('edit {form} form', function ($permission) { ``` :::tip -`hiddenBy` is purely visual. It doesn't grant anything, and it doesn't establish a hierarchy between permissions the way `children` does — it just avoids showing checkboxes that a broader permission already covers. +`hiddenBy` only affects the roles UI. Unlike `children`, it doesn't grant anything or establish a hierarchy — it just keeps the checkbox out of sight once a broader permission already covers it. ::: ## Policy based permissions From 52d99e7832c1ce1d8c8432f6420866af27bd1df8 Mon Sep 17 00:00:00 2001 From: Duncan McClean Date: Mon, 20 Jul 2026 16:42:53 +0100 Subject: [PATCH 3/3] tweak --- content/collections/pages/custom-permissions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/collections/pages/custom-permissions.md b/content/collections/pages/custom-permissions.md index 2a9da7893..4b9212d53 100644 --- a/content/collections/pages/custom-permissions.md +++ b/content/collections/pages/custom-permissions.md @@ -93,7 +93,7 @@ Permission::register('edit {form} form', function ($permission) { ``` :::tip -`hiddenBy` only affects the roles UI. Unlike `children`, it doesn't grant anything or establish a hierarchy — it just keeps the checkbox out of sight once a broader permission already covers it. +`hiddenBy` only affects the UI. It doesn't grant any permissions or establish a hierarchy — it simply keeps the checkbox out of sight when a broader permission already covers it. ::: ## Policy based permissions