README

spatie/laravel-permission 的管理界面。允许管理员轻松添加/编辑/删除用户、角色和权限，使用 Laravel Backpack。

与一些其他包不同

用户可以有多个角色；
用户可以拥有额外的权限，除了他们所拥有的角色上的权限之外；

此包只是 spatie/laravel-permission 的用户界面。它将安装它，并允许您在代码中使用其 API。有关如何在代码中使用的信息，请参阅他们的 README。

安全更新和重大更改

请 订阅 Backpack Newsletter，以便了解任何安全更新、重大更改或主要功能。我们每 1-2 个月发送一封电子邮件。

安装

此包假设您已经安装了 Backpack for Laravel。如果您还没有，请首先安装 Backpack。
在您的终端中

composer require hncore/permissionmanager

完成 spatie/laravel-permission 的所有安装步骤，该步骤作为依赖项被拉入。运行其迁移。发布其配置文件。很可能如下所示：

php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider" --tag="permission-migrations"
php artisan migrate
php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider" --tag="permission-config"
// then, add the Spatie\Permission\Traits\HasRoles trait to your User model(s)

发布 hncore\permissionmanager 配置文件和迁移

php artisan vendor:publish --provider="Backpack\PermissionManager\PermissionManagerServiceProvider" --tag="config" --tag="migrations"

注意： 我们建议您只发布配置文件和迁移，但您也可以发布 lang 和 routes。

运行迁移

php artisan migrate

此包假设它可以使用默认的 Backpack 用户模型（最可能是 App\Models\User 来管理用户。如果您想使用不同的模型，请通过在 config/hncore/permissionmanager.php 文件中更改用户模型来实现。任何您正在使用的模型，请确保它正在使用 CrudTrait 和 HasRoles 特性。

<?php namespace App\Models;

use Backpack\CRUD\app\Models\Traits\CrudTrait; // <------------------------------- this one
use Spatie\Permission\Traits\HasRoles;// <---------------------- and this one
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    use CrudTrait; // <----- this
    use HasRoles; // <------ and this

    /**
     * Your User Model content
     */

[可选] 在 resources/views/vendor/hncore/ui/inc/menu_items.blade.php 中为其添加一个菜单项

<x-hncore::menu-dropdown title="Add-ons" icon="la la-puzzle-piece">
    <x-hncore::menu-dropdown-header title="Authentication" />
    <x-hncore::menu-dropdown-item title="Users" icon="la la-user" :link="hncore_url('user')" />
    <x-hncore::menu-dropdown-item title="Roles" icon="la la-group" :link="hncore_url('role')" />
    <x-hncore::menu-dropdown-item title="Permissions" icon="la la-key" :link="hncore_url('permission')" />
</x-hncore::menu-dropdown>

[可选] 如果您想在 Backpack 路由中使用 @can 处理程序，您可以

(7.A.) 将 Backpack 更改为使用默认的 web 守卫而不是它自己的守卫。在 config/hncore/base.php 中更改

    // The guard that protects the Backpack admin panel.
    // If null, the config.auth.defaults.guard value will be used.
-   'guard' => 'hncore',
+   'guard' => null,

注意

当您添加新角色和权限时，数据库中保存的守卫将是 "web"；

(7.B.) 通过向您的 config/hncore/base.php 文件中添加以下内容来为所有 Backpack 路由添加中间件

    // The classes for the middleware to check if the visitor is an admin
    // Can be a single class or an array of classes
    'middleware_class' => [
        App\Http\Middleware\CheckIfAdmin::class,
        \Illuminate\Foundation\Http\Middleware\ConvertEmptyStringsToNull::class,
+       Backpack\CRUD\app\Http\Middleware\UseBackpackAuthGuardInsteadOfDefaultAuthGuard::class,
    ],

原因？ spatie/laravel-permission 使用 Auth 门面通过 @can 确定权限。使用 Auth 门面使用在 config/auth.php 中定义的默认守卫，而不是我们的 hncore 守卫。

请注意

这将使 auth() 返回与 hncore_auth() 在 Backpack 路由中完全相同的内容；
您只需要这样做如果您想使用 @can；您也可以使用 @if(hncore_user()->can('read'))，它执行完全相同的事情，但 100% 的时间都会工作；
当您添加新角色和权限时，数据库中保存的守卫将是 "hncore"；

【可选】在定义后，使用 config/hncore/permissionmanager.php 中的配置文件禁止对您的角色或权限进行创建/更新。请注意，代码中使用名称引用权限和角色。如果您允许管理员编辑这些字符串，并且他们真的这么做了，您的权限和角色检查将停止工作。

自定义 UserCrudController

如果您想为此包提供的默认用户控制器添加更多字段，您可以绑定自己的控制器来覆盖此包中提供的控制器

// in some ServiceProvider, AppServiceProvider for example

$this->app->bind(
    \Backpack\PermissionManager\app\Http\Controllers\UserCrudController::class, //this is package controller
    \App\Http\Controllers\Admin\UserCrudController::class //this should be your own controller
);

// this tells Laravel that when UserCrudController is requested, your own UserCrudController should be served.

API 使用

由于此包需要 spatie/laravel-permission，API 将相同。请参阅他们的 README 文件以获取完整的 API。尽管如此，这里有一个摘要：

使用权限

可以将权限授予用户

hncore_user()->givePermissionTo('edit articles');

可以从用户中撤销权限

hncore_user()->revokePermissionTo('edit articles');

您可以使用测试用户是否有权限

hncore_user()->hasPermissionTo('edit articles');

保存的权限将注册到 Illuminate\Auth\Access\Gate 类。因此，您可以使用 Laravel 的默认 can 函数测试用户是否有权限。

hncore_user()->can('edit articles');

使用角色和权限

可以将角色分配给用户

hncore_user()->assignRole('writer');

可以从用户中移除角色

hncore_user()->removeRole('writer');

您可以使用测试确定用户是否有特定的角色

hncore_user()->hasRole('writer');

您还可以确定用户是否有给定列表中的任何角色

hncore_user()->hasAnyRole(Role::all());

您还可以确定用户是否有给定列表中的所有角色

hncore_user()->hasAllRoles(Role::all());

assignRole、hasRole、hasAnyRole、hasAllRoles 和 removeRole 函数可以接受字符串、数组、Role 对象或 \Illuminate\Support\Collection 对象。

可以将权限授予角色

$role->givePermissionTo('edit articles');

您可以确定角色是否有特定的权限

$role->hasPermissionTo('edit articles');

可以从角色中撤销权限

$role->revokePermissionTo('edit articles');

givePermissionTo 和 revokePermissionTo 函数可以接受字符串或 Permission 对象。

保存的权限和角色也注册到 Illuminate\Auth\Access\Gate 类。

hncore_user()->can('edit articles');

使用 blade 指令

此包还添加了 Blade 指令以验证当前登录用户是否具有给定列表中的所有或任何角色。

@role('writer')
    I\'m a writer!
@else
    I\'m not a writer...
@endrole
@hasrole('writer')
    I\'m a writer!
@else
    I\'m not a writer...
@endhasrole
@hasanyrole(Role::all())
    I have one or more of these roles!
@else
    I have none of these roles...
@endhasanyrole
@hasallroles(Role::all())
    I have all of these roles!
@else
    I don\'t have all of these roles
@endhasallroles

您可以使用 Laravel 的原生 @can 指令来检查用户是否有特定的权限。

在 CRUD 控制器中使用权限

CRUD 控制器有方法动态允许或拒绝访问操作。$this->crud->allowAccess() 和 $this->crud->denyAccess() 方法控制这些

表单的导航按钮显示为添加、编辑、删除等
安全访问保护器，如果没有权限则返回 403 禁止错误。

在大多数情况下，您应该单独使用 access 和 permission。但如果您想将它们链接在一起，以便“权限”赋予“访问”，这里是如何做到这一点的示例。提醒：权限可以直接分配给用户，也可以通过角色分配。

定义 CrudPermissionTrait

namespace App\Traits;

use Backpack\CRUD\app\Library\CrudPanel\CrudPanelFacade as CRUD;

/**
 * CrudPermissionTrait: use Permissions to configure Backpack
 */
trait CrudPermissionTrait
{
    // the operations defined for CRUD controller
    public array $operations = ['list', 'show', 'create', 'update', 'delete'];


    /**
     * set CRUD access using spatie Permissions defined for logged in user
     *
     * @return void
     */
    public function setAccessUsingPermissions()
    {
        // default
        $this->crud->denyAccess($this->operations);

        // get context
        $table = CRUD::getModel()->getTable();
        $user = request()->user();

        // double check if no authenticated user
        if (!$user) {
            return; // allow nothing
        }

        // enable operations depending on permission
        foreach ([
            // permission level => [crud operations]
            'see' => ['list', 'show'], // e.g. permission 'users.see' allows to display users
            'edit' => ['list', 'show', 'create', 'update', 'delete'], // e.g. 'users.edit' permission allows all operations
        ] as $level => $operations) {
            if ($user->can("$table.$level")) {
                $this->crud->allowAccess($operations);
            }
        }
    }
}

在此示例中，在任何 CrudController、UserCrudController 中使用上述 CrudPermissionTrait 特性。

namespace App\Http\Controllers\Admin;

use Backpack\PermissionManager\app\Http\Controllers\UserCrudController as BackpackUserCrudController;

class UserCrudController extends BackpackUserCrudController
{
    use \App\Traits\CrudPermissionTrait;

    public function setup()
    {
        parent::setup();
        $this->setAccessUsingPermissions();
    }
}

现在确保路由使用正确的控制器

(3.A) 如在自定义 UserCrudController 中解释的那样将包控制器绑定到您的控制器

$this->app->bind(
    \Backpack\PermissionManager\app\Http\Controllers\UserCrudController::class, // package controller
    \App\Http\Controllers\Admin\UserCrudController::class // the controller using CrudPermissionTrait
);

(3.B) 如在覆盖功能中解释的那样在您的 routes/hncore/permissionmanager.php 文件中定义路由

Route::group([
    'namespace'  => 'App\Http\Controllers\Admin', // the new namespace
    'prefix'     => config('hncore.base.route_prefix', 'admin'),
    'middleware' => ['web', hncore_middleware()],
], function () {
    // the adapted controllers
    Route::crud('user', 'UserCrudController');
    // Route::crud('role', 'RoleCrudController');
});
Route::group([
    'namespace'  => '\Backpack\PermissionManager\app\Http\Controllers', // the original namespace
    'prefix'     => config('hncore.base.route_prefix', 'admin'),
    'middleware' => ['web', hncore_middleware()],
], function () {
    // to original controllers
    // not modified yet in this example
    Route::crud('permission', 'PermissionCrudController');
    Route::crud('role', 'RoleCrudController');
});

您可能希望使用 PermissionSeeder 来自动将权限填充到 permission 表中，与您的代码相对应。以下是一个示例

namespace Database\Seeders;

use App\Models\User;
use Illuminate\Database\Seeder;
use Backpack\PermissionManager\app\Models\Permission;
use Backpack\PermissionManager\app\Models\Role;

class PermissionSeeder extends Seeder
{
    /**
     * Run the database Permission seed.

     * Permissions are fixed in code and are seeded here.
     * use 'php artisan db:seed --class=PermissionSeeder --force' in production
     *
     * @return void
     */
    public function run()
    {
        // create permission for each combination of table.level
        collect([ // tables
            'users',
            'roles',
        ])
            ->crossJoin([ // levels
                'see',
                'edit',
            ])
            ->each(
                fn (array $item) => Permission::firstOrCreate([
                    'name' => implode('.', $item),
                ])
                    ->save()
            )
            //
        ;
        User::first()
            ->givePermissionTo(['users.edit']);
    }
}

在生产环境中使用 php artisan db:seed --class=PermissionSeeder --force

从 3.x 升级到 4.x

要从 PermissionManager 3.x 升级到 4.x

升级到 spatie/laravel-permission 2.28.2+ - 请注意数据库已更改，并且它们没有提供更改的跟踪
在您的 composer.json 文件中要求 hncore/permissionmanager 版本 4.0.*
删除您的旧文件 config/hncore/permissionmanager.php；
按照上面的安装步骤操作；

如果您正在升级到Laravel 8版本，请注意，User模型可能已从App\User::class移动到App\Models\User::class，请检查您的配置是否与该更改兼容 config/hncore/permissionmanager.php。

变更日志

有关最近更改的更多信息，请参阅变更日志。

覆盖功能

如果您需要修改项目中的此功能

创建一个 routes/hncore/permissionmanager.php 文件；该包将识别该文件，并加载您的路由文件，而不是包中的路由文件；
创建扩展包中模型的控制器/模型，并在您的新路由文件中使用它们；
修改新控制器/模型中的任何内容；

在创建自己的控制器、种子文件时，请确保使用 BackpackUser 模型，而不是应用中的 User 模型。最简单的方法是使用 config('hncore.base.user_model_fqn')，它将完全限定命名空间中的用户模型拉入，如您的 config/hncore/base.php 中定义。您可能需要使用 $model = config('hncore.base.user_model_fqn'); $model = new $model; 实例化它，以便执行如 $model->where(...) 这样的操作。

贡献

有关详细信息，请参阅贡献指南。

安全

如果您发现任何安全相关的问题，请通过电子邮件tabacitu@hncoreforlaravel.com联系，而不是使用问题跟踪器。

请 订阅 Backpack Newsletter，以便了解任何安全更新、重大更改或主要功能。我们每 1-2 个月发送一封电子邮件。

鸣谢

Marius Constantin - 首席开发者
Cristian Tabacitu - 维护者
所有贡献者

许可

Backpack 非商业用途免费，商业用途49欧元/项目。请参阅许可文件和hncoreforlaravel.com以获取更多信息。

招聘我们

我们投入了超过50,000个小时来创建、打磨和维护Laravel上的管理面板。我们开发了电子商务、在线学习、ERP、社交网络、支付网关等等。我们对管理面板的工作经验如此丰富，以至于我们创建了这个细分市场中最受欢迎的软件之一——仅仅是从我们的项目中公开重复的内容。

如果您正在寻找一个开发者/团队来帮助您在Laravel上构建管理面板，那么您无需再寻找。您将很难找到比这更有经验、更有热情的人。这就是我们的事业。联系我们。让我们看看是否可以合作。

hncore / permissionmanager

维护者

详细信息