cjmellor/level-up/level-up-development

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

use LevelUp\Experience\Concerns\GiveExperience;
use LevelUp\Experience\Concerns\HasAchievements;
use LevelUp\Experience\Concerns\HasChallenges;
use LevelUp\Experience\Concerns\HasLeagues;
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
    use HasLeagues;         // Optional — leagues (divisions/cohorts)
}

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

$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

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

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

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

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

$user->setPoints(500);

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

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

$multiplier->scopeToUser($user);                 // Specific user only
$multiplier->scopeToTier($goldTier);             // Gold tier users only
$multiplier->scopeToUser($user)->scopeToTier($tier); // Both — chains via fluent return
 
// Variadic — attach multiple of the same type in one call
$multiplier->scopeToUser($alice, $bob, $carol);
$multiplier->scopeToTier($silver, $gold, $platinum);
 
// Reverse the scope
$multiplier->unscopeFromUser($user);
$multiplier->unscopeFromTier($goldTier);
 
// Check whether a multiplier has any scopes attached
$multiplier->isGlobal();  // true when no users or tiers attached

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

'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
],

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)

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

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

TIER_DEMOTION=true

$multiplier = Multiplier::create([
    'name' => 'Gold Bonus',
    'multiplier' => 2.0,
    'is_active' => true,
]);
 
$goldTier = Tier::where('name', 'Gold')->first();
$multiplier->scopeToTier($goldTier);

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

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

use LevelUp\Experience\Facades\Leaderboard;
 
Leaderboard::forTier('Gold')->generate();
Leaderboard::forTier($tierModel)->generate();

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

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

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

$user->revokeAchievement($achievement);