PHPackages                             metarush/perm - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Authentication & Authorization](/categories/authentication)
4. /
5. metarush/perm

ActiveLibrary[Authentication & Authorization](/categories/authentication)

metarush/perm
=============

Role-based access control (RBAC) with custom rules (like ABAC)

v3.0.3(2y ago)17MITPHPPHP >=7.4CI failing

Since Jun 3Pushed 2y ago1 watchersCompare

[ Source](https://github.com/metarush/perm)[ Packagist](https://packagist.org/packages/metarush/perm)[ RSS](/packages/metarush-perm/feed)WikiDiscussions master Synced 1w ago

READMEChangelog (4)Dependencies (5)Versions (8)Used By (0)

metarush/perm
=============

[](#metarushperm)

`Perm` allows you to implement role-based access control (RBAC) functionality in your app with optional custom rules (like ABAC).

Install
-------

[](#install)

Install via composer as `metarush/perm`

Usage
-----

[](#usage)

`Perm` expects you to provide the following arrays:

- **$roleRanks**: hierarchy of roles
- **$roleResources**: list of resources roles has access to
- **$resourceRestrictions**: list of restrictions resources have that must validate before access is granted

---

`array` **$roleRanks**

An array where keys represent roleIds while the values represent their hierarchy. Example:

```
$roleRanks = [
    1 => 1,
    2 => 2,
    3 => 3
]
```

Keys `1`,`2`,`3` represent roleIds in your app. This could mean that `1` represents an admin, `2` a moderator, `3` a staff.

Values `1`,`2`,`3` represent their hierarchy. **Lower value means a higher rank**.

Note: Resources of a lower role are inherited by higher roles. E.g., Resources of a role with rank `3` are inherited by roles with a rank `2` and `1`.

---

`array` **$roleResources**

An array where keys represent roleIds while values represent an array of resourceIds the roleId has access to. Example:

```
$roleResources = [
    1 => ['1','2'],
    2 => ['3','4'],
    3 => ['5','6']
];
```

Keys `1`,`2`,`3` represent roleIds in your app. This could mean that `1` represents an admin, `2` a moderator, `3` a staff.

Values `['1','2']`, `['3','4']`, `['5','6']` represent resourceIds in your app. This could mean that `1` represents "create user", `2` "edit user", `3` "create post", and so on.

You may notice that the values are strings. This is so you could literally use strings like 'createUser' as it can also act as identifiers. Doing this, you may skip explicitly creating a list of numerical resourceIds, as long as your app can handle it.

Alternative example:

```
$roleResources = [
    1 => ['createUser', 'editUser'],
    2 => ['createPost','editPost'],
    3 => ['readPost', 'createComment']
];
```

`Perm` does not care how you name your roles or resources.

---

`array` **$resourceRestrictions**

An array where keys represent resourceIds while values represent an array of restrictions that are allowed. Restrictions in `Perm` are represented by the following public constants:

`Perm::RESTRICTION_PERMISSION`

Allow if the role has an explicit permission. E.g., "moderator" role has "create user" permission.

`Perm::RESTRICTION_CUSTOM_RULE`

Allow if the custom rule is met

`Perm::RESTRICTION_OWNER`

Allow if the requesting user is the owner of the resource

`Perm::RESTRICTION_CUSTOM_RULE_AND_OWNER`

Allow if the custom rule is met **and** the requesting user is the owner of the resource

`Perm::RESTRICTION_PERMISSION_AND_CUSTOM`

Allow if the role has explicit permission **and** if the custom rule is met

Example:

```
$resourceRestrictions = [
    '1' => [
        Perm::RESTRICTION_PERMISSION
    ],
    '2' => [
        Perm::RESTRICTION_PERMISSION,
        Perm::RESTRICTION_OWNER
    ],
    '3' => [
        Perm::RESTRICTION_CUSTOM_RULE
    ],
    '4' => [
        Perm::RESTRICTION_CUSTOM_RULE_AND_OWNER
    ]
    '5' => [
        Perm::RESTRICTION_PERMISSION_AND_CUSTOM_RULE
    ]
];
```

Keys `1`,`2`,`3`,`4`, `5` represent resourceIds in your app. This could mean `1` represents "create user", `2` "edit post", `3` "delete post", `4` "delete comment", `5` "delete user".

Values represent their restrictions that `Perm` understands. This is how `Perm` will interpret the abve example:

- resourceId `1` or "create user" resource, is allowed if the role of the requesting user has an explict "create user" permission.
- resourceId `2` or "edit post" resource, is allowed if the role of the requesting user has an explict "edit post" permission, **or**, if the requesting user is the owner of the resource
- resourceId `3` or "delete post" resource, is allowed if its custom rule is met. E.g., any rule you set like "post can be deleted if x". The rule is customizable in your own code as long as it returns a boolean value.
- resourceId `4` or "delete comment" resource, is allowed if its custom rule is met **and** if the requesting user is the owner of the resource.
- resourceId `5` or "delete user" resource, is allowed if the role has explicit permission **and** if its custom rule is met

As you can see in resourceId `2`, you can combine restrictions as you wish.

**When using combined restrictions, only one restriction that validates is required to grant access.** E.g., In resourceId `2`, access is granted if the user has explicit permission for resourceId `2` **or** if its custom rule validates.

---

### Optional custom classes

[](#optional-custom-classes)

`PermissionInterface` **$ownerFinder**

This custom class that you create will be used as the owner finder for a given resource.

Required by:

- `Perm::RESTRICTION_OWNER`
- `Perm::RESTRICTION_CUSTOM_RULE_AND_OWNER`

Use the `->setOwnerFinderFactoryFqn($ownerFinderFactoryFqn)` method in the builder to apply this custom class through a factory class that you will also create.

`PermissionInterface` **$customRules**

This custom class that you create will be used as the custom rule handler for a given resource.

Required by:

- `Perm::RESTRICTION_CUSTOM_RULE`
- `Perm::RESTRICTION_CUSTOM_RULE_AND_OWNER`
- `Perm::RESTRICTION_PERMISSION_AND_CUSTOM_RULE`

Use the `->setCustomRulesFactoryFqn($customRulesFactoryFqn)` method in the builder to apply this custom class through a factory class that you will also create.

To sum it up, if you're going to create an owner finder class then you also need to create a factory class that instantiates and returns your owner finder class. Likewise, if you're going to create a custom rules class, create a factory class for it too.

For an example on how to implement these custom classes, see the `tests/unit/Samples` folder.

---

Init the library
----------------

[](#init-the-library)

In your middleware, controller, or top of your app:

```
use MetaRush\Perm;

$perm = (new Perm\Builder)
    ->setRoleRanks($roleRanks)
    ->setRoleResources($roleResources)
    ->setResourceRestrictions($resourceRestrictions)
    ->setOwnerFinderFactoryFqn(Perm\Samples\MyOwnerFinderFactory::class) // optional
    ->setCustomRulesFactoryFqn(Perm\Samples\MyCustomRulesFactory::class) // optional
    ->build();
```

Create a `Request` object

```
$userId = 5; // userId of the requesting user
$roleId = 3; // roleId of $userId e.g., "staff"
$resourceId = 'addUser'; // resourceId of the requested resource
$serverRequest = $psr7serverRequest; // optional PSR-7 ServerRequestInterface object
$request = new Perm\Request($userId, $roleId, $resourceId, $serverRequest);
```

The above values are arbitrary data depending to your app. The optional `$serverRequest` parameter can be used in your custom rules.

Pass the `Request` object to `Perm'`s `hasPermission()`method:

```
if (!$perm->hasPermission($request))
    exit('Access denied');

// access allowed, continue with the app...
```

That's the idea on how to use `Perm`. The CRUD functions, or database of users, roles , and resources, are not included in this library as they are best implemented in userland -- since they are typically unique per project. The important thing to remember is to make them compatible with the three arrays required by `Perm` as discussed previously:

- **$roleRanks**
- **$roleResources**
- **$resourceRestrictions**

###  Health Score

26

—

LowBetter than 43% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity6

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity60

Established project with proven stability

 Bus Factor1

Top contributor holds 92.9% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~181 days

Recently: every ~269 days

Total

7

Last Release

1090d ago

Major Versions

v1.0.0 → v2.0.02020-06-04

v2.1.0 → v3.0.02020-06-14

### Community

Maintainers

![](https://www.gravatar.com/avatar/2efbbec5345d184bd2ffcb1c78f050fd7775cf1e52e64ab171e5673aaefc6daf?d=identicon)[zkwbbr](/maintainers/zkwbbr)

---

Top Contributors

[![zkwbbr](https://avatars.githubusercontent.com/u/45949485?v=4)](https://github.com/zkwbbr "zkwbbr (13 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (1 commits)")

---

Tags

rolespermissionsrbacaccess-controlabac

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/metarush-perm/health.svg)

```
[![Health](https://phpackages.com/badges/metarush-perm/health.svg)](https://phpackages.com/packages/metarush-perm)
```

###  Alternatives

[spatie/laravel-permission

Permission handling for Laravel 12 and up

12.9k89.8M1.0k](/packages/spatie-laravel-permission)[santigarcor/laratrust

This package provides a flexible way to add Role-based Permissions to Laravel

2.3k5.4M43](/packages/santigarcor-laratrust)[bezhansalleh/filament-shield

Filament support for `spatie/laravel-permission`.

2.8k2.9M88](/packages/bezhansalleh-filament-shield)[casbin/casbin

a powerful and efficient open-source access control library for php projects.

1.3k1.4M54](/packages/casbin-casbin)[casbin/laravel-authz

An authorization library that supports access control models like ACL, RBAC, ABAC in Laravel.

324339.9k4](/packages/casbin-laravel-authz)[pktharindu/nova-permissions

Laravel Nova Grouped Permissions (ACL)

136387.1k](/packages/pktharindu-nova-permissions)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)