README

这是一个基于 Laravel 通知系统灵感的 Laravel 成就系统实现。

需求

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

版本和分支

v2.* (master) - 新的命名空间 ITVOLAND\*，支持 Laravel >=6 和 PHP7.2（修复、安全和功能更新）

安装

默认安装通过 Composer 完成。

composer require itvoland/laravel-achievements

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

'providers' => [
    //...
    ITVOLAND\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 ITVOLAND\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 ITVOLAND\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 ITVOLAND\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 实例。

ITVOLAND\Achievements\Event\Progress 事件会在 Achiever 有进展但不解锁成就时触发。而 ITVOLAND\Achievements\Event\Unlocked 事件则在 Achiever 实际解锁成就时触发。

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

监听特定成就

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

<?php

namespace App\Achievements;

use ITVOLAND\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 许可证。

itvoland / laravel-achievements

维护者

详细信息