Download the PHP package cjmellor/level-up without Composer

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

Installation

You can install the package via composer:

You can publish and run the migrations with:

You can publish the config file with:

This is the contents of the published config file:

Usage

💯 Experience Points (XP)

Add the GiveExperience trait to your User model.

Give XP points to a User

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 1 will be added to get you started.

Deduct XP points from a User

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.

Retrieve a Users’ points

Multipliers

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.

This will create a file at app\Multipliers\IsMonthDecember.php.

Here is how the class looks:

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.

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.

Conditional Multipliers

If you don't want to use the class based method to check conditionals to add multipliers, you can do this inline by giving the method a callback with the conditional. When using this method, make sure you have the multiplier set as an argument in the addPoints method, otherwise an error will occur. See example below:

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.

Events

PointsIncrease - When points are added.

PointsDecreased - When points are decreased.

⬆️ Levelling

[!NOTE] If you add points before setting up your levelling structure, a default Level of 1 will be added to get you started.

Set up your levelling structure

The package has a handy facade to help you create your levels.

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.

[!TIP] 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

Get the Users’ current Level

Level Cap

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.

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.

Events

UserLevelledUp - When a User levels-up

🏆 Achievements

This 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.

Creating Achievements

There is no built-in methods for creating achievements, there is just an Achievement model that you can use as normal:

Gain Achievement

To use Achievements in your User model, you must first add the Trait.

Then you can start using its methods, like to grant a User an Achievement:

To retrieve your Achievements:

Add progress to Achievement

[!NOTE] Achievement progress is capped to 100%

Check Achievement Progression

Check at what progression your Achievements are at.

Check Achievements that have a certain amount of progression:

Increase Achievement Progression

You can increment the progression of an Achievement up to 100.

A AchievementProgressionIncreased Event runs on method execution.

Secret Achievements

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.

You can retrieve the secret Achievements.

To view all Achievements, both secret and non-secret:

Events

AchievementAwarded - When an Achievement is attached to the User

[!NOTE] This event only runs if the progress of the Achievement is 100%

AchievementProgressionIncreased - When a Users’ progression for an Achievement is increased.

📈 Leaderboard

The package also includes a leaderboard feature to track and display user rankings based on their experience points.

The Leaderboard comes as a Service.

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

🔍 Auditing

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

[!NOTE] Auditing happens when the addPoints and deductPoints methods are called. Auditing must be enabled in the config file.

View a Users’ Audit Experience

🔥 Streaks

With the Streaks feature, you can track and motivate user engagement by monitoring consecutive daily activities. Whether it's logging in, completing tasks, or any other daily activity, maintaining streaks encourages users to stay active and engaged.

Streaks are controlled in a Trait, so only use the trait if you want to use this feature. Add the Trait to you User model

Activities

Use the Activies model to add new activities that you want to track. Here’s some examples:

• Logs into a website
• Posts an article

Record a Streak

This will increment the streak count for the User on this activity. An `Event is ran on increment.

Break a Streak

Streaks can be broken, both automatically and manually. This puts the count back to 1 to start again. An Event is ran when a streak is broken.

For example, if your streak has had a successful run of 5 days, but a day is skipped and you run the activity on day 7, the streak will be broken and reset back to 1. Currently, this happens automatically.

Reset a Streak

You can reset a streak manually if you desire. If level-up.archive_streak_history.enabled is true, the streak history will be recorded.

Archive Streak Histories

Streaks are recorded, or “archived” by default. When a streak is broken, a record of the streak is recorded. A Model is supplied to use this data.

Get Current Streak Count

See the streak count for an activity for a User

Check User Streak Activity

Check if the User has performed a streak for the day

Events

StreakIncreased - If an activity happens on a day after the previous day, the streak is increased.

StreakBroken - When a streak is broken and the counter is reset.

🥶 Streak Freezing

Streaks can be frozen, which means they will not be broken if a day is skipped. This is useful for when you want to allow users to take a break from an activity without losing their streak.

The freeze duration is a configurable option in the config file.

Freeze a Streak

Fetch the activity you want to freeze and pass it to the freezeStreak method. A second parameter can be passed to set the duration of the freeze. The default is 1 day (as set in the config)

A StreakFrozen Event is ran when a streak is frozen.

Unfreeze a Streak

The opposite of freezing a streak is unfreezing it. This will allow the streak to be broken again.

A StreakUnfrozen Event is run when a streak is unfrozen.

Check if a Streak is Frozen

Events

StreakFrozen - When a streak is frozen.

StreakUnfrozen - When a streak is unfrozen.

Testing

Changelog

Please see CHANGELOG for more information on what has changed recently.

License

The MIT Licence (MIT). Please see Licence File for more information.