?style=for-the-badge&logo=laravel){kind=icon}
This package allows users to gain experience points (XP) and progress through levels by performing actions on your site. It can provide a simple way to track user progress and implement gamification elements into your application
You can install the package via composer:
composer require cjmellor/level-up
You can publish and run the migrations with:
php artisan vendor:publish --tag="level-up-migrations"
php artisan migrate
You can publish the config file with:
php artisan vendor:publish --tag="level-up-config"
This is the contents of the published config file:
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
| -------------------------------------------------------------------------<
8000
/span>
|
| Set the audit configuration.
|
*/
'audit' => [
'enabled' => env(key: 'AUDIT_POINTS', default: false),
],
];Note
XP is enabled by default. You can disable it in the config
Add the GiveExperience trait to your User model.
use LevelUp\Experience\Concerns\GiveExperience;
class User extends Model
{
use GiveExperience;
// ...
}Give XP points to a User
$user->addPoints(10);A new record will be added to the experiences table which stores the Usersâ points. If a record already exists, it will be updated instead. All new records will be given a level_id of 1.
Note
If you didn't set up your Level structure yet, a default Level of
1will be added to get you started.
Deduct XP points from a User
$user->deductPoints(10);Set XP points to a User
For an event where you just want to directly add a certain number of points to a User. Points can only be set if the User has an Experience Model.
$user->setPoints(10);Retrieve a Usersâ points
$user->getPoints();Point multipliers can be used to modify the experience point value of an event by a certain multiplier, such as doubling or tripling the point value. This can be useful for implementing temporary events or promotions that offer bonus points.
To get started, you can use an Artisan command to crease a new Multiplier.
php artisan level-up:multiplier IsMonthDecemberThis will create a file at app\Multipliers\IsMonthDecember.php.
Here is how the class looks:
<?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;
}
}Multipliers are enabled by default, but you can change the $enabled variable to false so that it wonât even run.
The qualifies method is where you put your logic to check against and multiply if the result is true.
This can be as simple as checking that the month is December.
public function qualifies(array $data): bool
{
return now()->month === 12;
}Or passing extra data along to check against. This is a bit more complex.
You can pass extra data along when you're adding points to a User. Any enabled Multiplier can then use that data to check against.
$user
->withMultiplierData([
'event_id' => 222,
])
->addPoints(10);
//
public function qualifies(array $data): bool
{
return isset($data['event_id']) && $data['event_id'] === 222;
}The setMultiplier method expects an int which is the number it will be multiplied by.
Multiply Manually
You can skip this altogether and just multiply the points manually if you desire.
$user->addPoints(
amount: 10,
multiplier: 2
);PointsIncrease - When points are added.
public int $pointsAdded,
public int $totalPoints,
public string $type,
public ?string $reason,
public Model $user,PointsDecreased - When points are decreased.
public int $pointsDecreasedBy,
public int $totalPoints,Note
If you add points before setting up your levelling structure, a default Level of
1will be added to get you started.
The package has a handy facade to help you create your levels.
Level::add(
['level' => 1, 'next_level_experience' => null],
['level' => 2, 'next_level_experience' => 100],
['level' => 3, 'next_level_experience' => 250],
);Level 1 should always be null for the next_level_experience as it is the default starting point.
As soon as a User gains the correct number of points listed for the next level, they will level-up.
Example: a User gains 50 points, theyâll still be on Level 1, but gets another 50 points, so the User will now move onto Level 2
See how many points until the next level
$user->nextLevelAt();Get the Usersâ current Level
$user->getLevel();A level cap sets the maximum level that a user can reach. Once a user reaches the level cap, they will not be able to gain any more levels, even if they continue to earn experience points. The level cap is enabled by default and capped to level 100. These options can be changed in the packages config file at config/level-up.php or by adding them to your .env file.
LEVEL_CAP_ENABLED=
LEVEL_CAP=
LEVEL_CAP_POINTS_CONTINUE
By default, even when a user hits the level cap, they will continue to earn experience points. To freeze this, so points do not increase once the cap is hit, turn on the points_continue option in the config file, or set it in the .env.
UserLevelledUp - When a User levels-up
public Model $user,
public int $levelThis is a feature that allows you to recognise and reward users for completing specific tasks or reaching certain milestones. You can define your own achievements and criteria for earning them. Achievements can be static or have progression. Static meaning the achievement can be earned instantly. Achievements with progression can be earned in increments, like an achievement can only be obtained once the progress is 100% complete.
There is no built-in methods for creating achievements, there is just an Achievement model that you can use as normal:
Achievement::create([
'name' => 'Hit Level 20',
'is_secret' => false,
'description' => 'When a User hits Level 20',
'image' => 'storage/app/achievements/level-20.png',
]);To use Achievements in your User mode, you must first add the Trait.
// App\Models\User.php
use LevelUp\Experience\Concerns\HasAchievements;
class User extends Authenticable
{
use HasAchievements;
// ...
}Then you can start using its methods, like to grant a User an Achievement:
$achievement = Achievement::find(1);
$user->grantAchievement($achievement);To retrieve your Achievements:
$user->achievements;$user->grantAchievement(
achievement: $achievement,
progress: 50 // 50%
);Note
Achievement progress is capped to 100%
Check at what progression your Achievements are at.
$user->achievementsWithProgress()->get();Check Achievements that have a certain amount of progression:
$user->achievements
->first()
->pivot()
->withProgress(25)
->get();You can increment the progression of an Achievement up to 100.
$user->incrementAchievementProgress(
achievement: $achievement,
amount: 10
);A AchievementProgressionIncreased Event runs on method execution.
Secret achievements are achievements that are hidden from users until they are unlocked.
Secret achievements are made secret when created. If you want to make a non-secret Achievement secret, you can just update the Model.
$achievement->update(['is_secret' => true]);You can retrieve the secret Achievements.
$user->secretAchievements;To view all Achievements, both secret and non-secret:
$user->allAchievements;AchievementAwarded - When an Achievement is attached to the User
public Achievement $achievement,
public Model $user,Note
This event only runs if the progress of the Achievement is 100%
AchievementProgressionIncreased - When a Usersâ progression for an Achievement is increased.
public Achievement $achievement,
public Model $user,
public int $amount,The package also includes a leaderboard feature to track and display user rankings based on their experience points.
The Leaderboard comes as a Service.
Leaderboard::generate();This generates a User model along with its Experience and Level data and ordered by the Usersâ experience points.
The Leaderboard is very basic and has room for improvement
You can enable an Auditing feature in the config, which keeps a track each time a User gains points, levels up and what level to.
The type and reason fields will be populated automatically based on the action taken, but you can overwrite these when adding points to a User
$user->addPoints(
amount: 50,
multiplier: 2,
type: AuditType::Add->value,
reason: "Some reason here",
);View a Usersâ Audit Experience
$user->experienceHistory;composer test
Please see CHANGELOG for more information on what has changed recently.
The MIT Licence (MIT). Please see Licence File for more information.