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

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

Level 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天，但有一天被跳过，您在第七天运行活动，连续性将被打破并重置为 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);

事件

连续性增加 - 如果在前一天之后的一天发生活动，连续性将增加。

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

连续性打破 - 当连续性被打破且计数器重置时。

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

事件

连续性冻结 - 当连续性被冻结时。

public int $frozenStreakLength,
public Carbon $frozenUntil,

连续性解冻 - 当连续性被解冻时。

No data is sent with this event

测试

composer test

变更日志

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

许可证

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