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）

将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方法期望一个int，这是它将乘以的数字。

手动乘法

您可以选择完全跳过此步骤，并手动乘以点数。

$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],
);

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

一旦用户获得下一级所需列出的正确积分，他们就会升级。

提示

如果用户获得50积分，他们仍然处于一级，但再获得50积分，那么用户现在将进入二级

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

$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;

	// ...
}

活动

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

• 登录网站
• 发布文章

记录连续活动

$activity = Activity::find(1);

$user->recordStreak($activity);

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

中断连续活动

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

例如，如果您的连续活动已经连续进行了5天，但有一天被跳过，您在第七天运行了活动，连续活动将被中断并重置为 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）。请参阅许可证文件以获取更多信息。