fix(admin): add custom capability option for settings pages

[faisalahammad]

Description

Settings pods now expose a per-pod capability option. The admin menu stays gated on pods, pods_content, or pods_edit_{name} by default. Picking "Custom" adds an editable cap name (e.g. manage_options) that grants access in the same OR-list, so existing admins keep their access and pods_is_admin filter still works.

Related GitHub issue(s)

Fixes #7245

Testing instructions

1. Go to Pods Admin.
2. Open an existing settings pod or create a new one (name site_settings for the test below).
3. Open the Admin UI tab.
4. New field "User Capability" — choose "Custom Capability".
5. In the new "Custom User Capability" input, type manage_options (or any cap your test user has).
6. Save pod.
7. As a user with manage_options but none of the Pods caps: the settings page menu item shows.
8. As a user without manage_options or any Pods cap: the menu item stays hidden.
9. Set "User Capability" back to "Default", save: original three-cap check restored.

Screenshots / screencast

n/a

Changelog text for these changes

• Enhancement: Settings pods now support specifying a custom capability to gate access from the admin menu. Custom Settings Pages should support specifying a capability for access #7245 (@faisalahammad)

PR checklist

• I have tested my own code to confirm it works as I intended.
• My code follows the WordPress Coding Standards.
• My code follows the WordPress Inline Documentation Standards.
• My code includes automated tests for PHP and/or JS (if applicable).

Screenshot

[what-the-diff]

PR Summary

• Enhanced admin capabilities management
  In our system, we've redesigned the way administrators can manage user capabilities (the abilities and accesses each user has in the system). This new design includes a new flexible and dynamic method that adjusts user capabilities based on their specific configurations.

• Updated method for admin capabilities
  We've improved a key system function that ensures these dynamic capabilities are properly attached to users when they're applicable. This allows our system to provide better, more personalized functionality to each user based on their role and permissions.

• Extended configuration options
  We've expanded the set of options available for administrators to configure our system. Notably, we've added the ability to choose between default and custom capabilities for accessing settings pages. This includes a new field to specify the precise access required, along with a user-friendly label and help text to guide administrators in these settings. This change aims to further streamline and personalize the system to suit your enterprise's unique needs.

[faisalahammad]

AI disclosure: this PR was written with Claude Opus 5 assistance, reviewed and tested by me.

[faisalahammad]

Review: the capability is only enforced on menu registration

No privilege escalation on the default path — the custom cap is only appended when capability_type === 'custom' and the value is non-empty, so the existing three-cap check at classes/PodsAdmin.php:484 is preserved for everyone else. That part is sound.

Two gaps before this delivers what the issue asks for.

1. The real access check is untouched

The custom cap is only consulted when registering the menu. The actual capability resolution for settings objects lives in includes/access.php:535-538, which still hardcodes:

$capabilities['read'] = 'manage_options';
$capabilities['edit'] = 'pods_edit_' . $info['object_name'];

PodsAdmin::admin_content_settings() (classes/PodsAdmin.php:760) performs no capability check of its own — it relies entirely on menu registration. So a user granted only the custom cap gets the menu item, but the path that governs actual read/edit access never learns about it.

Worth mirroring the custom cap into that access.php branch so both agree.

2. Unsanitized option

admin_capabilities() injects the raw user-supplied string, where the neighbouring post-type branch uses pods_v_sanitized() (classes/PodsAdmin.php:3995). Not an escalation vector — that method is only hooked to members_get_capabilities — but it's inconsistent with the surrounding code. Suggest pods_v_sanitized( 'capability_type_custom', ... ) in both places.

Minor

The PR checklist ticks "includes automated tests", but neither changed file is a test. A wpunit test asserting that a user with only the custom cap can reach the settings page (and that one without it cannot) would cover both points above.

Disclosure: this review was produced with AI assistance and verified against the branch code before posting.