Upgrading from v1.x to v2.0 involves significant breaking changes, primarily due to the replacement of the class-based multiplier system with a database-backed model and the introduction of Tiers and Challenges.
Requirements
- PHP 8.3+ is required.
- Laravel 12 or 13 is required.
Multiplier System Migration
The Multiplier contract, MultiplierService, and MultiplierServiceProvider have been removed. Multipliers are now managed via Eloquent models in the database.
1. Run Migrations
php artisan vendor:publish --tag="level-up-migrations"
php artisan migrate
2. Update Multiplier Logic
Instead of using PHP classes with qualifies() logic, create database records. For complex logic, toggle is_active programmatically.
// After (v2): Use database records
Multiplier::create([
'name' => 'December Holiday Bonus',
'multiplier' => 2,
'is_active' => true,
'starts_at' => '2026-12-01',
'expires_at' => '2026-12-31',
]);
3. Update Tier Multipliers
If you previously used config-based tier multipliers, attach them to tiers via the database:
$multiplier = Multiplier::create([
'name' => 'Gold Tier Bonus',
'multiplier' => 2,
'is_active' => true,
]);
$multiplier->tiers()->attach(Tier::where('name', 'Gold')->first());
API Changes
addPoints(): The $multiplier parameter type changed from ?int to int|float|null. This allows fractional multipliers (e.g., 1.5).Level::add(): Now only accepts arrays.- Old:
Level::add(level: 1, pointsToNextLevel: 100); - New:
Level::add(['level' => 1, 'next_level_experience' => 100]);
- Error Handling:
$user->levelUp(to: X) now throws InvalidArgumentException if the level does not exist.$user->deductPoints(X) now throws an Exception if no experience record exists for the user.$user->incrementAchievementProgress() now throws an Exception if the user lacks the achievement.
