README

Laravel Gamify：支持积分和徽章的游戏化系统

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

安装

1 - 您可以通过 composer 安装此包

$ composer require ansezz/laravel-gamify

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

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

Laravel 5.5 及更高版本会自动注册。

3 - 现在发布 gamify 表的迁移

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

注意： 它将生成 points、badges、gamify_groups、pointables、badgables 表的迁移，您需要运行 composer require doctrine/dbal 以支持删除和添加列。

php artisan migrate

您可以发布配置文件

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

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

入门

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

use Ansezz\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

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

<?php

namespace App\Gamify\Points;

use Ansezz\Gamify\BasePoint;

class PostCreated extends BasePoint
{
       public function __invoke($point, $subject)
       {
           return true;
       }

}

在 __invoke 中，您可以添加任何条件以检查用户是否达到积分，否则返回 true，否则我们使用 config('gamify.point_is_archived')，默认情况下，您可以在您的配置文件 gamify.php 中更改它。

向用户分配积分

$user = auth()->user();

$point = Point::find(1);

// or you can use facade function
Gamify::achievePoint($point);


// or via HasBadge trait method
$user->achievePoint($point);

撤销分配的积分

在某些情况下，您可能想要撤销分配的积分。

$user = auth()->user();

$point = Point::find(1);

// or you can use facade function
Gamify::undoPoint($point);

// or via HasPoint trait method
$user->undoPoint($point);

您也可以在函数 achievePoint & undoPoint ($point, $event) 中传递第二个参数 $event（布尔值），默认为 true，以禁用发送 PointsChanged 事件。

Pro Tip 👌 您还可以挂钩到 Eloquent 模型事件，在 created 事件上分配积分。同样，可以使用 deleted 事件来撤销积分。

获取总声誉

要获取总用户积分，您可以使用 achieved_points 属性。

// get integer point
$user->achieved_points; // 20

获取积分历史

该包存储了所有积分事件日志，因此您可以通过以下关系获取积分历史：

foreach($user->points as $point) {
    // name of the point type 
    $point->name;
    
    // how many points
    $point->point;
}

获取徽章历史

该包在数据库中存储了所有徽章，因此您可以通过以下关系获取徽章历史：

foreach($user->badges as $badge) {
    // name of the point type 
    $point->name;
    
    // how many points
    $point->image;
}

积分变更事件

当用户积分变更时，会触发 \Ansezz\Gamify\Events\PointsChanged 事件，该事件包含以下负载：

class PointsChanged implements ShouldBroadcast {
    
    ...
    public function __construct(Model $subject, int $point, bool $increment)
    {
        $this->subject = $subject;
        $this->point = $point;
        $this->increment = $increment;
    }
}

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

🏅 成就徽章 🏆

与积分类型类似，您还有徽章。您可以根据排名或其他任何标准将徽章授予用户。您应在配置文件中定义徽章级别。

创建徽章

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

它会询问您是否想要创建数据库徽章记录。

徽章表中的类属性将采用本例中的命名空间中的类：App\Gamify\Badges\PostCreated

php artisan gamify:badge PostCreated

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

对于每个级别，您需要定义一个以级别名称命名的函数来检查主题是否实现了徽章，否则我们使用默认的 config('gamify.badge_is_archived')，您可以在配置文件 gamify.php 中更改它。

<?php

namespace App\Gamify\Badges;

use Ansezz\Gamify\BaseBadge;

class PostCreated extends BaseBadge
{

    /**
       * @param $badge
       * @param $subject
       *
       * @return bool
       */
      public function beginner($badge, $subject)
      {
          return $subject->achieved_points >= 100;
      }
  
      /**
       * @param $badge
       * @param $subject
       *
       * @return bool
       */
      public function intermediate($badge, $subject)
      {
          return $subject->achieved_points >= 200;
      }
  
      /**
       * @param $badge
       * @param $subject
       *
       * @return bool
       */
      public function advanced($badge, $subject)
      {
          return $subject->achieved_points >= 300;
      }

}

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

检查主题是否实现了徽章

$badage = Badge::find(1);
$user =  auth()->user();

$badge->isAchieved($user);

同步所有徽章

// sync all badges for current subject using Facade
Gamify::syncBadges($user);

// or via HasBadge trait method
$user->syncBadges();

同步单个徽章

$badge = Badge::find(1);
// sync all badges for current subject using Facade
Gamify::syncBadge($badge, $user)

// or via HasBadge trait method
$user->syncBadge($badge);

徽章实现事件

当用户积分变更时，会触发 \Ansezz\Gamify\Events\BadgeAchieved 事件，该事件包含以下负载：

class BadgeAchieved implements ShouldBroadcast {
    
    ...
    public function __construct($subject, $badge)
    {
        $this->subject = $subject;
        $this->badge = $badge;
    }
}

配置Gamify

<?php

return [
    // Reputation model
    'point_model'                  => '\Ansezz\Gamify\Point',

    // 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'                  => '\Ansezz\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,

    // Badge achieved vy default if check function not exit
    'badge_is_archived'            => false,

    // point achieved vy default if check function not exit
    'point_is_archived'            => true,
];

变更日志

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

测试

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

$ composer test

贡献

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

安全

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

鸣谢

Anass Ez-zouaine（作者）

许可

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

ansezz / laravel-gamify

维护者

详细信息