README

Smarticops 是一个 Laravel 包，允许管理员管理用户、角色和权限。

I - 功能

• 注册用户，认证
• 电子邮件确认和密码重置
• 访问控制列表：角色和权限
• 记录访问和行政操作

II - 要求

• Smarticops 目前需要 确切地 Laravel 版本 5.2.x
• 不能保证该包与 Laravel 的其他次要和主要版本兼容。

III - 安装

概述

• Smarticops 和 Laravel

  Smarticops 旨在在 Laravel 安装后立即安装。它使用并替换了 Laravel 提供的内置认证功能。
  特别地，因为该包已经包含了 Laravel 认证，所以您 不需要 输入 $ php artisan make:auth。

• 超级管理员

  有一个将在数据库中始终存在（系统记录）的用户，称为超级管理员。其 ID 为 1。它关联了一个名为 "sa" 的权限，这也是一个系统记录，将在数据库中永久存在。
  默认情况下，超级管理员是唯一可以访问管理界面并管理用户、权限和角色的用户。

• 依赖项

  该包需要 "laravelcollective/html" 用于 HTML 表单，以及 "guzzlehttp/guzzle" 用于电子邮件 API 驱动程序。

Laravel

首先，您需要一个全新的 Laravel 5.2 安装。

$ composer create-project --prefer-dist laravel/laravel=5.2.* <project-name> 

Smarticops

通过 Composer 简单完成包安装。首先，转到您的新项目目录。然后，让 Composer 安装该包。

$ cd <project-name>
$ composer require dvivier/smarticops

IV - 配置

Artisan 命令

Smarticops 定义了一个 Artisan 命令，旨在简化配置。

要使用此命令，请将以下提供者在您的 config/app.php 文件中添加

    // file : config/app.php
    
    'providers' => [
        /* ... */
        
        Dvivier\Smarticops\Providers\SmarticopsServiceProvider::class,
    
    ],

现在 Smarticops 服务提供程序已注册，该命令可用。

该命令将提示您所需的数据，并将修改一些文件。它将自动执行本节中描述的操作。在执行之前将打印每条命令行指令。

如果您想确切了解此命令的功能，可以查看 src/Console/Commands/SmarticopsSetupCommand 文件。

Note : This command has to be executed only once. It doesn't have to be executed when updating the package, except if it's clearly asked.

在运行命令之前，请确保您已正确配置了 .env 文件中的数据库访问，并且数据库服务器正在运行。

输入

$ php artisan smarticops:setup

并遵循说明。

• 当命令成功结束时，出现消息 'Smarticops 设置完成'，您现在可以跳转到 V - 使用 部分。

• 否则，或者如果您不想使用自动过程，请继续阅读本部分以获取手动说明。

Laravel

• 在您的 config/app.php 文件中添加以下提供者和别名

    // file : config/app.php
    
    'providers' => [
        /* ... */
        
        Collective\Html\HtmlServiceProvider::class,
        
        Dvivier\Smarticops\Providers\SmarticopsServiceProvider::class,
    
    ],
    
    'aliases' => [
        /* ... */
        
        'Form' => Collective\Html\FormFacade::class,
        'Html' => Collective\Html\HtmlFacade::class,
    ]

需要来自 Laravel Collective 社区组织的 Form 和 Html 组件，用于管理面板中的表单。

• 在 app/Providers/EventServiceProvider 文件中请求您的应用程序注册 Smarticops 的事件监听器

    class EventServiceProvider extends ServiceProvider
    {
    
        /**
         * The subscriber classes to register.
         *
         * @var array
         */
        protected $subscribe = [
            'Dvivier\Smarticops\Listeners\AuthEventListener',
        ];

用户模型

基本的 Laravel 安装提供了一个位于 app/User.php 的 User 类

    class User extends Authenticatable
    {

此类扩展了 Illuminate\Foundation\Auth\User 类，以及（间接地）Eloquent 模型。

您必须将此类扩展为 Dvivier\Smarticops\User 模型，而不是 Auth.User 类

    use Dvivier\Smarticops\User as SmarticopsUser;
    class User extends SmarticopsUser
    {

别担心，Smarticops的用户类已经继承自Illuminate\Foundation\Auth\User类，从而继承了Eloquent模型。

当您的应用程序需要用户类时，请使用这个App\User类。

请注意，即使您的应用程序不需要管理用户，您仍然需要进行此操作以确保认证正常工作。

Smarticops

Smarticops会在config/smarticops.php中添加一个配置文件。但您需要在.env文件中添加额外的配置变量

// file : .env
APP_NAME=

SUPERADMIN_FIRSTNAME=
SUPERADMIN_LASTNAME=
SUPERADMIN_EMAIL=
SUPERADMIN_PASSWORD=

您必须设置密码，否则将存在安全问题，因为默认密码（不是秘密）将被使用。

为了考虑，超级管理员密码必须在下一节运行迁移之前更改。

应用程序名称将在视图和电子邮件中使用。

在config/smarticops.php文件中，您将找到以下配置选项

• 日志路径

  Smarticops会每天生成一个不同的日志文件。您可以配置日志的基本文件名和位置

    'log_path' => 'logs/smarticops/smarticops',  
  

• 电子邮件确认超时

  出于安全原因，发送给用户以确认其电子邮件的令牌必须有一个超时，默认为1小时。此持续时间（以分钟为单位）可以在此设置

    'confirm_expire' => 60,
  

• 密码长度

  您可以根据您的安全策略调整密码的最小字符数。
  请记住，密码越短，越弱。

    'password' => [
            // minimum number of characters for passwords
            'min' => 8,
            ],
  

• 密码重置视图

  Smarticops提供了另一个用于密码重置电子邮件的视图。如果想要使用它，请更改您的config/auth.php文件中的此行

    //file : config/auth.php
      
    'passwords' => [
        'users' => [
            'provider' => 'users',
            //'email' => 'auth.emails.password',            // change this line
            'email' => 'smarticops::auth.emails.password',  // into this one
            'table' => 'password_resets',
            'expire' => 60,
        ],
  

  ],

迁移和填充

• 准备

在安装包之后，Smarticops需要的迁移被添加到database/migrations，并在database/seeds/SmarticopsSeeder.php中添加了一个填充类。迁移将创建表，填充类将插入系统记录（与超级管理员相关的记录）。

为了做到这一点，在基础database/seeds/DatabaseSeeder文件中调用填充类

    public function run()
    {
        /* ... */
        $this->call(SmarticopsSeeder::class);
    }

根据您的应用程序需求，如有必要，调整迁移代码（特别是针对users表的代码）。您必须在运行迁移之前更改超级管理员密码，请参阅上面的配置部分。

在运行迁移之前，如果存在，请删除两个原始迁移文件，因为它们将被Smarticops的迁移文件替换

$ rm database/migrations/2014_10_12_000000_create_users_table.php
$ rm database/migrations/2014_10_12_100000_create_password_resets_table.php

• 运行

要运行迁移并填充系统记录，在项目目录中键入

$ php artisan migrate --seed

您必须使用--seed选项：它将在数据库中插入系统记录。

如果出现错误或更改了这些迁移文件中的某些内容，您可以删除并重新创建表（所有现有数据将被删除！）

$ php artisan migrate:refresh --seed

再次提醒，别忘了使用--seed选项。

V - 用法

关于权限名称

约束

每个权限都有一个唯一的名称，描述其本身。例如

create.company

权限名称只能包含字母、数字、短划线“-”、点“.”和下划线“_”。
权限名称是区分大小写的。

约定

该包不需要使用特定的格式来指定权限名称。
然而，建议选择一个约定，并在应用程序中的每个权限中使用相同的格式。
建议的格式是<action>.<object>。

构建网页

在构建网页时，有一些信息和控件仅限于具有特定权限或角色的用户。

要检查已登录用户是否具有特定权限，请使用

Auth::user()->hasPermission('code')

要检查他是否具有特定角色

Auth::user()->hasRole('RoleName')
// You can also use the alias :
Auth::user()->is('RoleName')

使用Laravel的Blade指令的一个示例，以限制信息/控件的访问权限，仅限于具有特定权限的用户

@if (Auth::user()->hasPermission('view.company.name'))
    <span>Company Name</span>
@endif

管理面板

服务器运行后，超级管理员可以在<domain>/admin处访问管理界面。

• 权限

请参阅上方的权限说明部分，了解权限命名和约定。在分配给用户和角色之前，必须创建权限。
每个权限都有一个描述性文本，明确其目的。

• 角色

可以将角色分配给用户，以明确其在应用程序中的角色。
用户可以分配零个、一个或多个角色。
角色名称只能包含字母、数字和下划线 "_"，并且区分大小写。每个角色都有一个描述性文本，明确其目的。

然后您可以为该角色分配一些权限。
选中的权限将随后在将此角色分配给用户时被提出。

请注意，更改角色的权限对拥有此角色的用户没有任何影响。

• 用户

用户编辑表单允许管理员为用户分配角色和权限。

通过角色选择自动填充权限

勾选您想分配给用户的角色复选框。
每次勾选一个角色，都会自动勾选对应该角色的所有权限。

选择角色后，您可以选择并调整该用户的特定权限。

地区

可以通过访问url <domain>/<locale>来切换地区，例如

http://example.com/fr

此外，基于Laravel默认页面的包页面标题栏包含易于更改地区的链接。

VI - 文档

文档由phpDocumentor从DockBlocks生成。
您可以通过在您的public目录中创建符号链接来使其可访问

$ cd public
$ ln -s ../vendor/dvivier/smarticops/doc smarticops-doc

然后您可以在<domain>/smarticops-doc/index.html访问Smarticops文档

VII - 更新日志

您可以在此处找到它。

VIII - 贡献

欢迎贡献！
请随时报告错误并建议修正和改进。使用Bitbucket的问题跟踪器和拉取请求。
我将非常感激对我的工作的反馈，特别是关于创建Laravel包，因为这是我第一个。

您可以在src/lang/<locale>/<file>目录中将包翻译成其他语言。
如果您发现安全问题，请通过d.vivier@smartic.ca与我联系。
贡献受Contributor Covenant的约束和保护，并将得到充分认可。

IX - 其他

• 该包目前可用英语和法语。
• 用户、权限和角色（模型和控制台）的测试类可供在./tests中使用phpunit运行。
• 该包遵循semver.org中描述的语义版本化2.0.0规范。

X - 许可证

MIT许可证（MIT）。有关更多信息，请参阅LICENSE。

XI - 致谢

• David Vivier d.vivier@smartic.ca 代表 Smartic.ca