README

此包允许您轻松管理Laravel应用的邀请码。

赞助我的工作！

如果您认为此包在某个方面帮助了您，您可以在GitHub上赞助我！

文档

• 安装
• 使用
  • 创建邀请码
    • 设置邀请码的过期日期
    • 限制某些特定用户的使用
    • 设置邀请码的最大允许使用次数
  • 创建多个邀请码
  • 兑换邀请码
  • 在不触发事件的情况下兑换邀请码
• 自定义邀请码的生成方式
• 扩展Invite模型
• 处理邀请码异常
• 使用Artisan命令
• 测试
• 贡献
• 变更日志
• 许可协议

安装

要开始使用Laravel邀请码，请使用Composer将包添加到项目的依赖中

composer require mateusjunges/laravel-invite-codes

或者在composer.json的require部分添加以下行

{
    "require": {
        "mateusjunges/laravel-invite-codes": "^2.0",
    }
}

然后运行composer install。

此包所需的所有迁移已经包含在内。如果您需要自定义表，您可以使用以下命令发布它们

php artisan vendor:publish --provider="Junges\InviteCodes\InviteCodesServiceProvider" --tag="invite-codes-migrations"

并将custom_migrations的配置设置为true，默认为false。

'custom_migrations' => true,

迁移发布后，您可以通过运行迁移来在数据库中创建表

php artisan migrate

如果您更改了迁移中的表名，请发布配置文件并更新表数组。您可以使用以下命令发布配置文件

php artisan vendor:publish --provider="Junges\InviteCodes\InviteCodesServiceProvider" --tag="invite-codes-config"

发布后，config/invite-codes.php配置文件包含以下内容

<?php

return [
    /*
    |--------------------------------------------------------------------------
    |  Models
    |--------------------------------------------------------------------------
    |
    | When using this package, we need to know which Eloquent Model should be used
    | to retrieve your invites. Of course, it is just the basics models
    | needed, but you can use whatever you like.
    |
    */
    'models' => [
        'invite_model' => \Junges\InviteCodes\Models\Invite::class,
    ],

    /*
    |--------------------------------------------------------------------------
    | Tables
    |--------------------------------------------------------------------------
    | Specify the basics authentication tables that you are using.
    | Once you required this package, the following tables are
    | created by default when you run the command
    |
    | php artisan migrate
    |
    | If you want to change this tables, please keep the basic structure unchanged.
    |
    */
    'tables' => [
        'invites_table' => 'invites',
    ],

    /*
    |--------------------------------------------------------------------------
    | User
    |--------------------------------------------------------------------------
    | To use the ProtectedByInviteCode middleware provided by this package, you need to
    | specify the email column you use in the model you use for authentication.
    | If not specified, only invite code with no use restrictions can be used in this middleware.
    |
    */
    'user' => [
        'email_column' => 'email',
    ],

    /*
    |--------------------------------------------------------------------------
    | Custom migrations
    |--------------------------------------------------------------------------
    | If you want to publish this package migrations and edit with new custom columns, change it to true.
    */
    'custom_migrations' => false,
];

使用

此包提供了一个名为ProtectedByInviteCodeMiddleware的中间件。如果您想使用它来保护路由，您需要在app/Http/Kernel.php文件中的$routeMiddleware数组中注册它

$routeMiddleware = [
    'protected_by_invite_codes' => ProtectedByInviteCodeMiddleware::class,
];

现在您可以使用中间件规则来保护您的路由

Route::get('some-route', function() {
    //
})->middleware('protected_by_invite_codes');

您也可以将其添加到控制器中的__construct()方法中

public function __construct()
{
    $this->middleware('protected_by_invite_codes');
}

注意 此中间件期望在请求的invite_code键中找到邀请码。

创建邀请码

要创建新的邀请码，您必须使用InviteCodes外观。以下是一个简单的示例

$invite_code = \Junges\InviteCodes\Facades\InviteCodes::create()
    ->expiresAt('2020-02-01')
    ->maxUsages(10)
    ->restrictUsageTo('contato@mateusjunges.com')
    ->save();

上述代码将创建一个新的邀请码，只能由具有指定电子邮件contato@mateusjunges.com的登录用户使用10次。

您可以使用以下方法与InviteCodes外观一起使用

设置邀请码的过期日期

要设置邀请码的过期日期，您可以使用以下方法之一

• expiresAt()：此方法接受一个格式为yyyy-mm-dd的日期字符串或Carbon实例，并将过期日期设置为指定的日期。
• expiresIn()：此方法接受一个整数，并将过期日期设置为当前日期加上指定的天数。

限制某些特定用户的使用

要限制邀请码的使用，您可以使用restrictUsageTo()方法，并传入将能够使用此邀请码的用户email。

设置邀请码的最大允许使用次数

如果您希望邀请码的使用次数有限，您可以使用maxUsages()方法设置最大使用次数，并传递一个表示允许使用次数的整数。

创建多个邀请码

如果您想使用相同的配置创建多个邀请码，可以使用make()方法。此方法会生成指定数量的邀请码。例如：

\Junges\InviteCodes\Facades\InviteCodes::create()
    ->maxUsages(10)
    ->expiresIn(30)
    ->make(10);

上面的代码将创建10个新的邀请码，每个邀请码可以使用10次，并且从现在起30天后将过期。

兑换邀请码

要兑换邀请码，可以使用redeem方法。

\Junges\InviteCodes\Facades\InviteCodes::redeem('YOUR-INVITE-CODE');

当任何邀请码被兑换时，将触发InviteRedeemedEvent事件。

在不触发事件的情况下兑换邀请码

如果您想在兑换邀请码时不触发InviteRedeemedEvent事件，可以使用withoutEvents()方法。

\Junges\InviteCodes\Facades\InviteCodes::withoutEvents()->redeem('YOUR-INVITE-CODE');

自定义邀请码的生成方式

默认情况下，此包生成一个随机的16字符字符串。有时，您可能想自定义邀请码的生成方式，例如添加前缀或进行其他操作。

如果您需要自定义邀请码的生成方式，可以在服务提供者中添加对InviteCodes外观的createInviteCodesusing方法的调用。

\Junges\InviteCodes\Facades\InviteCodes::createInviteCodeUsing(static function () {
    return 'THIS-IS-MY-INVITE-'.\Illuminate\Support\Str::random(); 
});

从现在起，您的所有邀请都将具有THIS-IS-MY-INVITE-前缀。

此外，该包本身将处理重复邀请，因此您无需自己处理。

扩展Invite模型

\Junges\InviteCodes\Models\Invite是完全可扩展和可替换的。您可以扩展或创建一个新模型来替换默认模型，您需要做的就是实现\Junges\InviteCodes\Contracts\InviteContract接口，该接口包含此包运行所需的一些必需方法。

实现合约后，您需要更改config/invite-codes.php中的models.invite_model配置值。

处理邀请码异常

如果您想覆盖默认的403响应，可以使用laravel异常处理器捕获异常。

public function render($request, Exception $exception)
{
    if ($exception instanceof \Junges\InviteCodes\Exceptions\InviteWithRestrictedUsageException) {
        //
    }
    if ($exception instanceof \Junges\InviteCodes\Exceptions\ExpiredInviteCodeException) {
        //
    }
    if ($exception instanceof \Junges\InviteCodes\Exceptions\DuplicateInviteCodeException) {
        //
    }
    if ($exception instanceof \Junges\InviteCodes\Exceptions\InvalidInviteCodeException) {
        //
    }
    if ($exception instanceof \Junges\InviteCodes\Exceptions\UserLoggedOutException) {
        //
    }
    if ($exception instanceof \Junges\InviteCodes\Exceptions\InviteMustBeAbleToBeRedeemedException) {
        //
    }
    if ($exception instanceof \Junges\InviteCodes\Exceptions\SoldOutException) {
        //
    }
    if ($exception instanceof \Junges\InviteCodes\Exceptions\RouteProtectedByInviteCodeException) {
        //
    }
    
    return parent::render($request, $exception);
}

使用Artisan命令

此包还提供了一个命令，可以从数据库中删除所有过期的邀请。您可以像这样使用它：

\Illuminate\Support\Facades\Artisan::call('invite-codes:clear');

删除所有过期的邀请后，将触发DeletedExpiredInvitesEvent事件。

测试

运行composer test来测试此包。

贡献

感谢您考虑为Laravel邀请码包做出贡献！贡献指南可以在这里找到。

变更日志

请参阅变更日志以获取有关此包变更的更多信息。

许可协议

Laravel邀请码包是开源软件，受MIT许可证许可。请参阅许可证文件以获取更多信息。