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.