dubroquin/bouncer

silber/bouncer 的分支

维护者

详情

github.com/DUBroquin/bouncer

源代码

安装: 264

依赖项: 0

建议者: 0

安全性: 0

星星: 0

关注者: 0

分支: 330

v1.0.0-beta.11 2017-08-01 10:55 UTC

Requires

Requires (Dev)

Suggests

MIT ed8cf4b8284656f9f67c6a1e823ae9a0ecf6d130

  • Joseph Silber <contact.woop@josephsilber.com>
  • Donovan Broquin <dbroquin.woop@deliverup.com>

capabilitiesacllaravelrolespermissionseloquentabilities

This package is not auto-updated.

Last update: 2024-09-23 07:07:49 UTC

README

此包在 Laravel 的访问门处添加了一个守门员。

注意：如果您是从 Bouncer 的早期版本升级，请务必查看升级指南。

简介

Bouncer 提供了一种处理 Laravel 的 ACL 中角色和能力的机制。使用表达性和流畅的语法，它尽可能少地干扰您：当您需要时使用它，不需要时忽略它。

要快速查看 Bouncer 的功能列表，请查看速查表。

Bouncer 可以很好地与您在应用程序中硬编码的其他能力一起工作。您的代码始终具有优先权：如果您的代码允许执行操作，守门员将不会干扰。

安装后，您只需告诉守门员在门处允许什么即可

// Give a user the ability to create posts
Bouncer::allow($user)->to('create', Post::class);

// Alternatively, do it through a role
Bouncer::allow('admin')->to('create', Post::class);
Bouncer::assign('admin')->to($user);

// You can also grant an ability only to a specific model
Bouncer::allow($user)->to('edit', $post);

当您在门处检查能力时，守门员将首先被咨询。如果他看到当前用户（无论是直接还是通过角色）已被授予的能力，他将授权检查。

安装

使用 composer 安装守门员包

$ composer require Dubroquin/bouncer v1.0.0-beta.4

composer 安装完成后，您可以添加服务提供程序并别名外观。打开 config/app.php，并做出以下更改

  1. 向 providers 数组添加一个新项
Dubroquin\Bouncer\BouncerServiceProvider::class,
  1. 向 aliases 数组添加一个新项
'Bouncer' => Dubroquin\Bouncer\BouncerFacade::class,

这部分是可选的。如果您不想使用外观，可以跳过步骤 2。

  1. 将守门员的特质添加到您的用户模型中
use Dubroquin\Bouncer\Database\HasRolesAndAbilities;

class User extends Model
{
    use HasRolesAndAbilities;
}
  1. 现在，要运行守门员的迁移，首先通过运行以下命令将包的迁移发布到您的应用程序的 migrations 目录
php artisan vendor:publish --tag="bouncer.migrations"
  1. 最后，运行迁移
php artisan migrate

外观

在您的代码中使用 Bouncer 外观时，请记住在文件顶部添加以下行到命名空间导入中

use Bouncer;

有关 Laravel 外观的更多信息，请参阅Laravel 文档。

启用缓存

守门器执行的查询都缓存在当前请求中。为了更好的性能，您可能希望使用跨请求缓存。要启用跨请求缓存，请将以下内容添加到 AppServiceProvider 的 boot 方法中

Bouncer::cache();

警告：如果您启用了跨请求缓存，您负责在修改用户的角色和能力时刷新缓存。有关刷新缓存的信息，请参阅刷新缓存。

升级

升级到 1.0

Bouncer 1.0 中的表结构已发生重大变化。要升级，您必须更新您的数据库模式以符合新结构。

如果你的应用尚未投入生产，并且你仍然可以回滚迁移，请这样做。一旦回滚所有迁移，你可以删除Bouncer迁移文件并重新发布以获取更新的版本

php artisan vendor:publish --provider="Dubroquin\Bouncer\BouncerServiceProvider" --tag="migrations"

对于已经投入生产并且数据库中已有实际数据的应用，Bouncer附带一个升级迁移文件，该文件将迁移你的模式和你的数据到新结构。

记住：在迁移之前，务必对您的数据库进行全面备份！如果出现任何问题，您将需要从备份中恢复。

通过composer更新到Bouncer 1.0后，运行以下命令

php artisan bouncer:upgrade

这将在database/migrations下创建一个新的迁移文件，并将自动调用artisan的migrate命令来迁移数据库。

恭喜你，你的升级完成了！

如果你之前更改了Bouncer的默认表名，你将不得不在此迁移文件中更改它们。为了防止bouncer:upgrade命令实际迁移你的数据库，请使用带有no-migrate标志调用它

php artisan bouncer:upgrade --no-migrate

这将创建迁移文件，但不会实际迁移数据库。你现在可以手动编辑迁移文件以进行任何必要的更改。在进行了必要的更改后，请记住自己运行php artisan migrate命令。

使用

向用户添加角色和权限变得非常简单。您无需提前创建角色或权限。只需传递角色/权限的名称，Bouncer就会在不存在时创建它。

注意：下面的示例都使用了Bouncer外观。如果您不喜欢外观，您可以在类中注入Dubroquin\Bouncer\Bouncer的一个实例。

创建角色和能力

让我们创建一个名为admin的角色，并给它赋予在网站上ban-users的权限

Bouncer::allow('admin')->to('ban-users');

就是这样。幕后，Bouncer将为您创建一个Role模型和一个Ability模型。

将角色分配给用户

要现在将admin角色分配给一个用户，只需告诉Bouncer该用户应被分配admin角色

Bouncer::assign('admin')->to($user);

或者，您可以直接在用户上调用assign方法

$user->assign('admin');

直接赋予用户能力

有时您可能希望直接给用户一个权限，而不使用角色

Bouncer::allow($user)->to('ban-users');

这里您也可以直接从用户处完成同样的操作

$user->allow('ban-users');

将能力限制在模型上

有时您可能希望将一个权限限制为特定模型类型。只需将模型名称作为第二个参数传递

Bouncer::allow($user)->to('edit', Post::class);

如果您想将权限限制为特定的模型实例，传递实际的模型

Bouncer::allow($user)->to('edit', $post);

从用户撤回角色

Bouncer还可以从用户撤回之前分配的角色

Bouncer::retract('admin')->from($user);

或者直接在用户上操作

$user->retract('admin');

移除能力

Bouncer还可以移除之前授予用户的权限

Bouncer::disallow($user)->to('ban-users');

或者直接在用户上操作

$user->disallow('ban-users');

注意：如果用户有一个允许他们ban-users的角色，他们仍然会有这个权限。要禁止它，您必须从角色中删除权限或从用户中撤回角色。

如果权限是通过角色授予的，告诉Bouncer从角色中移除权限

Bouncer::disallow('admin')->to('ban-users');

要为特定模型类型移除权限，传递其名称作为第二个参数

Bouncer::disallow($user)->to('delete', Post::class);

警告：如果用户有一个权限来删除特定的$post实例，上面的代码将不会移除该权限。您必须单独移除该权限 - 如下面所示，通过传递实际的$post作为第二个参数。

要为特定模型实例移除权限，传递实际的模型

Bouncer::disallow($user)->to('delete', $post);

检查用户的角色

注意：一般来说，您不需要直接检查角色。最好是允许角色拥有某些能力，然后检查这些能力。如果您需要的功能非常通用，您可以创建非常广泛的能力。例如，一个 access-dashboard 能力始终比直接检查 admin 或 editor 角色要好。对于您确实想要检查角色的罕见情况，该功能在此处可用。

Bouncer 可以检查用户是否拥有特定的角色

Bouncer::is($user)->a('moderator');

如果您要检查的角色以元音字母开头，您可能想使用 an 别名方法

Bouncer::is($user)->an('admin');

对于相反的情况，您也可以检查用户是否没有特定的角色

Bouncer::is($user)->notA('moderator');

Bouncer::is($user)->notAn('admin');

您可以检查用户是否拥有许多角色中的一个

Bouncer::is($user)->a('moderator', 'editor');

您也可以检查用户是否拥有所有给定的角色

Bouncer::is($user)->all('editor', 'moderator');

您还可以检查用户是否没有任何给定的角色

Bouncer::is($user)->notAn('editor', 'moderator');

这些检查也可以直接在用户上执行

$user->isAn('admin');
$user->isA('subscriber');

$user->isNotAn('admin');
$user->isNotA('subscriber');

$user->isAll('editor', 'moderator');

获取用户的全部能力

您可以直接从用户模型获取用户的全部能力

$abilities = $user->getAbilities();

这将返回一个包含用户所有能力的集合，包括通过其角色授予给用户的能力。

授权用户

用户授权在 Laravel 的 Gate 中直接处理，或在用户模型上（$user->can($ability)）。

为了方便，Bouncer 类提供了两种中继方法

Bouncer::allows($ability);
Bouncer::denies($ability);

这些方法直接调用到 Gate 类。

Blade 指令

Bouncer 不会添加自己的 blade 指令。由于 Bouncer 直接与 Laravel 的 gate 一起工作，因此只需使用其 @can 指令来检查当前用户的权限。

@can ('update', $post)
    <a href="{{ route('post.update', $post) }}">Edit Post</a>
@endcan

由于直接检查角色通常不推荐，Bouncer 不提供用于该目的的单独指令。如果您仍然坚持要检查角色，您可以使用一般的 @if 指令。

@if ($user->isAn('admin'))
    //
@endif

刷新缓存

Bouncer 执行的所有查询都将在当前请求中缓存。如果您启用了跨请求缓存，缓存将在不同的请求之间持久化。

您可以在需要时完全刷新 Bouncer 的缓存

Bouncer::refresh();

注意：如果可用，完全刷新所有用户的缓存将使用 缓存标签。并非所有缓存驱动程序都支持此功能。请参阅 Laravel 文档，以查看您的驱动程序是否支持缓存标签。如果您的驱动程序不支持缓存标签，调用 refresh 可能会因系统中用户数量而略显缓慢。

或者，您可以只刷新特定用户的缓存

Bouncer::refreshFor($user);

速查表

// Adding abilities for users
Bouncer::allow($user)->to('ban-users');
Bouncer::allow($user)->to('edit', Post::class);
Bouncer::allow($user)->to('delete', $post);

Bouncer::allow($user)->everything();
Bouncer::allow($user)->toManage(Post::class);
Bouncer::allow($user)->toManage($post);
Bouncer::allow($user)->toAlways('view');

Bouncer::allow($user)->toOwn(Post::class);
Bouncer::allow($user)->toOwnEverything();

// Removing abilities uses the same syntax, e.g.
Bouncer::disallow($user)->to('delete', $post);
Bouncer::disallow($user)->toManage(Post::class);
Bouncer::disallow($user)->toOwn(Post::class);

// Adding & removing abilities for roles
Bouncer::allow('admin')->to('ban-users');
Bouncer::disallow('admin')->to('ban-users');

// Assigning & retracting roles from users
Bouncer::assign('admin')->to($user);
Bouncer::retract('admin')->from($user);

$check = Bouncer::allows('ban-users');
$check = Bouncer::allows('edit', Post::class);
$check = Bouncer::allows('delete', $post);

$check = Bouncer::denies('ban-users');
$check = Bouncer::denies('edit', Post::class);
$check = Bouncer::denies('delete', $post);

$check = Bouncer::is($user)->a('subscriber');
$check = Bouncer::is($user)->an('admin');
$check = Bouncer::is($user)->notA('subscriber');
$check = Bouncer::is($user)->notAn('admin');
$check = Bouncer::is($user)->a('moderator', 'editor');
$check = Bouncer::is($user)->all('moderator', 'editor');

Bouncer::cache();
Bouncer::dontCache();

Bouncer::refresh();
Bouncer::refreshFor($user);

一些此功能也直接在用户模型上提供

$user->allow('ban-users');
$user->allow('edit', Post::class);
$user->allow('delete', $post);

$user->disallow('ban-users');
$user->disallow('edit', Post::class);
$user->disallow('delete', $post);

$user->assign('admin');
$user->retract('admin');

$check = $user->isAn('admin');
$check = $user->isAn('editor', 'moderator');
$check = $user->isAll('moderator', 'editor');
$check = $user->isNot('subscriber', 'moderator');

$abilities = $user->getAbilities();

替代方案

在 Spatie 非常慷慨地赐予社区的无数个包中，您会发现优秀的 laravel-permission 包。像 Bouncer 一样，它很好地集成了 Laravel 内置的 gate 和权限检查，但在语法、DB 结构和功能方面有一套不同的设计选择。Povilas Korop 在 Laravel News 上的文章中出色地比较了这两个，。

许可

Bouncer 是开源软件，采用 MIT 许可证