README

该软件包允许用户通过在您的网站上执行操作来获得经验值（XP）并通过等级。它可以提供一个简单的方式来跟踪用户进度并将游戏化元素集成到您的应用程序中

安装

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

composer require cjmellor/level-up

您可以使用以下命令发布和运行迁移

php artisan vendor:publish --tag="level-up-migrations"
php artisan migrate

您可以使用以下命令发布配置文件

php artisan vendor:publish --tag="level-up-config"

这是已发布的配置文件内容

return [
    /*
    |--------------------------------------------------------------------------
    | User Foreign Key
    |--------------------------------------------------------------------------
    |
    | This value is the foreign key that will be used to relate the Experience model to the User model.
    |
     */
    'user' => [
        'foreign_key' => 'user_id',
        'model' => App\Models\User::class,
    ],

    /*
    |--------------------------------------------------------------------------
    | Experience Table
    |--------------------------------------------------------------------------
    |
    | This value is the name of the table that will be used to store experience data.
    |
     */
    'table' => 'experiences',

    /*
    |-----------------------------------------------------------------------
    | Starting Level
    |-----------------------------------------------------------------------
    |
    | The level that a User starts with.
    |
    */
    'starting_level' => 1,

    /*
    |-----------------------------------------------------------------------
    | Multiplier Paths
    |-----------------------------------------------------------------------
    |
    | Set the path and namespace for the Multiplier classes.
    |
    */
    'multiplier' => [
        'enabled' => env(key: 'MULTIPLIER_ENABLED', default: true),
        'path' => env(key: 'MULTIPLIER_PATH', default: app_path(path: 'Multipliers')),
        'namespace' => env(key: 'MULTIPLIER_NAMESPACE', default: 'App\\Multipliers\\'),
    ],

    /*
    |-----------------------------------------------------------------------
    | Level Cap
    |-----------------------------------------------------------------------
    |
    | Set the maximum level a User can reach.
    |
    */
    'level_cap' => [
        'enabled' => env(key: 'LEVEL_CAP_ENABLED', default: true),
        'level' => env(key: 'LEVEL_CAP', default: 100),
        'points_continue' => env(key: 'LEVEL_CAP_POINTS_CONTINUE', default: true),
    ],

    /*
    | -------------------------------------------------------------------------
    | Audit
    | -------------------------------------------------------------------------
    |
    | Set the audit configuration.
    |
    */
    'audit' => [
        'enabled' => env(key: 'AUDIT_POINTS', default: false),
    ],

    /*
    | -------------------------------------------------------------------------
    | Record streak history
    | -------------------------------------------------------------------------
    |
    | Set the streak history configuration.
    |
    */
    'archive_streak_history' => [
        'enabled' => env(key: 'ARCHIVE_STREAK_HISTORY_ENABLED', default: true),
    ],

    /*
     | -------------------------------------------------------------------------
     | Default Streak Freeze Time
     | -------------------------------------------------------------------------
     |
     | Set the default time in days that a streak will be frozen for.
     |
     */
    'freeze_duration' => env(key: 'STREAK_FREEZE_DURATION', default: 1),
];

使用方法

💯 经验值（XP）

注意

XP默认启用。您可以在配置中禁用它

将GiveExperience特质添加到您的User模型中。

use LevelUp\Experience\Concerns\GiveExperience;

class User extends Model
{
    use GiveExperience;

    // ...
}

给用户添加XP点

$user->addPoints(10);

将在experiences表中添加一条新记录，该表存储用户的点数。如果已存在记录，则将其更新。所有新记录都将分配一个level_id为1。

注意

如果您还没有设置您的等级结构，将添加默认等级1以帮助您开始。

从用户中扣除XP点

$user->deductPoints(10);

将XP点设置给用户

对于您只想直接给用户添加一定数量点的活动。只能设置点数，如果用户有经验模型。

$user->setPoints(10);

检索用户的点数

$user->getPoints();

乘数

可以使用点数乘数来通过特定的乘数修改活动的经验值，例如将点值加倍或三倍。这对于实现提供额外积分的临时活动或促销非常有用。

要开始，您可以使用Artisan命令创建一个新的乘数。

php artisan level-up:multiplier IsMonthDecember

这将创建一个位于app\Multipliers\IsMonthDecember.php的文件。

这是一个类的样子

<?php

namespace LevelUp\Experience\Tests\Fixtures\Multipliers;

use LevelUp\Experience\Contracts\Multiplier;

class IsMonthDecember implements Multiplier
{
    public bool $enabled = true;
    
    public function qualifies(array $data): bool
    {
        return now()->month === 12;
    }

    public function setMultiplier(): int
    {
        return 2;
    }
}

乘数默认启用，但您可以将$enabled变量更改为false，这样它甚至不会运行。

qualifies方法是将您的逻辑放入以检查并乘以结果为真的地方。

这可以简单地检查月份是否为十二月。

public function qualifies(array $data): bool
{
    return now()->month === 12;
}

或者传递额外的数据以进行检查。这要复杂一些。

当您向用户添加点数时，您可以传递额外的数据。任何启用的乘数都可以使用这些数据进行检查。

$user
    ->withMultiplierData([
        'event_id' => 222,
    ])
    ->addPoints(10);

//

public function qualifies(array $data): bool
{
    return isset($data['event_id']) && $data['event_id'] === 222;
}

条件乘数

如果您不想使用基于类的条件检查方法来添加乘数，您可以通过传递一个带有条件的回调方法来实现。使用此方法时，请确保在addPoints方法中设置了乘数作为参数，否则将发生错误。下面是示例

$user
    ->withMultiplierData(fn () => true)
    ->addPoints(amount: 10, multiplier: 2);

setMultiplier方法期望一个整数，该整数将被乘以。

手动乘法

如果您希望，可以完全跳过此步骤并手动乘以点数。

$user->addPoints(
    amount: 10, 
    multiplier: 2
);

事件

PointsIncrease - 当添加点数时。

public int $pointsAdded,
public int $totalPoints,
public string $type,
public ?string $reason,
public Model $user,

PointsDecreased - 当减少点数时。

public int $pointsDecreasedBy,
public int $totalPoints,
public ?string $reason,
public Model $user,

⬆️ 等级提升

注意

如果您在设置等级结构之前添加点数，将添加默认等级1以帮助您开始。

设置您的等级结构

该软件包有一个方便的门面，可以帮助您创建等级。

Level::add(
    ['level' => 1, 'next_level_experience' => null],
    ['level' => 2, 'next_level_experience' => 100],
    ['level' => 3, 'next_level_experience' => 250],
);

等级 1对于next_level_experience应该是始终为null，因为它是默认的起始点。

一旦用户获得下一个等级所需的正确数量的点数，他们就会升级。

示例：用户获得50分，他们仍然处于第1级，但再获得50分，用户现在将进入第2级

查看距离下一个等级还有多少分

$user->nextLevelAt();

获取用户的当前等级

$user->getLevel();

等级上限

等级上限设置用户可以达到的最大等级。一旦用户达到等级上限，他们将无法再获得更多等级，即使他们继续获得经验值。等级上限默认启用，上限为等级100。这些选项可以在config/level-up.php配置文件中更改，或者通过添加到您的.env文件中来实现。

LEVEL_CAP_ENABLED=
LEVEL_CAP=
LEVEL_CAP_POINTS_CONTINUE

默认情况下，即使用户达到等级上限，他们仍将继续获得经验值。要冻结此功能，以便在达到上限后不再增加分数，请在配置文件中启用points_continue选项，或在.env中设置它。

事件

UserLevelledUp - 当用户升级时

public Model $user,
public int $level

🏆 成就

这是一个功能，允许您通过完成特定任务或达到某些里程碑来认可和奖励用户。您可以定义自己的成就及其获得标准。成就可以是静态的，也可以有进展。静态意味着成就可以立即获得。具有进展的成就可以在增量中获得，例如，成就只能在进度达到100%时获得。

创建成就

没有内置的创建成就的方法，只有一个您可以用作正常的Achievement模型。

Achievement::create([
    'name' => 'Hit Level 20',
    'is_secret' => false,
    'description' => 'When a User hits Level 20',
    'image' => 'storage/app/achievements/level-20.png',
]);

获得成就

要在用户模型中使用成就，您必须首先添加特性。

// App\Models\User.php

use LevelUp\Experience\Concerns\HasAchievements;

class User extends Authenticable
{
	use HasAchievements;
	
	// ...
}

然后您可以使用其方法，例如授予用户一个成就。

$achievement = Achievement::find(1);

$user->grantAchievement($achievement);

检索您的成就

$user->achievements;

添加成就进度

$user->grantAchievement(
    achievement: $achievement, 
    progress: 50 // 50%
);

注意

成就进度上限为100%

检查成就进度

检查您的成就进度处于什么位置。

$user->achievementsWithProgress()->get();

检查具有特定进度量的成就

$user->achievements
    ->first()
    ->pivot()
    ->withProgress(25)
    ->get();

增加成就进度

您可以增加成就的进度，最高到100。

$user->incrementAchievementProgress(
    achievement: $achievement, 
    amount: 10
);

在方法执行时运行一个AchievementProgressionIncreased事件。

秘密成就

秘密成就是那些在解锁之前对用户隐藏的成就。

秘密成就在创建时就被设置为秘密的。如果您想将非秘密成就设置为秘密，只需更新模型即可。

$achievement->update(['is_secret' => true]);

您可以检索秘密成就。

$user->secretAchievements;

查看所有成就，包括秘密和非秘密的成就

$user->allAchievements;

事件

AchievementAwarded - 当成就附加到用户上时

public Achievement $achievement,
public Model $user,

注意

只有当成就的进度为100%时，此事件才会运行。

AchievementProgressionIncreased - 当用户的成就进度增加时。

public Achievement $achievement,
public Model $user,
public int $amount,

📈 排行榜

此包还包括一个排行榜功能，用于跟踪和显示基于经验值的用户排名。

排行榜作为一个服务提供。

Leaderboard::generate();

这会生成一个用户模型及其经验和等级数据，并按用户的经验值排序。

排行榜非常基础，有很多改进的空间。

🔍 审计

您可以在配置中启用审计功能，该功能会跟踪用户每次获得分数、升级以及升级到哪个等级。

基于采取的操作，将自动填充type和reason字段，但在向用户添加分数时可以覆盖这些字段。

$user->addPoints(
    amount: 50,
    multiplier: 2,
    type: AuditType::Add->value,
    reason: "Some reason here",
);

注意

在调用addPoints和deductPoints方法时发生审计。必须在配置文件中启用审计。

查看用户的审计经验

$user->experienceHistory;

🔥 连赢

使用“连续活动”功能，您可以通过监控连续的每日活动来跟踪和激励用户参与度。无论是登录、完成任务还是任何其他日常活动，维持连续活动可以鼓励用户保持活跃和参与。

连续活动在属性中控制，因此只有当您想使用此功能时才使用该属性。将属性添加到您的 User 模型中

use LevelUp\Experience\Concerns\HasStreaks;

class User extends Model
{
	use HasStreaks;

	// ...
}

活动

使用 Activies 模型添加您想要跟踪的新活动。以下是一些示例

• 登录网站
• 发布文章

记录连续活动

$activity = Activity::find(1);

$user->recordStreak($activity);

这将增加用户在此活动上的连续活动计数。在增加时会触发一个事件。

中断连续活动

连续活动可以被中断，无论是自动还是手动。这将计数重置为 1 以重新开始。当连续活动被中断时，会触发一个事件。

例如，如果您的连续活动已经成功运行了5天，但有一天被跳过，您在第7天运行活动，连续活动将被中断并重置为 1。目前，这是自动发生的。

重置连续活动

如果您愿意，可以手动重置连续活动。如果 level-up.archive_streak_history.enabled 为 true，则将记录连续活动历史。

$activity = Activity::find(1);

$user->resetStreak($activity);

归档连续活动历史

连续活动默认是记录的，或称为“归档”。当连续活动被中断时，会记录连续活动的记录。提供了一个模型来使用这些数据。

use LevelUp\Experience\Models\StreakHistory;

StreakHistory::all();

获取当前连续活动计数

查看用户在活动上的连续活动计数

$user->getCurrentStreakCount($activity); // 2

检查用户连续活动情况

检查用户是否在当天完成了连续活动

$user->hasStreakToday($activity);

事件

StreakIncreased - 如果在前一天之后发生活动，则连续活动会增加。

public int $pointsAdded,
public int $totalPoints,
public string $type,
public ?string $reason,
public Model $user,

StreakBroken - 当连续活动被中断且计数重置时。

public Model $user,
public Activity $activity,
public Streak $streak,

🥶 连续活动冻结

连续活动可以被冻结，这意味着如果有一天被跳过，它们不会被中断。这对于您希望允许用户从活动中休息而不失去连续活动很有用。

冻结持续时间是配置文件中的一个可配置选项。

'freeze_duration' => env(key: 'STREAK_FREEZE_DURATION', default: 1),

冻结连续活动

获取要冻结的活动并将其传递给 freezeStreak 方法。可以传递第二个参数来设置冻结的持续时间。默认为 1 天（如配置中设置）

当连续活动被冻结时，会触发一个 StreakFrozen 事件。

$user->freezeStreak(activity: $activity);

$user->freezeStreak(activity: $activity, days: 5); // freeze for 5 days

解冻连续活动

冻结连续活动的相反操作是解冻它。这将允许再次中断连续活动。

当连续活动被解冻时，会运行一个 StreakUnfrozen 事件。

$user->unfreezeStreak($activity);

检查连续活动是否被冻结

$user->isStreakFrozen($activity);

事件

StreakFrozen - 当连续活动被冻结时。

public int $frozenStreakLength,
public Carbon $frozenUntil,

StreakUnfrozen - 当连续活动被解冻时。

No data is sent with this event

测试

composer test

变更日志

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

许可

MIT 许可证 (MIT)。请参阅许可文件以获取更多信息。