README

Laravel 用户的积分包，可用于实时支持奖励、忠诚度或经验点。

它是如何工作的？

每个积分都有一个动作文件，当调用该文件时，将为特定积分解析模型。

动作文件用于将积分分配给用户。

我们使用动作（文件）的原因是

这使得跟踪积分变得容易。
更容易切换积分，例如，您希望用户完成课程后从 50 积分增加到 100 积分，您只需创建一个新的动作并替换旧的即可。

安装

使用 composer 安装包

composer require miracuthbert/laravel-royalty

设置

该包利用 Laravel 自动发现，因此无需手动添加 ServiceProvider。

如果您不使用自动发现，请将 ServiceProvider 添加到 config/app.php 文件中的 providers 数组中

Miracuthbert\Royalty\RoyaltyServiceProvider::class

然后您必须发布 config 和 migrations 文件。

使用设置命令

您可以使用命令行中的 royalty:setup 完成所有必要的设置

php artisan royalty:setup

在迁移数据库之前，请更新 "config/royalty.php" 中的键。您可以为积分设置要使用的模型。

如果您想重置 config 或 migrations，请在控制台中使用以下命令

发布配置

php artisan vendor:publish --provider=Miracuthbert\Royalty\RoyaltyServiceProvider --tag=royalty-config

在配置中设置用户 model 键，以指示要使用的用户模型

发布迁移

php artisan vendor:publish --provider=Miracuthbert\Royalty\RoyaltyServiceProvider --tag=royalty-migrations

在迁移数据库之前，请确保已设置配置中的用户 model 键

发布 Vue 组件

包含一个简单的 Vue 组件，用于在用户获得积分时实时显示其积分。有关更多信息，请参阅使用说明下的实时部分。

php artisan vendor:publish --provider=Miracuthbert\Royalty\RoyaltyServiceProvider --tag=royalty-components

该包不会绑定您使用特定的前端框架来监听触发的事件，因此请随意实验。

使用说明

设置用户模型

首先，在配置中设置用户 model 键。

然后在相应的模型中添加 CollectsPoints 特性。

use CollectsPoints;

创建积分

让我们以用户完成课程中的课程为例，我们可以创建一个 CompletedLesson。

使用控制台命令

您可以使用以下命令

php artisan royalty:action CompletedLesson

// with specific namespace
php artisan royalty:action Course\\CompletedLesson

这将创建一个位于 app 目录下 Royalty\Actions 文件夹中的动作文件，或者根据 config/royalty.php 文件中指定的相应文件。

它将包括

key 方法，该方法具有唯一的密钥，该密钥将用于从 Action 名称的 slug 识别创建的。

您还可以使用这些选项与命令一起使用

--key 以覆盖从类名生成的密钥。
--name 在数据库中创建积分（与 points 选项一起使用）。
--points 给定动作的积分。
--description 积分的描述。

如果您仅创建了积分文件，则需要创建一个数据库中的记录，该记录引用动作。

参阅数据库中添加积分部分，了解如何在数据库中添加积分。

手动创建

要手动创建积分，您需要创建一个action文件，并在数据库中创建一个引用该操作的record。

创建操作文件

要创建积分操作文件，您需要创建一个继承自Miracuthbert\Royalty\Actions\ActionAbstract的类。

namespace App\Royalty\Actions;

use Miracuthbert\Royalty\Actions\ActionAbstract;

class CompletedLesson extends ActionAbstract
{
    /**
     * Set the action key.
     *
     * @return mixed
     */
    public function key()
    {
        return 'completed-lesson';
    }
}

数据库中添加积分

use Miracuthbert\Royalty\Models\Point;

$point = Point::create([
    'name' => 'Completed Lesson',
    'key' => 'completed-lesson',
    'description' => 'Reward for completing a lesson',
    'points' => 100,
]);

您还可以使用，例如种子器来批量创建积分。

$points = [
    [
        'name' => 'Completed Lesson',
        'key' => 'completed-lesson',
        'points' => 100,
    ],
    [
        'name' => 'Completed Course',
        'key' => 'completed-course',
        'points' => 500,
    ],
    
    // grouped
    [
        'name' => 'Grades',
        'key' => 'grades',
        'points' => 100,
        'children' => [
            [
                'name' => 'Excellent',
                'points' => 100,
            ],
            [
                'name' => 'Very Good',
                'points' => 90,
            ],
            [
                'name' => 'Good',
                'points' => 80,
            ],
        ],
    ],
];

foreach ($points as $point) {
    $exists = Point::where('key', $point['key'])->first();

    if (!$exists) {
        Miracuthbert\Royalty\Models\Point::create($point);
    }
}

分配积分

要分配积分，只需在用户实例上调用givePoints方法。

// user instance
$user = User::find(1);
$user->givePoints(new CompletedLesson());

// using request user
$request->user()->givePoints(new CompletedLesson());

// using auth user
auth()->user()->givePoints(new CompletedLesson());

获取用户的积分

要获取用户积分，只需在用户实例上调用points方法，并链接以下方法之一：

number：原始积分值
number：格式化的数字值，例如1,000、1,000,000
shorthand：格式化的字符串值，例如1k、10.5k、1m

// user instance
$user = User::find(1);
$user->points()->number();
$user->points()->shorthand();

// using request user
$request->user()->points()->number();
$request->user()->points()->shorthand();

// using auth user
auth()->user()->points()->number();
auth()->user()->points()->shorthand();

实时

每次给用户分配积分时，都会触发一个PointsGiven事件。

广播频道

它广播到users（私有）频道，该频道由config/royalty.php中broadcast键的channel设置。

该频道应位于路由下的channels文件中，或您各自的用户频道

频道路由的示例

Broadcast::channel('users.{id}', function ($user, $id) {
    return (int) $user->id === (int) $id;
});

监听事件

然后，您可以使用points-given或config/royalty.php中broadcast下name键的设置值来监听它。

使用Laravel Echo和Vue.js的示例

    Echo.private(`users.${this.userId}`)
        .listen('.points-given', (e) => {
            this.point = e.point
            this.userPoints = e.user_points
        })

Vue组件

该包包含一个Vue组件。使用以下命令发布它：

php artisan vendor:publish --provider=Miracuthbert\Royalty\RoyaltyServiceProvider --tag=royalty-components

发布的组件将被放置在您的resources/js/components目录中。一旦组件发布，您应该在resources/js/app.js文件中注册它们

Vue.component('royalty-badge', require('./components/royalty/RoyaltyBadge.vue').default);

注册组件后，请确保运行npm run dev以重新编译您的资源。一旦您重新编译了资源，就可以将组件拖放到应用程序的模板中开始使用

<royalty-badge
  :user-id="{{ auth()->user()->id }}"
  initial-points="{{ auth()->user()->points()->shorthand() }}"
/>

控制台命令

包内有三个命令

royalty:setup：用于设置包文件
royalty:action：用于创建操作文件和积分
royalty:actions：用于列出积分及其相关操作

安全漏洞

如果您发现安全漏洞，请通过miracuthbert@gmail.com发送电子邮件给Cuthbert Mirambo。所有安全漏洞都将得到及时处理。

致谢

Cuthbert Mirambo

许可证

该项目是开源软件，许可协议为MIT许可证。

miracuthbert / laravel-royalty

维护者

详细信息