feat: Support hierarchical permissions in method

[bgeneto]

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 (This functionality would need to be documented in the User Guide. I've included a note below on what needs to be added.)
• 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.

[jozefrebjak]

@bgeneto

Hi,

nice PR, I'm currently using something similar. If I understand correctly

For example permissions:

    public array $permissions = [
        'crm.customer.list'           => 'Can access the CRM customer list',
        'crm.customer.show'           => 'Can access the CRM customer',
        'crm.customer.edit'           => 'Can edit a CRM customer',
        'crm.customer.create'         => 'Can create a new CRM customer',
        'crm.customer.delete'         => 'Can delete a CRM customer',
    ];

In matrix then I don't need to write 5 rows in array like:

    public array $matrix = [
        'crm' => [
            'crm.access',
            'crm.customer.list',
            'crm.customer.show',
            'crm.customer.create',
            'crm.customer.edit',
            'crm.customer.delete',
        ],
    ];

but just 1 for crm.customer.* permissions like:

    public array $matrix = [
        'crm' => [
            'crm.access',
            'crm.customer.*',
        ],
    ];

It will work also deeper like for permissions like :

            'crm.service.note.list',
            'crm.service.note.show',
            'crm.service.note.edit',
            'crm.service.note.create',
            'crm.service.note.delete',

to be only:

            'crm.service.note.*,