README

使用jawabapp/laravel-gamify快速在您的Laravel应用中添加声誉积分和徽章。

安装

1 - 您可以通过Composer安装此软件包

$ composer require jawabapp/laravel-gamify

2 - 如果您在Laravel 5.4或更低版本上安装，您需要手动通过在config/app.php的providers数组中添加它来注册Service Provider。

'providers' => [
    //...
    Jawabapp\Gamify\GamifyServiceProvider::class
]

Laravel 5.5及以上版本会自动注册。

发布配置文件

php artisan vendor:publish --provider="Jawabapp\Gamify\GamifyServiceProvider" --tag="config"

3 - 现在发布gamify表的迁移

php artisan vendor:publish --provider="Jawabapp\Gamify\GamifyServiceProvider" --tag="migrations"

注意：它将为reputations、badges和user_badges表生成迁移，并添加存储积分的users表的声誉字段迁移，您需要运行composer require doctrine/dbal以支持删除和添加列。

php artisan migrate

如果您的收款人（将获得积分的模型）模型是App\User，则不需要在config/gamify.php中进行任何更改。

入门

1. 在软件包安装后，现在将Gamify特质添加到App\User模型或任何充当应用中用户的模型。

use Jawabapp\Gamify\Gamify;
use Illuminate\Notifications\Notifiable;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    use Notifiable, Gamify;

⭐️ 👑 声誉积分

2 下一步是创建积分。

php artisan gamify:point PostCreated

它将在app/Gamify/Points/文件夹下创建一个名为PostCreated的PointType类。

<?php

namespace App\Gamify\Points;

use Jawabapp\Gamify\PointType;

class PostCreated extends PointType
{
    /**
     * Number of points
     *
     * @var int
     */
    public $points = 20;

    /**
     * Point constructor
     *
     * @param $subject
     */
    public function __construct($subject)
    {
        $this->subject = $subject;
    }

    /**
     * User who will be receive points
     *
     * @return mixed
     */
    public function payee()
    {
        return $this->getSubject()->user;
    }
}

给用户积分

现在在创建帖子时，您可以在控制器中这样给予积分

$user = $request->user();
$post = $user->posts()->create($request->only(['title', 'body']));

// you can use helper function
givePoint(new PostCreated($post));

// or via HasReputation trait method
$user->givePoint(new PostCreated($post));

撤销已给予的积分

在某些情况下，您可能想要撤销已给予的积分，例如，用户删除了他的帖子。

// via helper function
undoPoint(new PostCreated($post));
$post->delete();

// or via HasReputation trait method
$user->undoPoint(new PostCreated($post));
$post->delete();

您也可以在辅助函数givePoint(new PostCreated($post, $user))中传递第二个参数作为$user，默认为auth()->user()。

专业提示 👌 您还可以挂钩Eloquent模型事件并在created事件上给予积分。同样，可以使用deleted事件来撤销积分。

获取总声誉

要获取用户总声誉，您可以使用$user->getPoints($formatted = false)方法。可选地，您可以通过传递$formatted = true来获取声誉作为1K+、2K+等。

// get integer point
$user->getPoints(); // 20

// formatted result
$user->getPoints(true); // if point is more than 1000 1K+

获取声誉历史

由于软件包存储所有声誉事件日志，因此您可以通过以下关系获取声誉历史

foreach($user->reputations as $reputation) {
    // name of the point type
    $reputation->name

    // payee user
    $reputation->payee

    // how many points
    $reputation->point

    // model on which point was given
    $reputation->subject
}

如果您想要获取对subject模型的所有积分。您应该在模型中定义morphMany关系。例如，在帖子模型上。

    /**
     * Get all the post's reputation.
     */
    public function reputations()
    {
        return $this->morphMany('Jawabapp\Gamify\Reputation', 'subject');
    }

现在您可以通过$post->reputations获取所有给予帖子的声誉。

配置积分类型

积分收款人

在大多数情况下，您传递到积分new PostCreated($post)中的主题模型将与用户通过某种关系相关联。

class PostCreated extends PointType
{
    public $points = 20;

    protected $payee = 'user';

    // dont need this, payee property will return subject realtion
    // public function payee()
    // {
    //    return $this->getSubject()->user;
    // }
}

动态积分

如果积分基于某些逻辑计算，则应添加getPoints()方法来进行计算，并始终返回一个整数。

class PostCreated extends PointType
{
    protected $payee = 'user';

    public function getPoints()
    {
        return $this->getSubject()->user->getPoint() * 10;
    }
}

积分限定符

这是一个可选方法，它返回布尔值。如果为真，则此积分将被给予，否则将被忽略。这对于动态确定积分资格非常有用。

防止重复声誉

默认情况下，您可以为相同的模型主题多次给予积分。但您可以通过在类中添加以下属性来防止它

class PostCreated extends PointType
{
    // prevent duplicate point
    public $allowDuplicates = false;

    protected $payee = 'user';
}

声誉变更事件

当用户积分发生变化时，会触发 \Jawabapp\Gamify\Events\ReputationChanged 事件，该事件具有以下有效负载

class ReputationChanged implements ShouldBroadcast {

    ...
    public function __construct(Model $user, int $point, bool $increment)
    {
        $this->user = $user;
        $this->point = $point;
        $this->increment = $increment;
    }
}

此事件也会在配置的频道名称中广播，因此您可以通过前端通过socket监听它以实时更新积分。

🏆 🏅 成就徽章

与积分类型类似，您有徽章。可以根据排名或其他标准将徽章授予用户。您应该在 config/gamify.php 中定义徽章级别。

// All the levels for badge
'badge_levels' => [
    'beginner' => 1,
    'intermediate' => 2,
    'advanced' => 3,
],

// Default level
'badge_default_level' => 1

徽章级别存储为 tinyint，请保持值为整数。在需要排序时这将更快。

创建徽章

要生成徽章，您可以运行以下提供的命令

php artisan gamify:badge FirstContribution

它将在 app/Gamify/Badges/ 文件夹下创建名为 FirstContribution 的 BadgeType 类。

<?php

namespace App\Gamify\Badges;

use Jawabapp\Gamify\BadgeType;

class FirstContribution extends BadgeType
{
    /**
     * Description for badge
     *
     * @var string
     */
    protected $description = '';

    /**
     * Check is user qualifies for badge
     *
     * @param $user
     * @return bool
     */
    public function qualifier($user)
    {
        return $user->getPoints() >= 1000;
    }
}

如您所见，此徽章具有 $description 字段和 qualifier($user) 方法。Gamify 包会监听任何积分变化，并将用户与所有可用徽章进行比较，并授予所有符合资格的徽章。

更改徽章名称

默认情况下，徽章名称将是徽章类名称的漂亮版本。在上面的例子中，它将是 First Contribution。您可以通过在类中添加 $name 属性来更改它，或者如果您想动态命名，可以覆盖 getName() 方法。

更改徽章图标

与名称类似，您可以通过 $icon 属性或通过 getIcon() 方法来更改它。在类上定义图标时，您需要指定带有扩展名的完整路径。config/gamify.php 文件夹中的 badge_icon_folder 和 badge_icon_extension 不会使用。

更改徽章级别

您有相同的 $level 属性或通过 getLevel() 方法来更改它。它类似于徽章的类别，所有徽章都在 config/gamify.php 中定义为 badge_levels。如果没有指定，则将使用配置中的 badge_default_level。

警告 ⚠️ 不要忘记在运行 php artisan cache:forget gamify.badges.all 以添加或删除徽章时清除缓存。⚠️

获取用户的徽章

您可以通过调用 $user->badges 来获取用户的徽章，它将返回用户的徽章集合。

不使用徽章

如果您的应用程序不需要徽章，则应仅使用 HasReputations 特性而不是 Gamify。

不使用声誉历史记录

如果您不需要维护所有已奖励的积分历史记录，只想增加和减少声誉，则应使用以下方法

// to add point
$user->addPoint($point = 1);

// to reduce point
$user->reducePoint($point = 1);

// to reset point back to zero
$user->resetPoint();

您不需要为这一点生成点类。

配置 Gamify

<?php

return [
    // Model which will be having points, generally it will be User
    'payee_model' => '\App\User',

    // Reputation model
    'reputation_model' => '\Jawabapp\Gamify\Reputation',

    // Allow duplicate reputation points
    'allow_reputation_duplicate' => true,

    // Broadcast on private channel
    'broadcast_on_private_channel' => true,

    // Channel name prefix, user id will be suffixed
    'channel_name' => 'user.reputation.',

    // Badge model
    'badge_model' => '\Jawabapp\Gamify\Badge',

    // Where all badges icon stored
    'badge_icon_folder' => 'images/badges/',

    // Extention of badge icons
    'badge_icon_extension' => '.svg',

    // All the levels for badge
    'badge_levels' => [
        'beginner' => 1,
        'intermediate' => 2,
        'advanced' => 3,
    ],

    // Default level
    'badge_default_level' => 1
];

更改日志

有关最近更改的更多信息，请参阅 CHANGELOG。

测试

该包包含一些集成/冒烟测试，使用 Orchestra 设置。可以通过 phpunit 运行这些测试。

$ composer test

贡献

有关详细信息，请参阅 CONTRIBUTING。

安全

如果您发现任何与安全相关的漏洞，请通过电子邮件 saquibweb@gmail.com 而不是使用问题跟踪器。

鸣谢

Mohd Saqueib Ansari（作者）

关于 QCode.in

QCode.in（《https://www.qcode.in》）是 Saqueib 的一篇博客，涵盖了关于全栈 Web 开发的所有内容。

许可协议

MIT 许可协议（MIT）。有关更多信息，请参阅许可文件。

jawabapp / laravel-gamify

维护者

详细信息