Zend Permissions RBAC

https://github.com/zendframework/zend-permissions-rbac
Admin
Provides role-based access control (RBAC) permissions management for PHP applications.
Tokens:4,598
Snippets:59
Trust Score:8.6
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install Dependencies

Source: https://github.com/zendframework/zend-permissions-rbac/blob/master/CONTRIBUTING.md

Install project dependencies using Composer. Ensure you have Composer installed globally or download the composer.phar.

```console
$ curl -sS https://getcomposer.org/installer | php --
$ ./composer.phar install
```

--------------------------------

### Example dynamic assertion implementation

Source: https://github.com/zendframework/zend-permissions-rbac/blob/master/doc/book/migration/to-v3-0.md

Demonstrates how to implement dynamic assertions using the new $role and $permission parameters in the assert() method to conditionally deny permissions.

```php
public function assert(Rbac $rbac, RoleInterface $role, string $permission) : bool
{
    return ! ($permission === 'foo' && $role->getName() === 'admin');
}
```

--------------------------------

### Check Coding Standards

Source: https://github.com/zendframework/zend-permissions-rbac/blob/master/CONTRIBUTING.md

Run PHP CodeSniffer to check for coding standard violations. This is installed via Composer.

```console
$ composer cs-check
```

--------------------------------

### Run Tests

Source: https://github.com/zendframework/zend-permissions-rbac/blob/master/CONTRIBUTING.md

Execute the project's tests using PHPUnit with the provided configuration.

```console
$ ./vendor/bin/phpunit
```

--------------------------------

### Assign and Check Permissions

Source: https://github.com/zendframework/zend-permissions-rbac/blob/master/doc/book/examples.md

Demonstrates how to assign permissions to roles and check if a role is granted a specific permission.

```php
use Zend\Permissions\Rbac\Rbac;
use Zend\Permissions\Rbac\Role;

$rbac = new Rbac();
$foo  = new Role('foo');
$foo->addPermission('bar');

var_dump($foo->hasPermission('bar')); // true

$rbac->addRole($foo);
$rbac->isGranted('foo', 'bar'); // true
$rbac->isGranted('foo', 'baz'); // false

$rbac->getRole('foo')->addPermission('baz');
$rbac->isGranted('foo', 'baz'); // true
```

--------------------------------

### Handle Roles with Children

Source: https://github.com/zendframework/zend-permissions-rbac/blob/master/doc/book/examples.md

Illustrates how to establish parent-child relationships between roles, both by direct instantiation and through the Rbac container.

```php
use Zend\Permissions\Rbac\Rbac;
use Zend\Permissions\Rbac\Role;

$rbac = new Rbac();
$foo  = new Role('foo');
$bar  = new Role('bar');

// 1 - Add a role with child role directly with instantiated classes.
$foo->addChild($bar);
$rbac->addRole($foo);

// 2 - Same as one, only via rbac container.
$rbac->addRole('boo', 'baz'); // baz is a parent of boo
$rbac->addRole('baz', ['out', 'of', 'roles']); // create several parents of baz
```

--------------------------------

### Extend and Add Roles via Instantiation

Source: https://github.com/zendframework/zend-permissions-rbac/blob/master/doc/book/examples.md

Demonstrates how to extend the base Role class and add custom roles to the Rbac container.

```php
use Zend\Permissions\Rbac\Rbac;
use Zend\Permissions\Rbac\AbstractRole;

class MyRole extends AbstractRole
{
    // .. implementation
}

// Creating roles manually
$foo  = new MyRole('foo');

$rbac = new Rbac();
$rbac->addRole($foo);

var_dump($rbac->hasRole('foo')); // true
```

--------------------------------

### Clone Canonical Repository

Source: https://github.com/zendframework/zend-permissions-rbac/blob/master/CONTRIBUTING.md

Clone the main zendframework/zend-permissions-rbac repository locally to begin contributing.

```console
$ git clone git://github.com:zendframework/zend-permissions-rbac.git
$ cd zend-permissions-rbac
```

--------------------------------

### Clone Repository

Source: https://github.com/zendframework/zend-permissions-rbac/blob/master/CONTRIBUTING.md

Clone the zend-permissions-rbac repository to your local machine.

```console
$ git clone git@github.com:zendframework/zend-permissions-rbac.git
$ cd
```

--------------------------------

### Dynamic Assertions with Closure

Source: https://github.com/zendframework/zend-permissions-rbac/blob/master/doc/book/examples.md

Demonstrates performing dynamic permission checks using a closure as an assertion.

```php
// assume same variables from previous example

$assertion = function($rbac) use ($user, $news) {
    return ($user->getId() === $news->getUserId());
};

// true
if ($rbac->isGranted($user->getRole(), 'edit.article', $assertion)) {
    // edits his own article
}
```

--------------------------------

### Dynamic Assertions with Class Implementation

Source: https://github.com/zendframework/zend-permissions-rbac/blob/master/doc/book/examples.md

Shows how to use a class implementing AssertionInterface to perform dynamic permission checks based on context.

```php
use App\Model\Article;
use Zend\Permissions\Rbac\AssertionInterface;
use Zend\Permissions\Rbac\Rbac;

class AssertUserRoleMatches implements AssertionInterface
{
    protected $userId;
    protected $article;

    public function __construct(string $userId)
    {
        $this->userId = $userId;
    }

    public function setArticle(Article $article)
    {
        $this->article = $article;
    }

    public function assert(Rbac $rbac, RoleInterface $role = null, string $permission = null)
    {
        if (! $this->article) {
            return false;
        }
        return ($this->userId === $this->article->getUserId());
    }
}

// User is assigned the foo role with id 5
// News article belongs to userId 5
// Jazz article belongs to userId 6

$rbac = new Rbac();
$user = $mySessionObject->getUser();
$news = $articleService->getArticle(5);
$jazz = $articleService->getArticle(6);

$rbac->addRole($user->getRole());
$rbac->getRole($user->getRole())->addPermission('edit.article');

$assertion = new AssertUserIdMatches($user->getId());
$assertion->setArticle($news);

// true always - bad!
if ($rbac->isGranted($user->getRole(), 'edit.article')) {
    // hacks another user's article
}

// true for user id 5, because he belongs to write group and user id matches
if ($rbac->isGranted($user->getRole(), 'edit.article', $assertion)) {
    // edits his own article
}

$assertion->setArticle($jazz);

// false for user id 5
if ($rbac->isGranted($user->getRole(), 'edit.article', $assertion)) {
    // can not edit another user's article
}
```

--------------------------------

### Create and Switch to a New Branch

Source: https://github.com/zendframework/zend-permissions-rbac/blob/master/CONTRIBUTING.md

Use this command to create a new local branch for a specific feature or bugfix, based on your current branch (e.g., master or develop).

```git
$ git checkout -b hotfix/9295
Switched to a new branch 'hotfix/9295'
```

--------------------------------

### Zend\Permissions\Rbac\Rbac Methods

Source: https://github.com/zendframework/zend-permissions-rbac/blob/master/doc/book/methods.md

The main entry point for interacting with the RBAC system to add roles and query for permissions.

```APIDOC
## `Zend\Permissions\Rbac\Rbac`

### Description
The main entry point for interacting with the RBAC system to add roles and query for permissions.

### Methods

- `addRole(string|RoleInterface $child, array|RoleInterface $parents = null): void`
  - Description: Add a role to the RBAC. If `$parents` is non-null, the `$child` is also added to any parents provided.

- `getRole(string $role): RoleInterface`
  - Description: Get the role specified by name, raising an exception if not found.

- `getRoles(): RoleInterface[]`
  - Description: Retrieve all the roles.

- `hasRole(string|RoleInterface $role): bool`
  - Description: Recursively queries the RBAC for the given role, returning `true` if found, `false` otherwise.

- `getCreateMissingRoles(): bool`
  - Description: Retrieve the flag that determines whether or not `$parent` roles are added automatically if not present when calling `addRole()`.

- `setCreateMissingRoles(bool $flag): void`
  - Description: Set the flag that determines whether or not `$parent` roles are added automatically if not present when calling `addRole()`.

- `isGranted(string|RoleInterface $role, string $permission, $assert = null): bool`
  - Description: Determine if the role has the given permission. If `$assert` is provided and either an `AssertInterface` instance or callable, it will be queried before checking against the given role.
```

--------------------------------

### Commit Changes

Source: https://github.com/zendframework/zend-permissions-rbac/blob/master/CONTRIBUTING.md

Stage and commit your work. You will be prompted to write a log message.

```git
$ git commit
```

--------------------------------

### Add Roles Directly to Rbac

Source: https://github.com/zendframework/zend-permissions-rbac/blob/master/doc/book/examples.md

Shows how to add roles directly to the Rbac container using the default Role class.

```php
use Zend\Permissions\Rbac\Rbac;

$rbac = new Rbac();
$rbac->addRole('foo');

var_dump($rbac->hasRole('foo')); // true
```

--------------------------------

### Add Fork Remote

Source: https://github.com/zendframework/zend-permissions-rbac/blob/master/CONTRIBUTING.md

Add a remote pointing to your personal GitHub fork. Replace {username} with your GitHub username.

```console
$ git remote add {username} git@github.com:{username}/zend-permissions-rbac.git
$ git fetch {username}
```

--------------------------------

### Role::addParent() method

Source: https://github.com/zendframework/zend-permissions-rbac/blob/master/CHANGELOG.md

This method was added to support multiple parent roles.

```php
addParent($parent)
```

--------------------------------

### Push Local Branch to Remote

Source: https://github.com/zendframework/zend-permissions-rbac/blob/master/CONTRIBUTING.md

Push your newly created local branch to your remote repository. Replace {username} with your GitHub username.

```git
$ git push {username} hotfix/9295:hotfix/9295
Counting objects: 38, done.
Delta compression using up to 2 threads.
Compression objects: 100% (18/18), done.
Writing objects: 100% (20/20), 8.19KiB, done.
Total 20 (delta 12), reused 0 (delta 0)
To ssh://git@github.com/{username}/zend-permissions-rbac.git
   b5583aa..4f51698  HEAD -> master
```

--------------------------------

### AssertionInterface assert() method signature (v3.0)

Source: https://github.com/zendframework/zend-permissions-rbac/blob/master/doc/book/migration/to-v3-0.md

The assert() method in AssertionInterface now includes $role and $permission parameters for dynamic assertions. Update your implementations to match this new signature.

```php
namespace Zend\Permissions\Rbac;

public function assert(
    Rbac $rbac,
    RoleInterface $role,
    string $permission
) : bool
```

--------------------------------

### Role::getParent() returning multiple roles

Source: https://github.com/zendframework/zend-permissions-rbac/blob/master/CHANGELOG.md

The getParent() method was updated to support multiple parent roles and can now return an array of roles.

```php
getParent() now can also return an array of roles.
```

--------------------------------

### Role::getPermissions() with children parameter

Source: https://github.com/zendframework/zend-permissions-rbac/blob/master/CHANGELOG.md

This method retrieves all permissions for a role, optionally including permissions from child roles.

```php
Role::getPermissions(bool $children = true)
```

--------------------------------

### Update Local Repository

Source: https://github.com/zendframework/zend-permissions-rbac/blob/master/CONTRIBUTING.md

Update your local master branch with the latest changes from the canonical ZF repository. Optionally, push these changes to your remote fork.

```console
$ git checkout master
$ git fetch origin
$ git rebase origin/master
# OPTIONALLY, to keep your remote up-to-date -
$ git push {username} master:master
```

--------------------------------

### Zend\Permissions\Rbac\Role Methods

Source: https://github.com/zendframework/zend-permissions-rbac/blob/master/doc/book/methods.md

Provides the base functionality for Role objects, including name management, permission handling, and parent/child role relationships.

```APIDOC
## `Zend\Permissions\Rbac\Role`

### Description
Provides the base functionality for Role objects, including name management, permission handling, and parent/child role relationships.

### Methods

- `__construct(string $name): void`
  - Description: Create a new instance with the provided name.

- `getName(): string`
  - Description: Retrieve the name assigned to this role.

- `addPermission(string $name): void`
  - Description: Add a permission for the current role.

- `hasPermission(string $name): bool`
  - Description: Does the role have the given permission?

- `getPermissions(bool $children = true): array`
  - Description: Retrieve all permissions, including child permissions if `$children` is true.

- `addChild(RoleInterface $child): Role`
  - Description: Add a child role to the current instance.

- `getChildren(): RoleInterface[]`
  - Description: Get all child roles.

- `addParent(RoleInterface $parent): Role`
  - Description: Add a parent role to the current instance.

- `getParents(): RoleInterface[]`
  - Description: Get all parent roles.
```

--------------------------------

### Assertion Interface Signature Update

Source: https://github.com/zendframework/zend-permissions-rbac/blob/master/CHANGELOG.md

The AssertionInterface's assert() method signature was updated to include two new parameters and a return type hint.

```php
public function assert(
    Rbac $rbac,
    RoleInterface $role,
    string $permission
) : bool

```

--------------------------------

### Role::addChild() and Role::addParent() circular reference check

Source: https://github.com/zendframework/zend-permissions-rbac/blob/master/CHANGELOG.md

These methods now include checks to prevent circular references in the role hierarchy.

```php
Role::addChild(RoleInterface $child)
```

```php
Role::addParent(RoleInterface $parent)
```

--------------------------------

### Rbac::getRoles() method

Source: https://github.com/zendframework/zend-permissions-rbac/blob/master/CHANGELOG.md

This method returns all roles registered with the Rbac instance as a flat array.

```php
Rbac::getRoles()
```

--------------------------------

### Zend\Permissions\Rbac\AssertionInterface

Source: https://github.com/zendframework/zend-permissions-rbac/blob/master/doc/book/methods.md

Defines the interface for custom assertions that can be provided to Rbac::isGranted() for more granular permission checks.

```APIDOC
## `Zend\Permissions\Rbac\AssertionInterface`

### Description
Defines the interface for custom assertions that can be provided to Rbac::isGranted() for more granular permission checks. Such assertions are provided the `Rbac` instance on invocation, along with the role and permission being tested against.

### Methods

- `assert(Rbac $rbac, RoleInterface $role, string $permission): bool`
  - Description: Given an RBAC, a role, and a permission, determine if permission is granted.
```

--------------------------------

### Fix Coding Standards

Source: https://github.com/zendframework/zend-permissions-rbac/blob/master/CONTRIBUTING.md

Automatically fix most coding standard violations using PHP CodeSniffer's beautifier tool. Remember to re-run tests and commit changes after fixing.

```console
$ composer cs-fix
```

--------------------------------

### Delete Local Branch

Source: https://github.com/zendframework/zend-permissions-rbac/blob/master/CONTRIBUTING.md

After your changes have been accepted into the master repository, you can clean up your local branches using this command. Replace <branchname> with the name of the branch you wish to delete.

```git
$ git branch -d <branchname>
```

--------------------------------

### Remove Remote Branch

Source: https://github.com/zendframework/zend-permissions-rbac/blob/master/CONTRIBUTING.md

Once your changes are merged and accepted, you can remove the corresponding branch from your remote repository. Replace {username} and <branchname> accordingly.

```git
$ git push {username} :<branchname>
```
Tokens:
Raw