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 的方法，可用于解锁成就。该方法期望一个 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有进度，但未解锁成就时触发。而Assada\Achievements\Event\Unlocked事件在Achiever实际解锁成就时触发。

有关如何监听这些事件的详细信息，请参阅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许可证。

assada / laravel-achievements

维护者

详细信息