Level-Up

https://github.com/cjmellor/level-up
Admin
A Laravel package that allows users to gain experience points (XP) and progress through levels,...
Tokens:113,905
Snippets:956
Trust Score:9
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Clone and install level-up locally

Source: https://github.com/cjmellor/level-up/blob/3.x/CONTRIBUTING.md

Clones the repository, changes into the project directory, and installs dependencies with Composer. The package's tests run against SQLite by default and require no further setup.

```bash
git clone https://github.com/cjmellor/level-up.git
cd level-up
composer install
```

--------------------------------

### Starting Level Configuration

Source: https://github.com/cjmellor/level-up/blob/3.x/README.md

Sets the level that a User starts with.

```php
'starting_level' => 1,
```

--------------------------------

### Install via Composer

Source: https://github.com/cjmellor/level-up/blob/3.x/README.md

Install the package using Composer. Run this command in your project root.

```bash
composer require cjmellor/level-up
```

--------------------------------

### Install level-up package and publish assets

Source: https://github.com/cjmellor/level-up/blob/3.x/resources/boost/skills/level-up-development/SKILL.md

Run these commands to install the package, publish migrations, run migrations, and publish the config file.

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

--------------------------------

### Example usage of resolveTables

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/LevelUpServiceProvider.md

Example showing how to call resolveTables with a prefix and an override, and the resulting table names for 'experiences' and 'levels'.

```php
$tables = LevelUpServiceProvider::resolveTables(
    prefix: 'lvl_',
    overrides: ['levels' => 'xp_levels'],
);

// $tables['experiences'] === 'lvl_experiences'
// $tables['levels']      === 'xp_levels'   // explicit override, no prefix
```

--------------------------------

### Leaderboard Usage Examples

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/Leaderboard.md

Shows how to generate a leaderboard for a board and get a user's rank. Both calls use the fluent board() method.

```php
Leaderboard::board('weekly-xp')->generate();
Leaderboard::board('weekly-xp')->rankOf(user: $user);
```

--------------------------------

### levelUp usage example

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/GiveExperience.md

Example call to levelUp, emitting UserLevelledUp for levels previous+1 through 5.

```php
$user->levelUp(5); // emits UserLevelledUp for levels previous+1 .. 5
```

--------------------------------

### getLevel() example

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/GiveExperience.md

Example usage of getLevel() returning the current level.

```php
$user->getLevel(); // 3
```

--------------------------------

### experienceHistory() example

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/GiveExperience.md

Example usage of experienceHistory() returning a collection of audit rows.

```php
$user->experienceHistory;   // Collection<ExperienceAudit> — audit rows including level/tier events
```

--------------------------------

### recordStreak usage example

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/HasStreaks.md

Example usage of recordStreak. Shows starting a streak, same-day no-op, and next-day increment behavior.

```php
$activity = Activity::find(1);
$user->recordStreak($activity); // day 1 → started
$user->recordStreak($activity); // same day → no-op
// next day:
$user->recordStreak($activity); // StreakIncreased, count = 2
```

--------------------------------

### Tier::add() example

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/Models-AchievementsTiers.md

Example of adding three tiers with names, experience points, and optional metadata. The method returns an array of created Tier models.

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

--------------------------------

### generate usage example

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/Leaderboard.md

Shows how to iterate over generated entries and how to use pagination and limiting with different metrics and periods.

```php
$entries = Leaderboard::generate();
foreach ($entries as $entry) {
    $entry->user;  // User (with 'experience' eager-loaded)
    $entry->score;
    $entry->rank;
}

Leaderboard::by('xp')->period(Period::Week)->generate(limit: 10);
Leaderboard::by('achievements')->period(Period::Month)->generate(paginate: true);
```

--------------------------------

### Migration example using entity key macros

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/LevelUpServiceProvider.md

Example migration-side usage of the entityId, userForeignId, and entityForeignId macros when creating the experiences table. It uses the configured table names and user table, and adds an experience_points column with a default of 0 and an index.

```php
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

Schema::create(config('level-up.tables.experiences'), function (Blueprint $table) {
    $table->entityId();
    $table->userForeignId()->constrained(config('level-up.user.users_table'));
    $table->entityForeignId('level_id')->constrained(table: config('level-up.tables.levels'));
    $table->integer('experience_points')->default(0)->index();
    $table->timestamps();
});
```

--------------------------------

### Tier::forPoints() example

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/Models-AchievementsTiers.md

Example call to forPoints with 1200 points, which would return the 'Silver' tier in the ladder defined earlier.

```php
Tier::forPoints(1200); // ?Tier — 'Silver' in the ladder above
```

--------------------------------

### around method usage example

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/Leaderboard.md

Shows two example calls to the around method: one with a range of 2 and another chained with a by('xp') modifier and a range of 3.

```php
Leaderboard::around(user: $user, range: 2);   // ≤2 above + user + ≤2 below
Leaderboard::by('xp')->around(user: $user, range: 3);
```

--------------------------------

### Invoke rollover from command

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/LeagueService.md

Example from `LeagueRolloverCommand` showing how to invoke the rollover method.

```php
resolve(LeagueService::class)->rollover();
```

--------------------------------

### Example of cohortStandings

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/LeagueService.md

Example usage of the standingsFor method, returning a collection of LeaderboardEntry with rank 1 being first in cohort.

```php
$user->cohortStandings(); // collection of LeaderboardEntry, rank 1 = first in cohort
```

--------------------------------

### deductPoints() example

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/GiveExperience.md

Example usage of deductPoints() with and without a reason.

```php
$user->deductPoints(10);
$user->deductPoints(10, reason: 'Marketplace purchase');
```

--------------------------------

### ExperienceMetric usage example

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/Metrics.md

Example usage of the ExperienceMetric. The first line generates a leaderboard for the current week, showing net points added. The second line generates an all-time leaderboard using the 'xp' key.

```php
Leaderboard::period(Period::Week)->generate();               // net points added this week
Leaderboard::by('xp')->generate();                           // all-time totals
```

--------------------------------

### Level::add usage example

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/Models-CoreExperience.md

Creates multiple levels with their next level experience thresholds.

```php
Level::add(
    ['level' => 1, 'next_level_experience' => null],
    ['level' => 2, 'next_level_experience' => 100],
    ['level' => 3, 'next_level_experience' => 250],
);
```

--------------------------------

### ExperienceAudit ledger query example

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/Models-CoreExperience.md

Shows how to retrieve ledger rows for a user using the experienceHistory relationship or a direct query.

```php
$user->experienceHistory; // ledger rows
ExperienceAudit::where('user_id', $user->id)->latest()->get();
```

--------------------------------

### getTier usage example

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/HasTiers.md

Example call to getTier(). Returns a Tier instance (e.g., Tier['Gold']) or null when no tier qualifies.

```php
$user->getTier(); // Tier['Gold'] | null
```

--------------------------------

### AchievementMetric usage example

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/Metrics.md

Generates a leaderboard for the 'achievements' metric, filtered by the current month period. This example uses the period method with Period::Month.

```php
Leaderboard::by('achievements')->period(Period::Month)->generate();
```

--------------------------------

### ChallengeMetric usage examples

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/Metrics.md

Generates leaderboards for the 'challenges' metric. The first example shows all-time completions, and the second shows completions for the current day. Note that if challenges are disabled, these calls will throw MetricDisabledException.

```php
Leaderboard::by('challenges')->generate();   // most completions ever
Leaderboard::by('challenges')->period(Period::Day)->generate();
```

--------------------------------

### nextLevelAt usage example

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/GiveExperience.md

Shows two calls: one returning absolute points remaining to the next level, and one returning the percentage through the current level band.

```php
$user->nextLevelAt();                 // 50 — points until level 2
$user->nextLevelAt(showAsPercentage: true); // 50 — halfway through level 1
```

--------------------------------

### getUserAchievements usage example

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/HasAchievements.md

Example usage of getUserAchievements, returning a Collection of non-secret achievements.

```php
$user->getUserAchievements(); // Collection<Achievement> (non-secret only)
```

--------------------------------

### Creating an Achievement

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/Models-AchievementsTiers.md

Shows how to create an Achievement instance directly using the create method, as no static helper exists. The example includes name, is_secret, description, and image fields.

```php
$achievement = Achievement::create([
    'name' => 'Hit Level 20',
    'is_secret' => false,
    'description' => 'When a User hits Level 20',
    'image' => 'storage/app/achievements/level-20.png',
]);
```

--------------------------------

### setPoints usage example

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/GiveExperience.md

Forces a level change by directly setting points without creating an audit entry. Requires an existing experience record.

```php
$user->setPoints(10_000); // force a level, without an audit entry
```

--------------------------------

### Schedule level-up:league-rollover weekly

Source: https://github.com/cjmellor/level-up/blob/3.x/resources/boost/skills/level-up-development/SKILL.md

Example host scheduling for the league rollover command, run just after the period boundary. This command is never auto-registered; it must be scheduled manually. The example uses a Monday-start weekly league at 00:05.

```php
Schedule::command('level-up:league-rollover')->weeklyOn(1, '00:05')
```

--------------------------------

### Example HasVerifiedEmail implementing ChallengeCondition

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/Contracts.md

Example implementation from the README. The class imports the ChallengeCondition contract and Eloquent Model, then implements the check method to return whether the user's email is verified. Return true to mark the condition complete, with progress persisting at the pivot level through the standard pipeline.

```php
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();
    }
}
```

--------------------------------

### Example usage of getChallengeProgress

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/ChallengeService.md

Example usage of the initializeProgress method via the trait. It returns an array of progress entries, index-aligned with the challenge's conditions, showing a points_earned entry with a baseline and a level_reached entry.

```php
$user->getChallengeProgress($challenge);
// [['type' => 'points_earned', 'completed' => false, 'baseline' => 120], ['type' => 'level_reached', 'completed' => true]]
```

--------------------------------

### restrictTo usage example

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/Leaderboard.md

Restricts the board to a custom population, such as friends. The example collects friend IDs and applies a whereIn constraint.

```php
$friendIds = $user->friends()->pluck('id')->push($user->id);
Leaderboard::restrictTo(fn ($query) => $query->whereIn('id', $friendIds))->generate();
```

--------------------------------

### AI prompt: convert existing install to uuid or ulid

Source: https://github.com/cjmellor/level-up/blob/3.x/README.md

Paste into an AI assistant to generate Laravel migrations for converting an existing install from bigint to the target type. Replace <TARGET> with 'uuid' or 'ulid' and <DB> with 'postgres', 'mysql', or 'sqlite'. The prompt instructs the assistant to add new id columns, migrate foreign keys, and re-establish constraints without touching user_id columns.

```text
I'm switching cjmellor/level-up's `entities.id_type` from `bigint` to `<TARGET>` on an existing `<DB>` install.

Generate a Laravel migration (or sequence of migrations) that:

1. For every level-up package table (experiences, levels, achievements, achievement_user, streak_activities, streaks, streak_histories, tiers, multipliers, multiplier_user, multiplier_tier, challenges, challenge_user, experience_audits): add a new `<TARGET>` column called `id_new`, generate a unique value for every existing row, then later drop the old `id` and rename `id_new` to `id`.

2. For every internal foreign key column (`level_id`, `activity_id`, `achievement_id`, `challenge_id`, `tier_id`, `multiplier_id`, etc.): add a corresponding `_new` column, populate it by joining on the parent table's new ids, then drop the old column and rename.

3. Re-establish primary key and foreign key constraints in the correct order. Wrap in a transaction if `<DB>` supports DDL transactions.

Constraints:
- Do NOT change `user_id` columns in any package table — those follow the host's `users` table type and are controlled by `level-up.user.foreign_key_type` separately.
- After the migration runs, update `level-up.entities.id_type` in `config/level-up.php` to `<TARGET>`.
```

--------------------------------

### Archive streak history example

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/Models-Streaks.md

Shows how to retrieve all archived streak runs and how to reset a user's streak, which archives the current run when enabled.

```php
StreakHistory::all(); // every archived streak run
$user->resetStreak($activity); // archives the current run first (when enabled)
```

--------------------------------

### Create a Challenge with conditions and rewards

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/Models-Challenges.md

Example of creating a Challenge with conditions, rewards, and scheduling. Validates that conditions and rewards follow the rule tables and that starts_at is before expires_at.

```php
Challenge::create([
    'name' => 'Welcome Warrior',
    'conditions' => [
        ['type' => 'points_earned', 'amount' => 100],
        ['type' => 'level_reached', 'level' => 5],
    ],
    'rewards' => [['type' => 'points', 'amount' => 500]],
    'auto_enroll' => true,
    'is_repeatable' => false,
    'starts_at' => '2026-04-01 00:00:00',
    'expires_at' => '2026-04-30 23:59:59',
]);
```

--------------------------------

### StreakMetric usage example

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/Metrics.md

Generates a leaderboard using a StreakMetric with a specific activity. Using 'streak' alone throws MetricRequiresActivityException.

```php
Leaderboard::by(new StreakMetric(activity: $activity))->generate();
// by('streak') alone → MetricRequiresActivityException
```

--------------------------------

### nextTierAt

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/HasTiers.md

Gets the XP needed to reach the next tier.

```APIDOC
## nextTierAt

### Description
Returns the XP remaining until the next tier, or 0 if already at the top tier.

### Method
PHP method

### Endpoint
`nextTierAt(): int`

### Parameters
None

### Response
- **Type**: `int` - XP remaining until next tier.

### Example
```php
$user->nextTierAt(); // 100
```
```

--------------------------------

### Increment achievement progress example

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/HasAchievements.md

Example usage of incrementAchievementProgress. The first call adds 1 progress; the second adds 10 progress and 1 count. The method requires the achievement to have been granted first.

```php
$user->incrementAchievementProgress($achievement);                       // +1 progress
$user->incrementAchievementProgress($achievement, amount: 10, count: 1); // +10 progress, +1 count
```

--------------------------------

### Example: creating a Level with ULID id

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/HasConfigurableIds.md

Example usage of the HasConfigurableIds trait with a 'ulid' id_type. Creates a Level record and shows the resulting lowercased ULID id.

```php
// config: 'entities' => ['id_type' => 'ulid']
$level = Level::create(['level' => 1, 'next_level_experience' => null]);
$level->id; // "01hy...a" (lowercased ULID)
```

--------------------------------

### isAtOrAboveTier usage example

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/HasTiers.md

Example call to isAtOrAboveTier(). Returns true when the user's current tier is Gold (or higher) compared to Silver.

```php
$user->isAtOrAboveTier('Silver'); // true when Gold
```

--------------------------------

### freezeStreak usage examples

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/HasStreaks.md

Shows two ways to call freezeStreak: with default days (1 day) and with an explicit days parameter of 5.

```php
$user->freezeStreak($activity);        // 1 day (default)
$user->freezeStreak($activity, days: 5);
```

--------------------------------

### LevelMetric usage example

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/Metrics.md

Generates a leaderboard using the 'level' key. Users on the same level share a rank.

```php
Leaderboard::by('level')->generate(); // users on the same level share a rank
```

--------------------------------

### Multiplier querying example: active, scheduled, expired

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/Models-Multipliers.md

Shows how to query multipliers using the active, scheduled, and expired scopes.

```php
Multiplier::active()->forUser($user)->get();  // applied to the user right now
Multiplier::scheduled()->get();               // armed in the future
Multiplier::expired()->get();                 // past expires_at
```

--------------------------------

### Define Levels with Level::add

Source: https://github.com/cjmellor/level-up/blob/3.x/resources/boost/skills/level-up-development/SKILL.md

Defines the level thresholds for the experience system. Level 1 must have `next_level_experience` set to `null` as the default starting point. Users level up automatically when their XP reaches the threshold. Throws `LevelExistsException` if a level number already exists.

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

--------------------------------

### Configure week start and timezone for periods

Source: https://github.com/cjmellor/level-up/blob/3.x/README.md

Set `week_starts_on` to choose the day `Period::Week` starts on (0=Sunday to 6=Saturday) and `timezone` to control the timezone for period boundaries. The `timezone` defaults to `null`, meaning the application timezone is used.

```php
'leaderboard' => [
    // ...
    'week_starts_on' => Carbon\CarbonInterface::MONDAY, // 0 (Sunday) – 6 (Saturday)
    'timezone' => null, // null = the application timezone
],
```

--------------------------------

### Get Points

Source: https://github.com/cjmellor/level-up/blob/3.x/resources/boost/skills/level-up-development/SKILL.md

Returns the user's current XP as an integer, returning 0 if no experience record exists.

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

--------------------------------

### getCurrentStreakCount usage example

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/HasStreaks.md

Example call to get the current streak count for a user's activity, returning an integer (e.g., 2).

```php
$user->getCurrentStreakCount($activity); // 2
```

--------------------------------

### Combine restrictTo() with period() and rankOf()

Source: https://github.com/cjmellor/level-up/blob/3.x/README.md

These examples show composing `restrictTo()` with `period()` for a weekly friends board and with `rankOf()` to get a user's rank among friends. The rank is `null` if the user is outside the restriction. The restriction works with any host-defined population, not just friends.

```php
// This week's XP, friends only
Leaderboard::restrictTo(fn ($query) => $query->whereIn('id', $friendIds))
    ->period(Period::Week)
    ->generate();

// Your rank among your friends — null if you're outside the restriction
Leaderboard::restrictTo(fn ($query) => $query->whereIn('id', $friendIds))->rankOf(user: $user);
```

--------------------------------

### Publish and run v3 migrations

Source: https://github.com/cjmellor/level-up/blob/3.x/resources/boost/skills/level-up-upgrade-v3/SKILL.md

Publishes the new v3 migration files and runs them. The publish command copies the migration files for the new tables: leaderboard_snapshots, divisions, cohorts, cohort_user, and challenge_completions. The migrate command runs the migrations, including the automatic migrate_multiplier_scopes_to_typed_pivots migration and the create_challenge_completions_table migration that backfills the ledger with one row per already-completed challenge.

```bash
php artisan vendor:publish --tag="level-up-migrations"
php artisan migrate
```

--------------------------------

### Multiplier usage example: create, scope, isGlobal, unscope

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/Models-Multipliers.md

Shows creating a multiplier, scoping it to a user and tier, checking if it's global, and unscoping from a tier.

```php
$m = Multiplier::create(['name' => 'Weekend', 'multiplier' => 2, 'is_active' => true]);
$m->scopeToUser($user)->scopeToTier($goldTier);   // idempotent
$m->isGlobal();                                    // false
$m->unscopeFromTier($goldTier);
```

--------------------------------

### Run tests

Source: https://github.com/cjmellor/level-up/blob/3.x/resources/boost/skills/level-up-upgrade-v3/SKILL.md

Runs the test suite to verify the v3 upgrade. If any tests fail, the source suggests walking back through the previous steps, as most v3 breakage is straightforward find-and-replace.

```bash
php artisan test
```

--------------------------------

### since

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/Leaderboard.md

Scopes to a custom [start, until) time window, open-ended when until is null. Timestamps are converted using CarbonImmutable and the application timezone.

```APIDOC
## `since`

### Signature
```php
public function since(CarbonInterface $start, ?CarbonInterface $until = null): static
```

### Description
Scopes to a custom `[start, until)` window (open-ended when `until` is `null`). Timestamps are converted with `CarbonImmutable::instance(...)->setTimezone(app.timezone)`.

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `start` | `CarbonInterface` | yes | — | Window start (inclusive). |
| `until` | `?CarbonInterface` | no | `null` | Window end (exclusive). |

### Throws
`MetricNotWindowableException::forMetric($metric)` on a non-Windowable metric.

### Source
`src/Services/LeaderboardService.php:92-103`
```

--------------------------------

### bootingPackage method

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/LevelUpServiceProvider.md

Defines the bootingPackage hook in the service provider, invoked while the package is booting, which calls registerEntityKeyMacros(). The source is LevelUpServiceProvider.php:55-58.

```php
public function bootingPackage(): void

```

--------------------------------

### Migrating from config-based tier multipliers

Source: https://github.com/cjmellor/level-up/blob/3.x/UPGRADE.md

Shows how to create a multiplier and attach it to a specific tier using the `tiers()` relationship. This replaces the old config-based tier multipliers. The example creates a 'Gold Tier Bonus' multiplier and attaches it to the 'Gold' tier.

```php
$multiplier = Multiplier::create([
    'name' => 'Gold Tier Bonus',
    'multiplier' => 2,
    'is_active' => true,
]);

$multiplier->tiers()->attach(Tier::where('name', 'Gold')->first());
```

--------------------------------

### Config Reference

Source: https://github.com/cjmellor/level-up/blob/3.x/resources/boost/skills/level-up-development/SKILL.md

Full configuration array for the Level Up package. All model classes in the 'models' array can be overridden with custom models. The 'user.foreign_key' defaults to 'user_id' and can be customized for non-standard setups.

```php
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_user' => LevelUp\Experience\Models\Pivots\MultiplierUser::class,
        'multiplier_tier' => LevelUp\Experience\Models\Pivots\MultiplierTier::class,
        'challenge' => LevelUp\Experience\Models\Challenge::class,
        'challenge_user' => LevelUp\Experience\Models\Pivots\ChallengeUser::class,
        'challenge_completion' => LevelUp\Experience\Models\ChallengeCompletion::class,
        'leaderboard_snapshot' => LevelUp\Experience\Models\LeaderboardSnapshot::class,
        'division' => LevelUp\Experience\Models\Division::class,
        'cohort' => LevelUp\Experience\Models\Cohort::class,
        'cohort_user' => LevelUp\Experience\Models\Pivots\CohortUser::class,
    ],
    'user' => [
        'foreign_key' => 'user_id',
        'model' => App\Models\User::class,
        'users_table' => 'users',
    ],
    'leaderboard' => [
        'default_metric' => 'xp',
        'metrics' => [
            'xp' => LevelUp\Experience\Metrics\ExperienceMetric::class,
            'level' => LevelUp\Experience\Metrics\LevelMetric::class,
            'streak' => LevelUp\Experience\Metrics\StreakMetric::class,
            'achievements' => LevelUp\Experience\Metrics\AchievementMetric::class,
            'challenges' => LevelUp\Experience\Metrics\ChallengeMetric::class,
        ],
        'boards' => [],
        'snapshots' => [
            'retention_days' => 30,
        ],
        'league' => [
            'board' => null,
            'cohort_size' => 30,
            'divisions' => [],
        ],
        'week_starts_on' => Carbon\CarbonInterface::MONDAY,
        'timezone' => null,
    ],
    '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', true),
    ],
    '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),
    ],
];
```

--------------------------------

### revokeAchievement usage example

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/HasAchievements.md

Example usage of revokeAchievement to revoke an achievement from a user.

```php
$user->revokeAchievement($achievement);
```

--------------------------------

### Get points until next level with $user->nextLevelAt()

Source: https://github.com/cjmellor/level-up/blob/3.x/README.md

Call this method on a User model to see how many points are needed until the next level.

```php
$user->nextLevelAt();
```

--------------------------------

### Suggested scheduling for level-up:snapshot-boards

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/Commands.md

Suggested Laravel scheduler entry to run the command hourly.

```php
Schedule::command('level-up:snapshot-boards')->hourly();
```

--------------------------------

### Retrieve a User's points

Source: https://github.com/cjmellor/level-up/blob/3.x/README.md

Gets the current total experience points for a user.

```php
$user->getPoints();
```

--------------------------------

### Migration summary output

Source: https://github.com/cjmellor/level-up/blob/3.x/resources/boost/skills/level-up-upgrade-v3/SKILL.md

Example output shown when the migration successfully migrates existing multiplier_scopes data. The exact numbers (47, 32, 15) are illustrative; the actual output will reflect the user's data. If the migration encounters rows with an unrecognized scopeable_type, it logs a warning and skips them, losing those rows.

```text
  level-up: migrated 47 multiplier scope rows (32 user, 15 tier) into typed pivot tables; dropped multiplier_scopes.
```

--------------------------------

### Manually enroll a user in a challenge

Source: https://github.com/cjmellor/level-up/blob/3.x/README.md

Enrolls a user in a challenge manually. Throws if the challenge hasn't started, has expired, or the user is already enrolled.

```php
$challenge = Challenge::find(1);

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

--------------------------------

### Custom RankingMetric example (PostCountMetric)

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/Contracts.md

Implements a custom `RankingMetric` that counts a user's posts. The `scoreExpression()` uses a correlated subquery on the user table. The config comment shows how to register the metric under `level-up.leaderboard.metrics`, and the final line demonstrates generating the leaderboard with `Leaderboard::by('posts')->generate()`.

```php
use LevelUp\Experience\Contracts\RankingMetric;

class PostCountMetric implements RankingMetric
{
    public function key(): string       { return 'posts'; }
    public function label(): string     { return 'Posts'; }
    public function enabled(): bool     { return true; }

    public function constrain(EloquentBuilder $query): EloquentBuilder
    {
        return $query->whereHas('posts');
    }

    public function scoreExpression(): Builder
    {
        return Post::query()->toBase()
            ->selectRaw('COUNT(*)')
            ->whereColumn('user_id', '=', config('level-up.user.users_table').'.id');
    }
}

// config: 'leaderboard' => ['metrics' => ['posts' => PostCountMetric::class]]
Leaderboard::by('posts')->generate();
```

--------------------------------

### Example usage of getChallengeCompletionPercentage

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/HasChallenges.md

Example usage of the getChallengeCompletionPercentage method. The comment shows the expected return value when one of two conditions is met.

```php
$user->getChallengeCompletionPercentage($challenge); // 50.0 — 1 of 2 conditions met
```

--------------------------------

### Sync a fork and create a v2.x bug-fix branch

Source: https://github.com/cjmellor/level-up/blob/3.x/CONTRIBUTING.md

Sets up an upstream remote and shows how to sync a fork with the main branch. Also demonstrates creating a bug-fix branch from the 2.x branch for v2.x changes.

```bash
# Add the upstream remote
git remote add upstream https://github.com/cjmellor/level-up.git

# Keep your fork in sync
git fetch upstream
git checkout main
git merge upstream/main
git push origin main

# For a v2.x bug fix, work from the 2.x branch instead:
git checkout -b fix/my-bug-fix upstream/2.x
```

--------------------------------

### Register Blueprint macros for entity keys

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/LevelUpServiceProvider.md

Registers three Blueprint macros used by published migrations. Each macro is installed only if not already defined via Blueprint::hasMacro.

```php
protected function registerEntityKeyMacros(): void
```

--------------------------------

### Configure a League with divisions and cohort size

Source: https://github.com/cjmellor/level-up/blob/3.x/resources/boost/skills/level-up-development/SKILL.md

Configuration for a League under level-up.leaderboard.league. The board must be a declared Board with a period; null (default) makes the league dormant. Divisions are ordered bottom to top, with promote/relegate counts consumed by the period rollover. Validation is loud on first enrollment: undeclared board throws BoardNotFoundException, board without a period throws LeagueBoardNotPeriodicException, and empty divisions throws LeagueDivisionsNotDeclaredException.

```php
'league' => [
    'board' => 'weekly-xp', // must be a declared Board with a 'period'; null (default) = dormant
    'cohort_size' => 30,
    'divisions' => [        // the ladder, ordered bottom to top
        'Bronze' => ['promote' => 10, 'relegate' => 0],
        'Silver' => ['promote' => 7, 'relegate' => 5],
        'Gold' => ['promote' => 0, 'relegate' => 5],
    ],
],
```

--------------------------------

### Update Leaderboard::generate() iteration for v3

Source: https://github.com/cjmellor/level-up/blob/3.x/resources/boost/skills/level-up-upgrade-v3/SKILL.md

Before (v2.x) and After (v3.0) examples for iterating leaderboard results. In v3, terminal calls return LeaderboardEntry objects instead of User models; update code that iterated users directly.

```php
foreach (Leaderboard::generate() as $user) {
    $user->name;
    $user->experience->experience_points;
}
```

```php
foreach (Leaderboard::generate() as $entry) {
    $entry->user->name;  // the User model (experience still eager-loaded)
    $entry->score;       // the user's score on the board's metric
    $entry->rank;        // competition rank — tied scores share a rank (1, 1, 3)
}
```

--------------------------------

### Combine prefix and specific renames

Source: https://github.com/cjmellor/level-up/blob/3.x/README.md

This config shows how to combine a prefix with specific overrides. The 'levels' table is renamed to 'xp_levels' without the prefix, while all other tables get the 'lvl_' prefix.

```php
'table_prefix' => 'lvl_',
'tables' => [
    'levels' => 'xp_levels',  // → 'xp_levels' (NO prefix)
    // others stay default → all become 'lvl_<default>'
],
```

--------------------------------

### Level::add() array form migration

Source: https://github.com/cjmellor/level-up/blob/3.x/UPGRADE.md

Shows the before and after for the `Level::add()` method. The scalar form is removed in v2; use the array form instead. The example shows the v1 call with named arguments and the v2 call with an array.

```php
// Before (v1)
Level::add(level: 1, pointsToNextLevel: 100);

// After (v2)
Level::add(['level' => 1, 'next_level_experience' => 100]);
```

--------------------------------

### Query Level and XP with getLevel, getPoints, nextLevelAt

Source: https://github.com/cjmellor/level-up/blob/3.x/resources/boost/skills/level-up-development/SKILL.md

Queries the user's current level, XP total, and progress toward the next level. `getLevel()` and `getPoints()` return 0 if there is no experience. `nextLevelAt()` can be customized with `checkAgainst` to target a specific level or `showAsPercentage` to return progress as a 0-100 percentage.

```php
$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
```

--------------------------------

### Publish Config File

Source: https://github.com/cjmellor/level-up/blob/3.x/README.md

Publish the configuration file using the 'level-up-config' tag.

```bash
php artisan vendor:publish --tag="level-up-config"
```

--------------------------------

### Create activity and record streak

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/Models-Streaks.md

Creates an Activity with the name 'daily-login' and records a streak for the user with that activity.

```php
$activity = Activity::create(['name' => 'daily-login']);
$user->recordStreak($activity);
```

--------------------------------

### Use custom time range with since()

Source: https://github.com/cjmellor/level-up/blob/3.x/README.md

Use `since()` to define an open-ended start or a bounded `[start, until)` window for a periodic leaderboard. The windowed score is the sum of points added minus removed in the window from the `experience_audits` ledger.

```php
Leaderboard::since(start: now()->subDays(3))->generate();

Leaderboard::since(start: $seasonStart, until: $seasonEnd)->generate();
```

--------------------------------

### Get a user's rank and surrounding entries

Source: https://github.com/cjmellor/level-up/blob/3.x/README.md

Use rankOf() to get a single user's exact rank, or around() to fetch a slice of the board around them. Both return null or empty collection if the user is absent. Both compose with by().

```php
Leaderboard::rankOf(user: $user); // 4 — or null if the user isn't on the board

Leaderboard::around(user: $user, range: 2); // up to 2 entries above + the user + up to 2 below
```

```php
Leaderboard::by('xp')->rankOf(user: $user);
Leaderboard::by(MyCustomMetric::class)->around(user: $user, range: 3);
```

--------------------------------

### Run tests with Composer

Source: https://github.com/cjmellor/level-up/blob/3.x/README.md

Executes the test suite for the package using Composer. Run this command from the project root to verify the package works as expected.

```bash
composer test
```

--------------------------------

### GET /api/multipliers/expired

Source: https://github.com/cjmellor/level-up/blob/3.x/README.md

Retrieves all multipliers that are past their `expires_at`.

```APIDOC
## [GET] /api/multipliers/expired

### Description
Retrieves all multipliers that are past their `expires_at`.

### Method
GET

### Endpoint
/api/multipliers/expired

### Response
#### Success Response (200)
- **multipliers** (array) - List of expired multipliers.

#### Response Example
{
  "multipliers": []
}
```

--------------------------------

### GET /api/multipliers/active

Source: https://github.com/cjmellor/level-up/blob/3.x/README.md

Retrieves all currently active multipliers.

```APIDOC
## [GET] /api/multipliers/active

### Description
Retrieves all currently active multipliers.

### Method
GET

### Endpoint
/api/multipliers/active

### Response
#### Success Response (200)
- **multipliers** (array) - List of active multipliers.

#### Response Example
{
  "multipliers": []
}
```

--------------------------------

### getNextTier

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/HasTiers.md

Gets the next tier above the current one.

```APIDOC
## getNextTier

### Description
Returns the next tier strictly above the current one, or the lowest tier if the user has none.

### Method
PHP method

### Endpoint
`getNextTier(?Tier $currentTier = null): ?Tier`

### Parameters
#### Parameters
- **currentTier** (`?Tier`) - Optional - Tier to measure from; defaults to `getTier()`.

### Response
- **Type**: `?Tier` - The next tier or null.

### Example
```php
$user->getNextTier(); // Tier['Platinum'] | null
```
```

--------------------------------

### Leaderboard Configuration

Source: https://github.com/cjmellor/level-up/blob/3.x/README.md

Configures the leaderboard. 'metrics' maps registry keys to RankingMetric classes; 'default_metric' is used when no metric is specified. 'week_starts_on' sets the boundary of Period::Week as a Carbon day-of-week number (0-6), defaulting to Monday. 'timezone' controls period boundaries; null uses the application timezone. 'boards' declares named Boards; each entry maps a board name to a 'metric' (required), optional 'period', 'tier', and 'track_top' (default 100). 'snapshots.retention_days' controls how long snapshot runs are kept; the level-up:snapshot-boards command prunes older runs. 'league' declares a League with 'board' (must be declared under 'boards' and have a 'period'), 'cohort_size' (default 30), and 'divisions' (ladder with 'promote' and 'relegate' counts).

```php
'leaderboard' => [
    'default_metric' => 'xp',
    'metrics' => [
        'xp' => LevelUp\Experience\Metrics\ExperienceMetric::class,
        'level' => LevelUp\Experience\Metrics\LevelMetric::class,
        'streak' => LevelUp\Experience\Metrics\StreakMetric::class,
        'achievements' => LevelUp\Experience\Metrics\AchievementMetric::class,
        'challenges' => LevelUp\Experience\Metrics\ChallengeMetric::class,
    ],
    'boards' => [],
    'snapshots' => [
        'retention_days' => 30,
    ],
    'league' => [
        'board' => null,
        'cohort_size' => 30,
        'divisions' => [],
    ],
    'week_starts_on' => Carbon\CarbonInterface::MONDAY,
    'timezone' => null,
],
```

--------------------------------

### LeaderboardService Class Properties and Constructor

Source: https://github.com/cjmellor/level-up/blob/3.x/_autodocs/api-reference/Leaderboard.md

Fluent and stateful service class. Builder methods accumulate context; terminal methods consume and reset it. Constructor stores the user model from config.

```php
class LeaderboardService
{
    private readonly string $userModel;

    private ?Tier $tier = null;
    private ?RankingMetric $metric = null;
    private ?PeriodRange $range = null;
    private ?Closure $restriction = null;

    public function __construct()
```

--------------------------------

### GET /streak-history

Source: https://github.com/cjmellor/level-up/blob/3.x/README.md

Retrieves all archived streak history records.

```APIDOC
## [GET] /streak-history

### Description
Retrieves all archived streak history records.

### Method
GET

### Endpoint
/streak-history

### Parameters
No parameters documented.

### Request Example
```php
use LevelUp\Experience\Models\StreakHistory;
StreakHistory::all();
```

### Response
#### Success Response (200)
- Returns a collection of StreakHistory models.

#### Response Example
No response example provided.

```

--------------------------------

### Retrieve All Achievements

Source: https://github.com/cjmellor/level-up/blob/3.x/README.md

Gets all achievements, both secret and non-secret, for the user.

```php
$user->allAchievements;
```

--------------------------------

### Retrieve Secret Achievements

Source: https://github.com/cjmellor/level-up/blob/3.x/README.md

Gets all secret achievements for the user.

```php
$user->secretAchievements;
```

--------------------------------

### Generate and query leaderboards with LevelUp\Experience\Facades\Leaderboard

Source: https://github.com/cjmellor/level-up/blob/3.x/resources/boost/skills/level-up-development/SKILL.md

Shows the fluent Leaderboard facade API for generating and querying leaderboards. Supports pagination, limits, metric selection via by(), period and since filters, tier restriction, host-restricted populations via restrictTo(), named boards, and rank queries. Returns LeaderboardEntry objects with user, score, and rank; ranks use competition semantics (ties share a rank, next rank skipped) and are board-wide even when limiting or paginating. Requires SQLite 3.25+, MySQL 8+ / MariaDB 10.2+, or PostgreSQL for window functions.

```php
use LevelUp\Experience\Enums\Period;
use LevelUp\Experience\Facades\Leaderboard;
use LevelUp\Experience\Metrics\StreakMetric;

Leaderboard::generate();                        // Default metric (XP), score descending
Leaderboard::generate(paginate: true);          // Paginated
Leaderboard::generate(limit: 10);              // Top 10
Leaderboard::by('xp')->generate();              // Explicit metric key
Leaderboard::by('level')->generate();           // Rank by current level
Leaderboard::by(new StreakMetric(activity: $activity))->generate(); // Rank by current streak count for an Activity
Leaderboard::by('achievements')->generate();    // Rank by achievements earned (secret ones count)
Leaderboard::by('challenges')->period(Period::Week)->generate(); // Challenges completed this week
Leaderboard::by(MyMetric::class)->generate();   // Custom metric (class or instance)
Leaderboard::forTier('Gold')->generate();       // Gold tier only
Leaderboard::restrictTo(fn ($query) => $query->whereIn('id', $friendIds))->generate(); // Host-restricted population (e.g. friends board)
Leaderboard::period(Period::Week)->generate();  // Points earned this week (also Period::Day / Period::Month)
Leaderboard::since(start: now()->subDays(3))->generate(); // Custom range; optional until: bounds it
Leaderboard::board('weekly-xp')->generate();    // Resolve a named Board declared in config
Leaderboard::rankOf(user: $user);               // Exact rank (int), null if absent from the board
Leaderboard::around(user: $user, range: 2);     // Up to 2 entries above + user + up to 2 below; empty if absent
```

--------------------------------

### Select a leaderboard metric with by()

Source: https://github.com/cjmellor/level-up/blob/3.x/README.md

Select a metric explicitly using by() with a registry key, class-string, or metric instance. Unknown keys throw MetricNotFoundException; disabled features throw MetricDisabledException.

```php
Leaderboard::by('xp')->generate();
Leaderboard::by(MyCustomMetric::class)->generate();
Leaderboard::by(new MyCustomMetric())->generate();
```

--------------------------------

### Retrieve User Achievements

Source: https://github.com/cjmellor/level-up/blob/3.x/README.md

Gets all achievements earned by the user.

```php
$user->getUserAchievements();
```

--------------------------------

### Replace 'table' config key with 'tables.experiences'

Source: https://github.com/cjmellor/level-up/blob/3.x/UPGRADE.md

Shows the before and after for the configuration change from the deprecated 'table' key to the new 'tables.experiences' key. Update your published config file accordingly.

```php
// Before (in your published config/level-up.php)
'table' => 'my_experiences',

// After
'tables' => [
    'experiences' => 'my_experiences',
    // ... other table overrides
],
```

--------------------------------

### GET /api/multipliers/scheduled

Source: https://github.com/cjmellor/level-up/blob/3.x/README.md

Retrieves all multipliers that are armed but have a `starts_at` in the future.

```APIDOC
## [GET] /api/multipliers/scheduled

### Description
Retrieves all multipliers that are armed but have a `starts_at` in the future.

### Method
GET

### Endpoint
/api/multipliers/scheduled

### Response
#### Success Response (200)
- **multipliers** (array) - List of scheduled multipliers.

#### Response Example
{
  "multipliers": []
}
```

--------------------------------

### Get current level with $user->getLevel()

Source: https://github.com/cjmellor/level-up/blob/3.x/README.md

Call this method on a User model to retrieve the user's current level.

```php
$user->getLevel();
```
Tokens:
Raw