feat: Support hierarchical permissions in method

[christianberkman]

This is a reboot of #1253 by @bgeneto. I have copied his changes and applied them to the most recent develop branch. I did run PHPStan and Rector which did not return errors on the changed files.

Description

This pull request enhances the can() method in CodeIgniter Shield to support hierarchical permissions, allowing for more granular control over user access. Previously, Shield only supported single-level permissions (e.g., users.create), see #1229 This change enables checking permissions with multiple levels, like admin.users.crud.create, using wildcard matching at each level.

The core change involves modifying the can() method to generate a series of wildcard checks based on the input permission string. It now iteratively checks for all possible parent levels. For example, for admin.users.create, it will check for admin.users.create, admin.users.*, and admin.*.

A new test case, testCanNestedPerms, has been added to verify the correct behavior of the hierarchical permission checks, including various positive and negative scenarios.

This improvement provides greater flexibility in defining and managing permissions within applications built with Shield. It allows for a more natural and organized permission structure, reflecting the hierarchical nature of many application features.

Checklist:

• Securely signed commits
• Component(s) with PHPDoc blocks, only if necessary or adds value (No new PHPDoc blocks were necessary as the existing documentation sufficiently covers the functionality. The method signature remains unchanged.)
• Unit testing, with >80% coverage (New test case testCanNestedPerms added to specifically cover the hierarchical permission logic.)
• User guide updated (changed authorization.md file)
• Conforms to style guide

User Guide Updates (Required):

The following section needs to be added/updated in the User Guide (likely within the "Authorization" or "Permissions" section):

Hierarchical Permissions

Shield now supports hierarchical permissions, allowing you to define permissions with multiple levels separated by dots (.). This enables a more granular and organized approach to authorization.

You can use the wildcard character (*) at any level to represent all permissions within that level.

Example:

If a group has the permission users.manage.*, it will have access to:

* `users.manage.create`

* `users.manage.edit`

* `users.manage.delete`

* `users.manage.anything.else`

However, it will not have access to:

* `users.view`

* `users.anything.else`

The can() method will automatically check all parent levels when evaluating a permission.

Note: This update significantly improves the flexibility of the authorization system. Be sure to review your existing permissions and consider how you can leverage hierarchical permissions to simplify and improve your authorization logic.

[michalsn]

Please rebase to resolve the errors, as they are now fixed in the develop branch.

Tests are still needed for Authorizable::can() with nested permissions (user-in-group via the matrix).

It would be nice to extract the duplicated wildcard logic into a shared method, but I'm not sure where to place it.

[neznaika0]

Are you worried about type errors? Write a test for her. Throw an exception if it's dangerous.

[christianberkman]

@michalsn could you confirm I did the rebase correctly? Git (online) is still saying my branch is 1 commit behind on shield/develop but it looks to me the rebase did include that commit? /not-sure

[michalsn]

@christianberkman It looks like your branch includes a commit that has already been merged into develop, so it's now appearing in the PR history.

You can clean this up by rebasing your branch onto the latest develop and dropping the already-merged commit.

Try:

git fetch origin
git rebase -i origin/develop

In the interactive editor, keep your feature commit and change the other one to drop.

Then force-push the updated branch:

git push --force-with-lease

That should leave the PR with only the initial commit.

[christianberkman]

@michalsn Thank you for your patience and guidance. I'll add to the Authorizable::can() test hopefully soon.

[bgeneto]

I sincerely hope we can successfully merge this PR one day 🤭.....
I’ve been relying on this feature (with success) across all my projects for quite some time.

[michalsn]

I see two problems:

First one
User-level permissions don't support wildcard matching. Currently, Authorizable::can() handles wildcards only when checking group-level permissions (the matrix). For user-level permissions (added via addPermission()), it only does an exact in_array() check. This means if a user has a direct permission forum.posts.*, calling $user->can('forum.posts.create') will return false.

This creates an inconsistency - wildcards work at the group level but not at the user level. The wildcard hierarchy logic should also be applied when checking $this->permissionsCache, not just the matrix.

Second one
The new AuthorizableTest tests don't cover the actual feature. The two new tests (testCanNestedPerms and testCanMultipleNestedPerms) use addPermission() to add exact permissions like forum.posts.create, then check for that same exact permission. This only tests exact string matching, which already worked before this PR.

What's missing is a test that verifies the new hierarchical wildcard logic works through the full Authorizable::can() flow. For example: add forum.posts.* to a group in the matrix, put the user in that group, then assert that $user->can('forum.posts.create') returns true. That would actually test the new code path introduced by this PR.