Level Up Development

When to use this skill

Use this skill when working with gamification features — adding experience points, levels, tiers, achievements, streaks, multipliers, leaderboards, or auditing — using cjmellor/level-up.

Core Concepts

• XP and Levels — Users earn experience points (XP) and automatically progress through a defined level structure.
• Tiers — Named status brackets (e.g. Bronze, Silver, Gold) based on XP thresholds, independent of numeric levels.
• Achievements — Unlockable rewards, optionally with progress tracking, optionally gated by tier.
• Streaks — Track consecutive daily activities with freeze support.
• Multipliers — Database-backed point modifiers with scoping, scheduling, and configurable stacking strategies.
• Leaderboard — Rank users by XP, optionally scoped to a tier.
• Auditing — Automatic history of all XP changes, level-ups, and tier changes.

Setup

Install

composer require cjmellor/level-up
php artisan vendor:publish --tag="level-up-migrations"
php artisan migrate
php artisan vendor:publish --tag="level-up-config"

Add Traits to the User Model

Add only the traits you need:

use LevelUp\Experience\Concerns\GiveExperience;
use LevelUp\Experience\Concerns\HasAchievements;
use LevelUp\Experience\Concerns\HasChallenges;
use LevelUp\Experience\Concerns\HasStreaks;
use LevelUp\Experience\Concerns\HasTiers;

class User extends Authenticatable
{
    use GiveExperience;     // Required — XP and levels
    use HasAchievements;    // Optional — achievements
    use HasStreaks;          // Optional — streaks
    use HasTiers;           // Optional — tiers
    use HasChallenges;      // Optional — challenges
}

GiveExperience is the foundation. The others are opt-in.

Levels

Define Levels

use LevelUp\Experience\Models\Level;

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

Level 1 must have next_level_experience set to null — it is the default starting point. Users level up automatically when their XP reaches the threshold. Throws LevelExistsException if a level number already exists.

Level Queries

$user->getLevel();       // Current level number (int), 0 if no experience
$user->getPoints();      // Current XP total (int), 0 if no experience
$user->nextLevelAt();    // XP remaining until next level (int)
$user->nextLevelAt(checkAgainst: 5); // XP remaining until level 5
$user->nextLevelAt(showAsPercentage: true); // Progress as 0-100 percentage

Manual Level Up

$user->levelUp(to: 5); // Jump to level 5

Throws InvalidArgumentException if the level does not exist. Fires UserLevelledUp for each intermediate level gained. Respects the level cap.

Level Cap

Configured in config/level-up.php:

'level_cap' => [
    'enabled' => env('LEVEL_CAP_ENABLED', true),
    'level' => env('LEVEL_CAP', 100),
    'points_continue' => env('LEVEL_CAP_POINTS_CONTINUE', true),
],

When the cap is reached, the user stops levelling. If points_continue is true, XP still accumulates. If false, XP stops accumulating too.

Experience Points (XP)

Add Points

$user->addPoints(50);
$user->addPoints(50, reason: 'Completed tutorial');
$user->addPoints(50, multiplier: 2);
$user->addPoints(50, type: AuditType::Add->value, reason: 'Bonus');

Creates an experience record if none exists, otherwise increments. Automatically levels up if the threshold is crossed. Throws if the amount exceeds the highest level's next_level_experience.

Deduct Points

$user->deductPoints(30);
$user->deductPoints(30, reason: 'Penalty');

Throws Exception if the user has no experience record.

Set Points

$user->setPoints(500);

Directly overwrites the XP total. Throws Exception if the user has no experience record.

Get Points

$user->getPoints(); // int, returns 0 if no experience record

Multipliers

Multipliers are database-backed records that modify point calculations. They can be scoped to specific users or tiers, scheduled with time windows, and configured to stack using different strategies.

Create Multipliers

use LevelUp\Experience\Models\Multiplier;

Multiplier::create([
    'name' => 'Weekend Bonus',
    'multiplier' => 2.0,
    'is_active' => true,
    'starts_at' => now()->startOfWeekend(),
    'expires_at' => now()->endOfWeekend(),
]);

Active multipliers are automatically applied when addPoints() is called. The multiplier value must be at least 0.01. If both starts_at and expires_at are set, starts_at must be before expires_at.

Scope Multipliers

Multipliers with no scopes apply to all users. Use scopeTo() to restrict:

$multiplier->scopeTo($user);           // Specific user only
$multiplier->scopeTo($goldTier);       // Gold tier users only
$multiplier->scopeTo($user, $tier);    // Multiple scopes (variadic)

scopeTo() is idempotent — calling it twice with the same model does not create duplicates.

Inline Multiplier

$user->addPoints(amount: 10, multiplier: 3); // 30 points

Inline multipliers stack with DB multipliers according to the configured strategy.

Stacking Strategies

Configure in config/level-up.php:

'multiplier' => [
    'enabled' => env('MULTIPLIER_ENABLED', true),
    'stack_strategy' => env('MULTIPLIER_STACK', 'compound'),
    // 'compound'  — multipliers multiply each other: 2 × 5 = 10x
    // 'additive'  — multipliers sum:              2 + 5 = 7x
    // 'highest'   — only the largest applies:  max(2, 5) = 5x
],

Query Multipliers

Multiplier::active()->get();                    // Currently active
Multiplier::active()->forUser($user)->get();    // Active for a specific user
Multiplier::scheduled()->get();                 // Future (starts_at > now)
Multiplier::expired()->get();                   // Past (expires_at < now)

MultiplierApplied Event

Fires when multipliers modify a point calculation. Properties: Model $user, Collection $multipliers, int $originalAmount, int $finalAmount, string $strategy.

Tiers

Define Tiers

use LevelUp\Experience\Models\Tier;

Tier::add(
    ['name' => 'Bronze', 'experience' => 0],
    ['name' => 'Silver', 'experience' => 500],
    ['name' => 'Gold', 'experience' => 2000],
    ['name' => 'Platinum', 'experience' => 5000, 'metadata' => ['color' => '#E5E4E2', 'icon' => 'crown']],
);

Tier names and experience values must be unique. Throws TierExistsException on duplicates. The metadata column is a flexible JSON field for any extra data (colours, icons, descriptions). The entire add() call is wrapped in a database transaction — if any tier fails, none are created.

Automatic Tier Promotion

Tiers update automatically when XP changes. When addPoints() causes the user to cross a tier threshold, experience.tier_id is updated and a UserTierUpdated event fires with TierDirection::Promoted.

Query Tiers

$user->getTier();                    // Current Tier model or null
$user->getNextTier();                // Next tier above current (Tier or null)
$user->tierProgress();               // Percentage 0-100 through current bracket
$user->nextTierAt();                 // XP remaining until next tier
$user->isAtTier('Gold');             // Exact match (bool)
$user->isAtOrAboveTier('Silver');    // At or above (bool)

getTier() returns null if the user has no experience record or tiers are disabled.

Demotion

By default, tiers use a high-water mark — once earned, they persist even if points decrease. Enable demotion to allow tier drops:

TIER_DEMOTION=true

When enabled, deductPoints() checks if the user should drop and fires UserTierUpdated with TierDirection::Demoted. The newTier property is nullable — it will be null if the user drops below all tier thresholds.

Tier-Scoped Multipliers

Create a multiplier and scope it to a tier so it only applies to users at that tier:

$multiplier = Multiplier::create([
    'name' => 'Gold Bonus',
    'multiplier' => 2.0,
    'is_active' => true,
]);

$goldTier = Tier::where('name', 'Gold')->first();
$multiplier->scopeTo($goldTier);

When a Gold-tier user calls addPoints(), this multiplier is automatically included.

Tier-Gated Achievements

Restrict achievements so only users at a certain tier can earn them:

$goldTier = Tier::where('name', 'Gold')->first();

Achievement::create([
    'name' => 'Golden Streak',
    'tier_id' => $goldTier->id,
]);

Attempting to grant to a user below Gold throws TierRequirementNotMet.

Tier-Scaled Streak Freezes

Higher tiers get longer freeze durations:

// config/level-up.php
'tiers' => [
    'streak_freeze_days' => [
        'Bronze' => 1,
        'Silver' => 2,
        'Gold' => 3,
        'Platinum' => 7,
    ],
],

Falls back to the global freeze_duration if the tier is not listed or tiers are disabled.

Tier-Scoped Leaderboards

use LevelUp\Experience\Facades\Leaderboard;

Leaderboard::forTier('Gold')->generate();
Leaderboard::forTier($tierModel)->generate();

Tier Config

'tiers' => [
    'enabled' => env('TIERS_ENABLED', true),
    'demotion' => env('TIER_DEMOTION', false),
    'streak_freeze_days' => [],
],

Achievements

Create Achievements

use LevelUp\Experience\Models\Achievement;

Achievement::create([
    'name' => 'First Login',
    'is_secret' => false,
    'description' => 'Log in for the first time',
    'image' => 'storage/app/achievements/first-login.png',
]);

// Secret achievement (hidden until earned)
Achievement::create([
    'name' => 'Hidden Gem',
    'is_secret' => true,
]);

// Tier-gated achievement
Achievement::create([
    'name' => 'Gold Member Badge',
    'tier_id' => $goldTier->id,
]);

Grant Achievement

$user->grantAchievement($achievement);

// With progress (0-100)
$user->grantAchievement($achievement, progress: 50);

Throws Exception if progress exceeds 100, or if the user already has the achievement. Throws TierRequirementNotMet if tier-gated and user does not meet the tier requirement. AchievementAwarded event fires only when progress is null or 100.

Revoke Achievement

$user->revokeAchievement($achievement);

Throws Exception if the user does not have the achievement.

Achievement Progress

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

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

incrementAchievementProgress() throws Exception if the user does not have the achievement. Grant it first. Progress is capped at 100.

Query Achievements

$user->achievements;               // Non-secret achievements
$user->secretAchievements;          // Secret achievements only
$user->allAchievements;            // Both
$user->getUserAchievements();      // Same as $user->achievements

Streaks

Create Activities

use LevelUp\Experience\Models\Activity;

Activity::create(['name' => 'daily-login', 'description' => 'User logs in']);

Record a Streak

$activity = Activity::where('name', 'daily-login')->first();

$user->recordStreak($activity);

• First call: creates streak (count = 1), fires StreakStarted
• Same day: no-op
• Next consecutive day: increments count, fires StreakIncreased
• Skipped a day: resets to 1, fires StreakBroken (archives if enabled)
• Streak frozen: no-op until freeze expires

Query Streaks

$user->getCurrentStreakCount($activity); // int (0 if no streak)
$user->hasStreakToday($activity);        // bool
$user->streaks;                          // HasMany relationship

Reset / Freeze / Unfreeze

$user->resetStreak($activity);
$user->freezeStreak($activity);               // Uses config or tier-scaled duration
$user->freezeStreak($activity, days: 5);       // Custom duration
$user->unFreezeStreak($activity);
$user->isStreakFrozen($activity);              // bool

Streak History

When a streak breaks, it is archived automatically (if enabled):

use LevelUp\Experience\Models\StreakHistory;

$histories = StreakHistory::where('user_id', $user->id)->get();

Streak Config

'archive_streak_history' => [
    'enabled' => env('ARCHIVE_STREAK_HISTORY_ENABLED', true),
],
'freeze_duration' => env('STREAK_FREEZE_DURATION', 1),

Challenges

Challenges are multi-condition goals that users enroll in and complete for rewards. Conditions are evaluated automatically when relevant events fire (points earned, level reached, achievement granted, streak recorded, tier changed).

Create a Challenge

use LevelUp\Experience\Models\Challenge;

Challenge::create([
    'name' => 'Getting Started',
    'conditions' => [
        ['type' => 'points_earned', 'amount' => 100],
        ['type' => 'level_reached', 'level' => 3],
    ],
    'rewards' => [
        ['type' => 'points', 'amount' => 50],
    ],
    'auto_enroll' => true,
    'is_repeatable' => false,
]);

Condition Types

Reward Types

Enrollment

$user->enrollInChallenge($challenge);
$user->unenrollFromChallenge($challenge);

Throws if: challenge not started yet, expired, already enrolled, or completed and not repeatable. Completed repeatable challenges can be re-enrolled.

Auto-enroll challenges (auto_enroll: true) automatically enroll users when a relevant event fires.

Query Progress

$user->getChallengeProgress($challenge);              // Array of condition statuses
$user->getChallengeCompletionPercentage($challenge);  // 0.0 - 100.0
$user->activeChallenges;                              // Enrolled, not completed
$user->completedChallenges;                           // Completed

Temporal Constraints

Challenges support optional starts_at and expires_at fields. If both are set, starts_at must be before expires_at. Expired challenges are not evaluated.

Custom Conditions

Implement the ChallengeCondition interface:

use LevelUp\Experience\Contracts\ChallengeCondition;
use Illuminate\Database\Eloquent\Model;

class HasVerifiedEmail implements ChallengeCondition
{
    public function check(Model $user, array $condition): bool
    {
        return $user->hasVerifiedEmail();
    }
}

Reference it in the condition: ['type' => 'custom', 'class' => HasVerifiedEmail::class].

Challenge Config

'challenges' => [
    'enabled' => env('CHALLENGES_ENABLED', true),
],

Leaderboard

use LevelUp\Experience\Facades\Leaderboard;

Leaderboard::generate();                        // All users by XP
Leaderboard::generate(paginate: true);          // Paginated
Leaderboard::generate(limit: 10);              // Top 10
Leaderboard::forTier('Gold')->generate();       // Gold tier only

Returns User models with experience relationship eager-loaded, ordered by XP descending.

Auditing

Enable in config:

'audit' => [
    'enabled' => env('AUDIT_POINTS', false),
],

When enabled, every addPoints(), deductPoints(), levelUp(), and tier change creates an experience_audits record.

$user->experienceHistory;   // HasMany to ExperienceAudit

Audit types use the AuditType enum:

use LevelUp\Experience\Enums\AuditType;

AuditType::Add;      // 'add'
AuditType::Remove;   // 'remove'
AuditType::Reset;    // 'reset'
AuditType::LevelUp;  // 'level_up'
AuditType::TierUp;   // 'tier_up'
AuditType::TierDown; // 'tier_down'

Events

Common Patterns

User Profile with Level and Tier

$user = User::with(['experience.status', 'experience.tier'])->find($id);

$data = [
    'level' => $user->getLevel(),
    'points' => $user->getPoints(),
    'next_level_in' => $user->nextLevelAt(),
    'level_progress' => $user->nextLevelAt(showAsPercentage: true),
    'tier' => $user->getTier()?->name,
    'tier_progress' => $user->tierProgress(),
    'next_tier_in' => $user->nextTierAt(),
];

Level-Up Reward via Event

use LevelUp\Experience\Events\UserLevelledUp;

Event::listen(UserLevelledUp::class, function (UserLevelledUp $event) {
    if ($event->level === 10) {
        $achievement = Achievement::where('name', 'Hit Level 10')->first();
        if ($achievement) {
            $event->user->grantAchievement($achievement);
        }
    }
});

Seeding Levels and Tiers

class GamificationSeeder extends Seeder
{
    public function run(): void
    {
        Level::add(
            ['level' => 1, 'next_level_experience' => null],
            ['level' => 2, 'next_level_experience' => 100],
            ['level' => 3, 'next_level_experience' => 250],
        );

        Tier::add(
            ['name' => 'Bronze', 'experience' => 0],
            ['name' => 'Silver', 'experience' => 500],
            ['name' => 'Gold', 'experience' => 2000],
        );

        Activity::create(['name' => 'daily-login']);
    }
}

Config Reference

All model classes in the models config array can be overridden to use custom models. The user.foreign_key defaults to user_id and can be customised for non-standard setups.

return [
    'models' => [
        'achievement' => LevelUp\Experience\Models\Achievement::class,
        'activity' => LevelUp\Experience\Models\Activity::class,
        'experience' => LevelUp\Experience\Models\Experience::class,
        'experience_audit' => LevelUp\Experience\Models\ExperienceAudit::class,
        'level' => LevelUp\Experience\Models\Level::class,
        'streak' => LevelUp\Experience\Models\Streak::class,
        'streak_history' => LevelUp\Experience\Models\StreakHistory::class,
        'achievement_user' => LevelUp\Experience\Models\Pivots\AchievementUser::class,
        'tier' => LevelUp\Experience\Models\Tier::class,
        'multiplier' => LevelUp\Experience\Models\Multiplier::class,
        'multiplier_scope' => LevelUp\Experience\Models\MultiplierScope::class,
        'challenge' => LevelUp\Experience\Models\Challenge::class,
        'challenge_user' => LevelUp\Experience\Models\Pivots\ChallengeUser::class,
    ],
    'user' => [
        'foreign_key' => 'user_id',
        'model' => App\Models\User::class,
        'users_table' => 'users',
    ],
    'table' => 'experiences',
    'starting_level' => 1,
    'multiplier' => [
        'enabled' => env('MULTIPLIER_ENABLED', true),
        'stack_strategy' => env('MULTIPLIER_STACK', 'compound'),
    ],
    'level_cap' => [
        'enabled' => env('LEVEL_CAP_ENABLED', true),
        'level' => env('LEVEL_CAP', 100),
        'points_continue' => env('LEVEL_CAP_POINTS_CONTINUE', true),
    ],
    'audit' => [
        'enabled' => env('AUDIT_POINTS', false),
    ],
    'archive_streak_history' => [
        'enabled' => env('ARCHIVE_STREAK_HISTORY_ENABLED', true),
    ],
    'freeze_duration' => env('STREAK_FREEZE_DURATION', 1),
    'tiers' => [
        'enabled' => env('TIERS_ENABLED', true),
        'demotion' => env('TIER_DEMOTION', false),
        'streak_freeze_days' => [],
    ],
    'challenges' => [
        'enabled' => env('CHALLENGES_ENABLED', true),
    ],
];

Source: cjmellor/level-up — distributed by TomeVault.