PHPackages                             tourze/role-based-access-control-bundle - 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. tourze/role-based-access-control-bundle

ActiveSymfony-bundle[Authentication & Authorization](/categories/authentication)

tourze/role-based-access-control-bundle
=======================================

基于角色的访问控制(RBAC)Bundle，为PHP Monorepo提供统一的权限管理系统

0.0.1(4mo ago)00MITPHPPHP ^8.2CI passing

Since Dec 20Pushed 4mo agoCompare

[ Source](https://github.com/tourze/role-based-access-control-bundle)[ Packagist](https://packagist.org/packages/tourze/role-based-access-control-bundle)[ RSS](/packages/tourze-role-based-access-control-bundle/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (1)Dependencies (35)Versions (2)Used By (0)

Role-Based Access Control Bundle
================================

[](#role-based-access-control-bundle)

基于角色的访问控制(RBAC)Bundle，为 PHP Monorepo 提供完整的权限管理系统

[![PHP Version](https://camo.githubusercontent.com/962aced9b09d89716dbebf186ff899754a096ff1068b6b7988675c2d9fab9331/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253545382e322d626c75652e737667)](https://php.net)[![Symfony Version](https://camo.githubusercontent.com/e04c6225a1086092d0490062dec434db5fa25945c2faa41181cc5b84f026a057/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f73796d666f6e792d253545372e332d626c61636b2e737667)](https://symfony.com)[![License](https://camo.githubusercontent.com/8bb50fd2278f18fc326bf71f6e88ca8f884f72f179d3e555e20ed30157190d0d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e2e737667)](LICENSE)

[English](README.md) | [中文](README.zh-CN.md)

功能特性
----

[](#功能特性)

- **完整 RBAC 系统**：提供角色、权限、用户角色的完整管理
- **无缝集成**：与 Symfony Security 系统深度集成，支持 `#[IsGranted]` 注解
- **灵活权限控制**：基于自定义 Voter 实现细粒度权限管理
- **EasyAdmin 集成**：提供开箱即用的管理界面
- **命令行工具**：丰富的 CLI 命令简化权限管理
- **事件驱动**：完整的事件系统支持权限审计
- **性能优化**：高效的权限查询和缓存机制

安装指南
----

[](#安装指南)

### 安装依赖

[](#安装依赖)

```
composer require tourze/role-based-access-control-bundle
```

### 注册 Bundle

[](#注册-bundle)

在 `config/bundles.php` 中添加：

```
return [
    // ...
    Tourze\RoleBasedAccessControlBundle\RoleBasedAccessControlBundle::class => ['all' => true],
];
```

### 数据库架构

[](#数据库架构)

创建必要的数据库表：

```
-- 角色表
CREATE TABLE `rbac_role` (
    `id` INT AUTO_INCREMENT PRIMARY KEY,
    `code` VARCHAR(255) NOT NULL UNIQUE,
    `name` VARCHAR(255) NOT NULL,
    `description` TEXT NULL,
    `parent_role_id` INT NULL,
    `hierarchy_level` INT NULL,
    `created_at` DATETIME NOT NULL,
    `updated_at` DATETIME NOT NULL,
    UNIQUE KEY `role_code_unique` (`code`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

-- 权限表
CREATE TABLE `rbac_permission` (
    `id` INT AUTO_INCREMENT PRIMARY KEY,
    `code` VARCHAR(255) NOT NULL UNIQUE,
    `name` VARCHAR(255) NOT NULL,
    `description` TEXT NULL,
    `created_at` DATETIME NOT NULL,
    `updated_at` DATETIME NOT NULL,
    UNIQUE KEY `permission_code_unique` (`code`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

-- 用户角色关联表
CREATE TABLE `user_role` (
    `id` INT AUTO_INCREMENT PRIMARY KEY,
    `user_id` INT NOT NULL,
    `role_id` INT NOT NULL,
    `created_at` DATETIME NOT NULL,
    `updated_at` DATETIME NOT NULL,
    UNIQUE KEY `user_role_unique` (`user_id`, `role_id`),
    KEY `idx_user_role_user` (`user_id`),
    KEY `idx_user_role_role` (`role_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

-- 角色权限关联表
CREATE TABLE `rbac_role_permission` (
    `role_id` INT NOT NULL,
    `permission_id` INT NOT NULL,
    PRIMARY KEY (`role_id`, `permission_id`),
    KEY `idx_role_permission_role` (`role_id`),
    KEY `idx_role_permission_permission` (`permission_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
```

使用方法
----

[](#使用方法)

### 在 Controller 中使用权限

[](#在-controller-中使用权限)

```
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\Security\Http\Attribute\IsGranted;

class UserController extends AbstractController
{
    #[IsGranted('PERMISSION_USER_EDIT')]
    public function editUser(): Response
    {
        // 只有拥有 PERMISSION_USER_EDIT 权限的用户才能访问
    }

    #[IsGranted('PERMISSION_ORDER_VIEW')]
    public function viewOrder(): Response
    {
        // 只有拥有 PERMISSION_ORDER_VIEW 权限的用户才能访问
    }
}
```

### 在 Service 中使用权限

[](#在-service-中使用权限)

```
use Symfony\Component\Security\Core\Security;

class OrderService
{
    public function __construct(private Security $security)
    {
    }

    public function deleteOrder(int $orderId): void
    {
        if ($this->security->isGranted('PERMISSION_ORDER_DELETE')) {
            // 执行删除操作
        } else {
            throw new AccessDeniedException('删除订单权限不足');
        }
    }
}
```

### 在 Twig 模板中使用权限

[](#在-twig-模板中使用权限)

```
{% if is_granted('PERMISSION_USER_CREATE') %}

        创建用户

{% endif %}

{% if is_granted('PERMISSION_ARTICLE_PUBLISH') %}
    发布文章
{% endif %}
```

### 权限管理

[](#权限管理)

#### 创建角色和权限

[](#创建角色和权限)

```
use Tourze\RoleBasedAccessControlBundle\Entity\Role;
use Tourze\RoleBasedAccessControlBundle\Entity\Permission;

// 创建角色
$editorRole = new Role();
$editorRole->setCode('ROLE_EDITOR');
$editorRole->setName('编辑员');
$editorRole->setDescription('内容编辑角色');

// 创建权限
$editPermission = new Permission();
$editPermission->setCode('PERMISSION_ARTICLE_EDIT');
$editPermission->setName('编辑文章');
$editPermission->setDescription('编辑文章内容的权限');

// 保存到数据库
$this->entityManager->persist($editorRole);
$this->entityManager->persist($editPermission);
$this->entityManager->flush();

// 为角色分配权限
$editorRole->addPermission($editPermission);
$this->entityManager->flush();
```

#### 为用户分配角色

[](#为用户分配角色)

```
use Tourze\RoleBasedAccessControlBundle\Entity\UserRole;

// 分配角色给用户
$userRole = new UserRole();
$userRole->setUser($user);
$userRole->setRole($editorRole);

$this->entityManager->persist($userRole);
$this->entityManager->flush();
```

### CLI 命令

[](#cli-命令)

Bundle 提供了丰富的 CLI 命令来管理权限：

```
# 创建角色
php bin/console rbac:role:create ROLE_EDITOR "编辑员" "内容编辑角色"

# 创建权限
php bin/console rbac:permission:create PERMISSION_ARTICLE_EDIT "编辑文章" "编辑文章内容的权限"

# 授权
php bin/console rbac:grant ROLE_EDITOR PERMISSION_ARTICLE_EDIT

# 撤销权限
php bin/console rbac:revoke ROLE_EDITOR PERMISSION_ARTICLE_DELETE

# 查看用户权限
php bin/console rbac:user:permissions user@example.com

# 扫描代码中的权限使用情况
php bin/console rbac:scan-permissions src/ --check-missing

# 删除角色前检查依赖
php bin/console rbac:role:delete ROLE_EDITOR --check-dependencies
```

最佳实践
----

[](#最佳实践)

### 权限命名

[](#权限命名)

权限命名采用 `PERMISSION_[模块]_[对象]_[操作]` 格式

建议模块：

- 用户相关：`PERMISSION_USER_*`
- 订单相关：`PERMISSION_ORDER_*`
- 文章相关：`PERMISSION_ARTICLE_*`
- 系统相关：`PERMISSION_SYSTEM_*`

示例：

- `PERMISSION_USER_CREATE` - 创建用户
- `PERMISSION_ORDER_VIEW` - 查看订单
- `PERMISSION_ARTICLE_PUBLISH` - 发布文章
- `PERMISSION_SYSTEM_CONFIG` - 系统配置

### 角色命名

[](#角色命名)

角色命名采用 `ROLE_[名称]` 格式

示例：

- `ROLE_ADMIN` - 管理员
- `ROLE_MANAGER` - 经理
- `ROLE_EDITOR` - 编辑员
- `ROLE_USER` - 普通用户

### 数据模型

[](#数据模型)

#### Role 角色模型

[](#role-角色模型)

```
class Role
{
    private int $id;                    // 主键ID
    private string $code;               // 角色代码（唯一）
    private string $name;               // 角色名称
    private ?string $description;       // 角色描述
    private ?int $parentRoleId;         // 父角色ID（支持层级）
    private ?int $hierarchyLevel;       // 层级深度（支持层级）
    private Collection $permissions;    // 关联权限
    private Collection $userRoles;      // 关联用户角色
}
```

#### Permission 权限模型

[](#permission-权限模型)

```
class Permission
{
    private int $id;                    // 权限ID
    private string $code;               // 权限代码（唯一）
    private string $name;               // 权限名称
    private ?string $description;       // 权限描述
    private Collection $roles;          // 关联角色
}
```

#### UserRole 用户角色关联模型

[](#userrole-用户角色关联模型)

```
class UserRole
{
    private int $id;                    // 主键ID
    private UserInterface $user;        // 用户
    private Role $role;                 // 角色
}
```

高级功能
----

[](#高级功能)

### 事件监听

[](#事件监听)

Bundle 提供完整的事件系统，支持权限变更审计：

```
use Tourze\RoleBasedAccessControlBundle\Event\RoleAssignedToUserEvent;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;

class PermissionAuditListener
{
    #[AsEventListener(event: RoleAssignedToUserEvent::class)]
    public function onRoleAssigned(RoleAssignedToUserEvent $event): void
    {
        // 记录权限变更日志
        $this->logger->info('角色分配给用户', [
            'user' => $event->getUser()->getId(),
            'role' => $event->getRole()->getCode(),
            'operated_by' => $event->getOperatedBy()?->getId(),
        ]);
    }
}
```

### 自定义权限管理器

[](#自定义权限管理器)

```
use Tourze\RoleBasedAccessControlBundle\Service\PermissionManagerInterface;

class CustomPermissionManager implements PermissionManagerInterface
{
    public function getUserPermissions(UserInterface $user): array
    {
        // 自定义权限查询逻辑
    }

    public function hasPermission(UserInterface $user, string $permissionCode): bool
    {
        // 自定义权限检查逻辑
    }
}
```

EasyAdmin 集成
------------

[](#easyadmin-集成)

Bundle 提供开箱即用的 EasyAdmin 管理界面：

```
# config/easy_admin.yaml
easy_admin:
    entities:
        - Tourze\RoleBasedAccessControlBundle\Controller\Admin\RoleCrudController
        - Tourze\RoleBasedAccessControlBundle\Controller\Admin\PermissionCrudController
        - Tourze\RoleBasedAccessControlBundle\Controller\Admin\UserRoleCrudController
```

性能优化
----

[](#性能优化)

### 权限查询优化

[](#权限查询优化)

Bundle 提供高效的用户权限查询机制：

```
// Repository 层优化查询
public function getUserPermissions(UserInterface $user): array
{
    return $this->createQueryBuilder('p')
        ->join('p.roles', 'r')
        ->join('r.userRoles', 'ur')
        ->where('ur.user = :user')
        ->setParameter('user', $user)
        ->getQuery()
        ->getResult();
}
```

### 批量权限检查

[](#批量权限检查)

```
// 批量检查多个权限，减少数据库查询
public function checkMultiplePermissions(UserInterface $user, array $permissionCodes): array
{
    $userPermissions = $this->getUserPermissionCodes($user);
    $results = [];

    foreach ($permissionCodes as $permissionCode) {
        $results[$permissionCode] = in_array($permissionCode, $userPermissions);
    }

    return $results;
}
```

测试
--

[](#测试)

### 权限测试示例

[](#权限测试示例)

```
use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;

class PermissionTest extends WebTestCase
{
    public function testPermissionCheck(): void
    {
        $client = static::createClient();

        // 模拟用户登录
        $user = $this->createUserWithRole('ROLE_EDITOR');
        $client->loginUser($user);

        // 测试有权限的页面
        $client->request('GET', '/admin/users');
        $this->assertResponseIsSuccessful();

        $client->request('POST', '/admin/users/delete/1');
        $this->assertResponseStatusCodeSame(403); // 没有删除权限
    }
}
```

系统要求
----

[](#系统要求)

- **PHP**: `^8.2`
- **Symfony**: `^7.3`
- **Doctrine ORM**: `^3.0`

开发计划
----

[](#开发计划)

- 完善角色层级支持
- 权限继承功能
- 增强的权限审计日志
- 更好的 Symfony Security 集成

贡献指南
----

[](#贡献指南)

欢迎提交 Issue 和 Pull Request

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

许可证
---

[](#许可证)

本项目使用 MIT 许可证，详情请查看 [LICENSE](LICENSE) 文件

相关链接
----

[](#相关链接)

- [Symfony Security 文档](https://symfony.com/doc/current/security.html)
- [EasyAdmin 文档](https://symfony.com/doc/current/bundles/EasyAdminBundle/index.html)
- [Doctrine ORM 文档](https://www.doctrine-project.org/projects/orm.html)

支持
--

[](#支持)

如果您遇到问题，请：

- 提交 [GitHub Issue](https://github.com/tourze/php-monorepo/issues)
- 查看 [需求规格](.spec/requirements.md)
- 阅读 [开发指南](.spec/)

###  Health Score

31

—

LowBetter than 68% of packages

Maintenance79

Regular maintenance activity

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity36

Early-stage or recently created project

 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

Unknown

Total

1

Last Release

140d ago

### Community

Maintainers

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

---

Top Contributors

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

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/tourze-role-based-access-control-bundle/health.svg)

```
[![Health](https://phpackages.com/badges/tourze-role-based-access-control-bundle/health.svg)](https://phpackages.com/packages/tourze-role-based-access-control-bundle)
```

###  Alternatives

[sylius/sylius

E-Commerce platform for PHP, based on Symfony framework.

8.4k5.6M647](/packages/sylius-sylius)[contao/core-bundle

Contao Open Source CMS

1231.6M2.3k](/packages/contao-core-bundle)[sulu/sulu

Core framework that implements the functionality of the Sulu content management system

1.3k1.3M152](/packages/sulu-sulu)[ec-cube/ec-cube

EC-CUBE EC open platform.

78527.0k1](/packages/ec-cube-ec-cube)[prestashop/prestashop

PrestaShop is an Open Source e-commerce platform, committed to providing the best shopping cart experience for both merchants and customers.

9.0k15.4k](/packages/prestashop-prestashop)[open-dxp/opendxp

Content & Product Management Framework (CMS/PIM)

7310.3k29](/packages/open-dxp-opendxp)

PHPackages © 2026

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