PHPackages                             apaoww/yii2-cerbos - 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. apaoww/yii2-cerbos

ActiveYii2-extension[Authentication & Authorization](/categories/authentication)

apaoww/yii2-cerbos
==================

Yii2 extension for Cerbos access control with HTTP API integration

v1.1.0(7mo ago)027MITPHPPHP >=8.0

Since Sep 12Pushed 5mo agoCompare

[ Source](https://github.com/apaoww/yii2-cerbos)[ Packagist](https://packagist.org/packages/apaoww/yii2-cerbos)[ RSS](/packages/apaoww-yii2-cerbos/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (3)Versions (3)Used By (0)

Yii2 Cerbos Extension
=====================

[](#yii2-cerbos-extension)

A Yii2 extension that provides seamless integration with [Cerbos](https://cerbos.dev/) for fine-grained access control and authorization.

Features
--------

[](#features)

- **CerbosAccessControl**: Action filter for automatic route-based access control
- **CerbosHttpAuth**: HTTP client component for Cerbos API integration
- **System Prefix Support**: Add system-wide prefixes to resource names
- **RBAC Fallback**: Optional fallback to Yii2's built-in RBAC system
- **Flexible Resource Mapping**: Custom resource and action mapping
- **Batch Permission Checking**: Check multiple permissions in a single request

Installation
------------

[](#installation)

### Via Composer (Recommended)

[](#via-composer-recommended)

```
composer require apaoww/yii2-cerbos
```

### Local Development

[](#local-development)

Add to your project's `composer.json`:

```
{
    "repositories": [
        {
            "type": "path",
            "url": "vendor/apaoww/yii2-cerbos"
        }
    ],
    "require": {
        "apaoww/yii2-cerbos": "*"
    }
}
```

Configuration
-------------

[](#configuration)

### 1. Configure the Cerbos HTTP Component

[](#1-configure-the-cerbos-http-component)

Add the Cerbos component to your application config:

```
// config/main.php or config/main-local.php
return [
    'components' => [
        'cerbos' => [
            'class' => 'apaoww\cerbos\CerbosHttpAuth',
            'host' => 'localhost:3592', // Your Cerbos server
            'httpHost' => null, // Optional separate HTTP host
            'systemPrefix' => 'imap', // Optional system prefix for resources
            'projectCode' => 'imap',
            'db' => 'db', // Use custom database component
            'authAssignmentTable' => 'ad_sso_admin.auth_assignment',
        ],
    ],
];
```

### 2. Configure Access Control

[](#2-configure-access-control)

You can use CerbosAccessControl in two ways: **globally for the entire application** (recommended) or **per-controller**.

#### Option A: Global Application-Wide Access Control (Recommended)

[](#option-a-global-application-wide-access-control-recommended)

Configure access control for your entire application by adding it to your main config file:

```
// frontend/config/main-local.php (or backend/config/main-local.php)
return [
    'components' => [
        // ... other components
    ],

    // Global access control filter
    'as access' => [
        'class' => 'apaoww\cerbos\CerbosAccessControl',
        'systemPrefix' => 'imap', // System prefix for all resources
        'projectCode' => 'imap',
        'db' => 'db', // Use custom database component
        'authAssignmentTable' => 'ad_sso_admin.auth_assignment',
        'except' => ['debug/*', 'gii/*'], // Exclude debug and development tools
        'allowActions' => [
            // Public actions that don't require authentication
            'site/index',
            'site/login',
            'site/logout',
            'site/error',
            'site/captcha',
            'cas/*', // CAS authentication routes
        ],

        // Map specific routes to custom Cerbos resources and actions
        'resourceMap' => [
            'site/index' => [
                'resource' => 'dashboard',
                'action' => 'view',
            ],
            'user/*' => [
                'resource' => 'user',
                'action' => function() {
                    // Dynamic action mapping based on controller action
                    $actionId = Yii::$app->controller->action->id;
                    $actionMap = [
                        'index' => 'list',
                        'view' => 'read',
                        'create' => 'create',
                        'update' => 'update',
                        'delete' => 'delete',
                    ];
                    return $actionMap[$actionId] ?? $actionId;
                },
            ],
            'report/*' => [
                'resource' => 'report',
                'action' => function() {
                    return Yii::$app->controller->action->id;
                },
                'resourceId' => function() {
                    return Yii::$app->request->get('id');
                },
                'attributes' => [
                    'department' => function() {
                        return Yii::$app->user->identity->department ?? 'unknown';
                    },
                ],
            ],
        ],

        // Enable fallback to existing RBAC system during migration
        'useMdmFallback' => true,

        // Custom extractors for resource identification
        'resourceIdExtractor' => function($action) {
            return Yii::$app->request->get('id') ?: Yii::$app->request->post('id');
        },

        'resourceAttributesExtractor' => function($action) {
            $attributes = [];
            $user = Yii::$app->user->identity;

            if ($user) {
                if (isset($user->department)) {
                    $attributes['department'] = $user->department;
                }
                if (isset($user->role)) {
                    $attributes['role'] = $user->role;
                }
            }

            return $attributes;
        },
    ],
];
```

#### Option B: Per-Controller Access Control

[](#option-b-per-controller-access-control)

Add the access control filter to individual controller behaviors:

```
use apaoww\cerbos\CerbosAccessControl;

class ExampleController extends Controller
{
    public function behaviors()
    {
        return [
            'access' => [
                'class' => CerbosAccessControl::class,
                'systemPrefix' => 'imap', // Optional: override system prefix
                'useMdmFallback' => true, // Enable RBAC fallback
                'allowActions' => ['login', 'signup'], // Always allowed actions
                'resourceMap' => [
                    // Custom resource mappings
                    'example/special' => [
                        'resource' => 'special_resource',
                        'action' => 'custom_action',
                    ],
                ],
            ],
        ];
    }
}
```

#### When to Use Which Approach:

[](#when-to-use-which-approach)

- **Global Configuration**: Use when you want consistent access control across your entire application. This is the recommended approach for most applications.
- **Per-Controller Configuration**: Use when you need different access control rules for specific controllers or when gradually migrating to Cerbos.

Usage Examples
--------------

[](#usage-examples)

### Basic Usage

[](#basic-usage)

The extension automatically maps controller/action routes to Cerbos resources:

- `example/index` → Resource: `imap_example`, Action: `index`
- `example/view` → Resource: `imap_example`, Action: `read`
- `example/create` → Resource: `imap_example`, Action: `create`
- `example/update` → Resource: `imap_example`, Action: `update`
- `example/delete` → Resource: `imap_example`, Action: `delete`

### Custom Resource Mapping

[](#custom-resource-mapping)

```
'resourceMap' => [
    'user/*' => [
        'resource' => 'user_management',
        'action' => function() {
            return Yii::$app->controller->action->id === 'index' ? 'list' : 'manage';
        },
    ],
    'report/generate' => [
        'resource' => 'reports',
        'action' => 'generate',
        'resourceId' => function() {
            return Yii::$app->request->get('type', 'default');
        },
        'attributes' => [
            'department' => Yii::$app->user->identity->department ?? 'unknown',
        ],
    ],
],
```

### Resource ID and Attributes Extraction

[](#resource-id-and-attributes-extraction)

```
'resourceIdExtractor' => function($action) {
    return Yii::$app->request->get('id') ?: 'default';
},
'resourceAttributesExtractor' => function($action) {
    return [
        'owner_id' => Yii::$app->user->id,
        'created_at' => date('Y-m-d'),
    ];
},
```

### Direct Cerbos API Usage

[](#direct-cerbos-api-usage)

```
// Single permission check
$allowed = Yii::$app->cerbos->checkPermission(
    'read',
    'imap_document',
    '123',
    ['department' => 'sales']
);

// Batch permission check
$permissions = Yii::$app->cerbos->batchCheckPermissions(
    ['read', 'write', 'delete'],
    'imap_document',
    '123'
);
// Returns: ['read' => true, 'write' => false, 'delete' => false]
```

Configuration Options
---------------------

[](#configuration-options)

### CerbosAccessControl Options

[](#cerbosaccesscontrol-options)

OptionTypeDefaultDescription`allowActions`array`[]`Actions that are always allowed without checking permissions`resourceMap`array`[]`Custom mapping of routes to Cerbos resources and actions`useMdmFallback`bool`true`Enable fallback to Yii2 RBAC when Cerbos policy doesn't exist`systemPrefix`string`null`Prefix to prepend to all resource names`resourceIdExtractor`callable`null`Custom function to extract resource ID from request`resourceAttributesExtractor`callable`null`Custom function to extract resource attributes### CerbosHttpAuth Options

[](#cerboshttpauth-options)

OptionTypeDefaultDescription`host`string`'localhost:3592'`Cerbos server host and port`httpHost`string`null`Alternative HTTP host (if different from main host)`systemPrefix`string`null`System prefix for resource namesCerbos Policy Example
---------------------

[](#cerbos-policy-example)

Here's an example Cerbos policy file (`imap_example.yaml`) that works with this extension:

```
---
apiVersion: api.cerbos.dev/v1
resourcePolicy:
  version: "default"
  resource: "imap_example"
  rules:
    - actions: ['*']
      effect: EFFECT_ALLOW
      roles:
        - admin

    - actions: ['index', 'read']
      effect: EFFECT_ALLOW
      roles:
        - user
        - manager

    - actions: ['create', 'update', 'delete']
      effect: EFFECT_ALLOW
      roles:
        - manager
      condition:
        match:
          expr: request.resource.attr.department == principal.attr.department
```

Requirements
------------

[](#requirements)

- PHP 8.0 or higher
- Yii2 framework 2.0.14 or higher
- Cerbos server running and accessible
- GuzzleHTTP 7.0 or higher

License
-------

[](#license)

This extension is released under the MIT License. See LICENSE file for details.

Contributing
------------

[](#contributing)

Contributions are welcome! Please feel free to submit a Pull Request.

Support
-------

[](#support)

If you encounter any issues or have questions, please create an issue in the GitHub repository.

###  Health Score

32

—

LowBetter than 72% of packages

Maintenance67

Regular maintenance activity

Popularity7

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity41

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% 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 ~6 days

Total

2

Last Release

237d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/a775977f4705909feb9c4b573e420175096166c9084afb9084ac661f2e29dc16?d=identicon)[apaoww](/maintainers/apaoww)

---

Top Contributors

[![apaoww](https://avatars.githubusercontent.com/u/4974699?v=4)](https://github.com/apaoww "apaoww (4 commits)")

---

Tags

securityauthorizationrbacyii2extensionaccess-controlcerbos

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/apaoww-yii2-cerbos/health.svg)

```
[![Health](https://phpackages.com/badges/apaoww-yii2-cerbos/health.svg)](https://phpackages.com/packages/apaoww-yii2-cerbos)
```

###  Alternatives

[hosseinhezami/laravel-permission-manager

Advanced permission manager for Laravel.

403.3k](/packages/hosseinhezami-laravel-permission-manager)

PHPackages © 2026

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