README

介绍

Phalcon Confer，或简称Confer，为您的应用程序提供强大的灵活的角色和权限管理系统。

用户或用户团队都可以接收新角色。

Confer 受 Laravel 包 Entrust 的极大启发。

安装

Confer 可以通过 Composer 安装，只需将 "michele-angioni/phalcon-confer": "^1.0" 添加到您的 composer.json 中，然后运行 composer update 或 composer install。

然后必须运行 Confer 迁移以创建所需的表。为此，您需要安装 Phalcon Dev Tools。

或者，可以使用 Yarak 来运行迁移。只需将迁移文件复制粘贴到您的迁移文件夹中，然后运行 php yarak migrate。

从您的 Phalcon 根目录运行 phalcon migration run --migrations=vendor/michele-angioni/phalcon-confer/migrations。

使用方法

赋予用户权限

假设您有一个 MyApp\Users 模型，您想为其添加角色。它只需扩展 MicheleAngioni\PhalconConfer\Models\AbstractConferModel 并使用 MicheleAngioni\PhalconConfer\ConferTrait，如下所示

<?php

namespace MyApp;

use MicheleAngioni\PhalconConfer\ConferTrait;
use MicheleAngioni\PhalconConfer\Models\AbstractConferModel;

class Users extends AbstractConferModel
{
    use ConferTrait;

    protected $id;

    protected $email;

    protected $password;

    public function getId(): int
    {
        return $this->id;
    }

    public function getEmail(): string
    {
        return $this->email;
    }

    public function setEmail(string $email)
    {
        $this->email = $email;
    }

    public function getPassword(): string
    {
        return $this->password;
    }

    public function setPassword(string $password)
    {
        $this->password = $password;
    }
}

赋予团队权限

或者，如果您的应用程序有用户团队，并且您需要赋予团队角色和权限系统，Confer 可以实现这一点。

假设您还有一个 MyApp\Teams 模型，并且您想为属于每个团队的用户分别添加角色。您只需也扩展 MicheleAngioni\PhalconConfer\Models\AbstractConferTeamModel 和 MicheleAngioni\PhalconConfer\ConferTeamTrait 到您的团队模型中，如下所示

<?php

namespace MyApp;

use MicheleAngioni\PhalconConfer\ConferTeamTrait;
use MicheleAngioni\PhalconConfer\Models\AbstractConferTeamModel;

class Teams extends AbstractConferTeamModel
{
    use ConferTeamTrait;

    protected $id;

    protected $name;

    public function getId(): int
    {
        return $this->id;
    }

    public function getName(): string
    {
        return $this->name;
    }

    public function setName(string $name)
    {
        $this->name = $name;
    }
}

角色和权限管理

Confer 类

Confer 的大多数功能都可以通过 Confer 类来处理，它提供了一个有用的网关来管理角色和权限。

您可以通过以下方式简单地创建 Confer 类的实例

$confer = new Confer(
    new RoleService(new Roles()),
    new PermissionService(new Permissions())
);

或者，您可以通过定义来利用 Phalcon 的依赖注入

$di->setShared('confer', function () use ($di) {
    return new Confer(
     new RoleService(new Roles()),
     new PermissionService(new Permissions())
   );
});

检索所有角色和权限

多亏了 Confer 类，检索所有角色和权限非常简单

$roles = $confer->getRoles();

$permissions = $confer->getPermissions();

检索特定的角色或权限

Confer 类还允许通过 id 和名称搜索角色或权限

$role = $confer->getRole('Admin'); // Also the Role id can be used as parameter

$permission = $confer->getPermission('manage_roles'); // Also the Permission id can be used as parameter

创建新角色

创建新角色非常简单，可以通过使用 Confer 类来完成

$role = $confer->createRole([
    'name' => 'Admin'
]);

创建新权限

创建新权限的方式与角色相同

$permission = $confer->createPermission([
    'name' => 'manage_roles'
]);

删除角色或权限

Confer 类还提供了通过 id 和名称正确删除角色和权限的方法。

$role = $confer->getRole('Admin'); // Also the Role id can be used as parameter

$permission = $confer->getPermission('manage_roles'); // Also the Permission id can be used as parameter

将权限分配给角色

将权限分配给角色很简单

$role->attachPermission($permission);

从角色中删除权限

与之前一样，从角色中删除权限只需要一个命令

$role->detachPermission($permission);

检索所有权限角色

多亏了 Phalcon ORM，我们可以立即从角色中检索所有权限

$permissions = $role->getPermissions();

用户角色管理

将角色分配给用户

多亏了 ConferTrait，使用 Confer 管理角色极其简单

$user->attachRole($role);

从用户中移除角色

类似于分配的方式，我们也可以将其移除

$user->detachRole($role);

检索所有用户角色

同样，得益于Phalcon ORM，我们可以立即从用户中检索所有角色

$roles = $user->getRoles();

检查角色

检查用户是否具有特定角色非常简单

$user->hasRole($roleName);

检查权限

甚至检查特定权限也非常简单

$user->can($permissionName);

团队用户角色管理

将角色分配给团队

得益于ConferTeamTrait，即使团队角色也可以轻松处理

$team->attachRole($idUser, $role);

从团队中移除角色

类似于分配的方式，我们也可以将其移除

$team->detachRole($idUser);

检查角色

可以从用户和团队模型中检查团队用户是否具有特定角色

$user->hasRoleInTeam($idTeam, $roleName);
$team->userHasRole($idUser, $roleName);

检查权限

同样，可以从这两个模型中执行特定权限的检查

$team->userCan($idUser, $permissionName);
$team->canInTeam($idTeam, $permissionName);

中间件

一旦设置了您自己的角色和权限，您可能希望保护一些路由。实现这一点最简单的方法是使用Phalcon Router的Match功能。您可以轻松编写您自己的RolesMiddleware或使用Confer中包含的Middleware。

自定义匹配中间件

让我们构建一个自定义RolesMiddleware骨架，这样您就可以轻松将其添加到您的应用程序中

<?php

namespace MyApp;

use Phalcon\Http\Response;
use Phalcon\Mvc\User\Plugin;

class RolesMiddleware extends Plugin
{
    /**
     * The Role name.
     *
     * @var string
     */
    protected $roleName;

    /**
     * @param string $roleName
     */
    function __construct(string $roleName)
    {
        $this->roleName = $roleName;
    }

    /**
     * Check if there is an Authenticated User and if he/she has the required Role.
     *
     * @return mixed
     */
    public function check()
    {
        // 1) Check if a User if currently authenticated. You can do this with your own auth service or however you prefer
           
        [...]  // Let's say we have a $user object which can be null, false or an instance of MyApp\Users
        
        // 2) Check if an authenticated User has been found

        if (!$user) {
            // The User is not authenticated, return false
            return false;
        }

        // 3) We have the authenticated User. Check if he/she has the required role

        if(!$user->hasRole($this->roleName)) {
            // The User has not the required role, return false
            return false;
        }

        return true;
    }
}

现在我们有了RolesMiddleware，只需将其添加到路由器中，并检查用户是否有'Admin'角色

$router->addGet('/super-private-route', [
    'module' => 'web',
    'controller' => 'secret',
    'action' => 'index'
])->beforeMatch([new \MyApp\RolesMiddleware('DEV', '/homepage'), 'check']);

就是这样。如果用户没有所需的角色，他将收到一个404错误。

Confer RolesMiddleware

Confer自带了一个内置的RolesMiddleware。然而，为了使用它，用户的认证必须由Phalcon Auth处理。

Phalcon Auth允许您通过调用$auth->getAuth()轻松检索已认证的用户。

如果您使用Phalcon Auth来处理认证，添加Confer RolesMiddleware非常简单

$router->addGet('/super-private-route', [
    'module' => 'web',
    'controller' => 'secret',
    'action' => 'index'
])->beforeMatch([new \MicheleAngioni\PhalconConfer\Middlewares('DEV', '/homepage'), 'check']);

贡献指南

Confer遵循PSR-1、PSR-2和PSR-4 PHP编码标准和语义版本控制。

欢迎拉取请求。

许可证

Confer是免费软件，根据MIT许可证的条款分发。