README

简介

Laravel Ban 简化了 Eloquent 模型的封禁管理。几分钟内让任何模型变得可封禁！

用例不仅限于 User 模型，任何 Eloquent 模型都可以被封禁：组织、团队、群体等。

内容

特性
安装
用法
集成
变更日志
升级
贡献
测试
安全
贡献者
替代方案
许可
关于 CyberCog

特性

模型可以有多个封禁。
保留在历史中的已封禁记录将被作为软删除记录删除。
大部分逻辑由 BanService 处理。
有中间件来防止被封禁的用户访问路由。
用例不仅限于 User 模型，任何 Eloquent 模型都可以被封禁。
在模型上触发 ban 和 unban 事件。
设计用于与 Laravel Eloquent 模型一起工作。
有 Laravel Nova 支持。
使用合约来保持高度的定制能力。
使用特性来获得开箱即用的功能。
遵循 PHP 标准建议
覆盖单元测试。

安装

首先，通过 Composer 引入包

composer require cybercog/laravel-ban

注册包

该包将自动注册自己。此步骤仅适用于 Laravel 5.4 或更早版本。

在 app/config/app.php 中包含服务提供者

'providers' => [
    Cog\Laravel\Ban\Providers\BanServiceProvider::class,
],

应用数据库迁移

最后，您需要发布并运行数据库迁移

php artisan vendor:publish --provider="Cog\Laravel\Ban\Providers\BanServiceProvider" --tag="migrations"
php artisan migrate

用法

准备可封禁模型

use Cog\Contracts\Ban\Bannable as BannableInterface;
use Cog\Laravel\Ban\Traits\Bannable;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable implements BannableInterface
{
    use Bannable;
}

准备可封禁模型的数据库表

可封禁模型必须有名为 banned_at 的 nullable timestamp 列。此值用作标志，简化了检查用户是否被封禁。如果您尝试使默认的 Laravel User 模型可封禁，可以使用以下示例。

创建一个新的迁移文件

php artisan make:migration add_banned_at_column_to_users_table

然后将以下代码插入到迁移文件中

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up(): void
    {
        Schema::table('users', function (Blueprint $table) {
            $table->timestamp('banned_at')->nullable();
        });
    }

    public function down(): void
    {
        Schema::table('users', function (Blueprint $table) {
            $table->dropColumn('banned_at');
        });
    }
};

可用方法

对实体应用封禁

$user->ban();

带原因注释对实体应用封禁

$user->ban([
    'comment' => 'Enjoy your ban!',
]);

对将被删除的实体应用封禁

$user->ban([
    'expired_at' => '2086-03-28 00:00:00',
]);

expired_at 属性可以是 \Carbon\Carbon 实例或任何可以被 \Carbon\Carbon::parse($string) 方法解析的字符串

$user->ban([
    'expired_at' => '+1 month',
]);

从实体中移除封禁

$user->unban();

在 unban 时，所有相关的封禁模型都将被软删除。

检查实体是否被封禁

$user->isBanned();

检查实体是否未被封禁

$user->isNotBanned();

手动删除过期的封禁

app(\Cog\Contracts\Ban\BanService::class)->deleteExpiredBans();

确定封禁是否是永久的

$ban = $user->ban();

$ban->isPermanent(); // true

或传递 null 值。

$ban = $user->ban([
   'expired_at' => null,
]);

$ban->isPermanent(); // true

确定封禁是否是临时的

$ban = $user->ban([
   'expired_at' => '2086-03-28 00:00:00',
]);

$ban->isTemporary(); // true

作用域

获取所有未被封禁的模型

$users = User::withoutBanned()->get();

获取被封禁和未被封禁的模型

$users = User::withBanned()->get();

仅获取被封禁的模型

$users = User::onlyBanned()->get();

作用域自动应用

要始终应用查询作用域，您可以在可封禁模型中定义 shouldApplyBannedAtScope 方法。如果方法返回 true，则默认隐藏所有被封禁的模型。

use Cog\Contracts\Ban\Bannable as BannableInterface;
use Cog\Laravel\Ban\Traits\Bannable;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable implements BannableInterface
{
    use Bannable;
    
    /**
     * Determine if BannedAtScope should be applied by default.
     *
     * @return bool
     */
    public function shouldApplyBannedAtScope()
    {
        return true;
    }
}

事件

如果实体被禁用，则触发 \Cog\Laravel\Ban\Events\ModelWasBanned 事件。

如果实体被解禁，则触发 \Cog\Laravel\Ban\Events\ModelWasUnbanned 事件。

中间件

此包包含路由中间件，用于防止被禁用的用户访问受保护的路由。

要在 app/Http/Kernel.php 文件的 $routeMiddleware 数组中定义新的中间件。

protected $routeMiddleware = [
    'forbid-banned-user' => \Cog\Laravel\Ban\Http\Middleware\ForbidBannedUser::class,
]

然后，在需要保护的任何路由和路由组中使用它。

Route::get('/', [
    'uses' => 'UsersController@profile',
    'middleware' => 'forbid-banned-user',
]);

如果要在受保护的路由访问时强制注销被禁用的用户，请使用 LogsOutBannedUser 中间件。

protected $routeMiddleware = [
    'logs-out-banned-user' => \Cog\Laravel\Ban\Http\Middleware\LogsOutBannedUser::class,
]

定时任务

在完成基本安装后，您可以使用 ban:delete-expired 命令。在大多数情况下，您可能希望安排这些命令，这样您就不必每次需要删除过期的禁用条目和解禁模型时都手动运行它。

可以像安排其他命令一样在 Laravel 的控制台内核中安排此命令。

// app/Console/Kernel.php

protected function schedule(Schedule $schedule)
{
    $schedule->command('ban:delete-expired')->everyMinute();
}

当然，上面代码中使用的时间只是一个示例。根据您的喜好进行调整。

集成

Laravel Nova 禁用

变更日志

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

升级

有关详细升级说明，请参阅升级。

贡献

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

测试

使用以下命令运行测试

vendor/bin/phpunit

安全

如果您发现任何安全问题，请通过电子邮件发送到 open@cybercog.su 而不是使用问题跟踪器。

贡献者

Laravel 禁用贡献者列表

替代方案

https://github.com/imanghafoori1/laravel-temp-tag

许可

Laravel 禁用 包是开源软件，根据 MIT 许可证由 Anton Komarev 许可。
胖老板在监狱里 图片由 Gan Khoon Lay 根据 Creative Commons 3.0 许可。

🌟 随时间推移的 Star 数

关于 CyberCog

CyberCog 是一个由爱好者组成的社交团体。研究产品 & 软件开发中的最佳解决方案是我们的热情。

cybercog / laravel-ban

维护者

详细信息