README

Laravel 成就系统的实现，灵感来源于 Laravel 的通知系统。

要求

Laravel 6 或更高版本
PHP 7.2 或更高版本

版本和分支

v1.* - 原始 Gstt\* 命名空间，支持 Laravel 6 和 PHP7.2（仅修复和安全更新）
v2.*（master）- 新命名空间 Assada\*，支持 Laravel >=6 和 PHP7.2（修复、安全和功能更新）

安装

默认安装方式是通过 Composer。

composer require assada/laravel-achievements

服务提供器将自动注册。或者，您可以手动将服务提供器添加到您的 config/app 文件中的 providers 部分。

'providers' => [
    //...
    Assada\Achievements\AchievementsServiceProvider::class,
]

备份您的数据库，并运行迁移以在数据库上设置所需的表。

php artisan migrate

创建成就

类似于 Laravel 对通知的实现，每个成就由单个类表示（通常存储在 app\Achievements 目录中。）在您运行 make:achievement 命令时，此目录将自动为您创建。

php artisan make:achievement UserMadeAPost

此命令将在您的 app/Achievements 目录中放置一个全新的成就，仅定义了两个属性：name 和 description。您应该更改这些属性的默认值，以便更好地解释成就是什么以及如何解锁它。完成后，它应该看起来像这样

<?php

namespace App\Achievements;

use Assada\Achievements\Achievement;

class UserMadeAPost extends Achievement
{
    /*
     * The achievement name
     */
    public $name = 'Post Created';

    /*
     * A small description for the achievement
     */
    public $description = 'Congratulations! You have made your first post!';
}

解锁成就

可以通过使用 Achiever 特性来解锁成就。

<?php

namespace App;

use Assada\Achievements\Achiever;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    use Achiever;
}

此特性包含 unlock 方法，可以用来解锁成就。该 unlock 方法期望一个 Achievement 实例

use App\Achievements\UserMadeAPost;

$user->unlock(new UserMadeAPost());

请记住，您不仅限于 User 类。您可以将 Achiever 特性添加到任何可以解锁成就的实体中。

添加进度

除了直接解锁成就外，您还可以向其添加进度。例如，您可能有一个名为 UserMade10Posts 的成就，并希望跟踪用户在该成就上的进度。

为了做到这一点，您必须在您的 UserMade10Posts 类上设置一个额外的参数，称为 $points

<?php

namespace App\Achievements;

use Assada\Achievements\Achievement;

class UserMade10Posts extends Achievement
{
    /*
     * The achievement name
     */
    public $name = '10 Posts Created';

    /*
     * A small description for the achievement
     */
    public $description = 'Wow! You have already created 10 posts!';

    /*
     * The amount of "points" this user need to obtain in order to complete this achievement
     */
    public $points = 10;
}

现在，您可以通过 Achiever 特性上的 addProgress 和 removeProgress 方法控制进度。这两个方法都期望一个 Achievement 实例和要添加或删除的点数

use App\Achievements\UserMade10Posts;

$user->addProgress(new UserMade10Posts(), 1); // Adds 1 point of progress to the UserMade10Posts achievement

此外，您可以使用 resetProgress 方法将进度重置为 0，并使用 setProgress 方法将其设置为指定的点数

use App\Achievements\FiveConsecutiveSRanks;

if($rank != 'S'){
    $user->resetProgress(new FiveConsecutiveSRanks());
} else {
    $user->addProgress(new FiveConsecutiveSRanks(), 1);
}

use App\Achievements\Have1000GoldOnTheBag;

$user->setProgress(new Have100GoldOnTheBag(), $user->amountOfGoldOnTheBag);

一旦成就达到定义的点数，它将被自动解锁。

检索成就

Achiever 特性还向实现它的实体添加了一个便捷的关系：achievements()。您可以使用它来检索实体已交互的所有成就的进度。由于 achievements() 是一个关系，您可以使用它作为 QueryBuilder 进一步筛选数据。

$achievements   = $user->achievements;
$unlocked_today = $user->achievements()->where('unlocked_at', '>=', Carbon::yesterday())->get();

您还可以使用 achievementStatus() 方法搜索特定的成就。

$details = $user->achievementStatus(new UserMade10Posts());

Achiever 特性还有三个额外的辅助方法：lockedAchievements()、inProgressAchievements() 和 unlockedAchievements()。

事件监听器

监听所有成就

Laravel Achievements 提供了两个可以监听的事件，以便提供“成就解锁”消息或类似的消息。这两个事件都会接收触发它们 AchievementProgress 实例。

Assada\Achievements\Event\Progress 事件在 Achiever 有进步但未解锁成就时触发。当 Achiever 实际解锁成就时，会触发 Assada\Achievements\Event\Unlocked 事件。

有关如何监听这些事件的详细信息，请参阅 Laravel 事件文档。

监听特定成就

上述事件监听器针对所有成就触发。如果您只想为特定成就添加事件监听器，可以在 Achievement 类上实现 whenUnlocked 或 whenProgress 方法。

<?php

namespace App\Achievements;

use Assada\Achievements\Achievement;

class UserMade50Posts extends Achievement
{
    /*
     * The achievement name
     */
    public $name = '50 Posts Created';

    /*
     * A small description for the achievement
     */
    public $description = 'Wow! You have already created 50 posts!';

    /*
     * The amount of "points" this user need to obtain in order to complete this achievement
     */
    public $points = 50;

    /*
     * Triggers whenever an Achiever makes progress on this achievement
    */
    public function whenProgress($progress)
    {

    }

    /*
     * Triggers whenever an Achiever unlocks this achievement
    */
    public function whenUnlocked($progress)
    {

    }
}

许可

Laravel Achievements 是开源软件，许可协议为 MIT 许可证。

romjkeeee / laravel-achievements

维护者

详细信息