Allow model customisation

config/level-up.php

@@ -1,6 +1,18 @@
 <?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,
+    ],
+
     /*
     |--------------------------------------------------------------------------
     | User Foreign Key

src/Concerns/GiveExperience.php

@@ -14,7 +14,6 @@
 use LevelUp\Experience\Events\PointsIncreased;
 use LevelUp\Experience\Events\UserLevelledUp;
 use LevelUp\Experience\Models\Experience;
-use LevelUp\Experience\Models\ExperienceAudit;
 use LevelUp\Experience\Models\Level;
 use LevelUp\Experience\Services\MultiplierService;
 
@@ -34,7 +33,9 @@ public function addPoints(
             $type = AuditType::Add->value;
         }
 
-        $lastLevel = Level::orderByDesc(column: 'level')->first();
+        $levelClass = config(key: 'level-up.models.level');
+
+        $lastLevel = $levelClass::orderByDesc(column: 'level')->first();
         throw_if(
             condition: isset($lastLevel->next_level_experience) && $amount > $lastLevel->next_level_experience,
             message: 'Points exceed the last level\'s experience points.',
@@ -63,7 +64,7 @@ public function addPoints(
          * If the User does not have an Experience record, create one.
          */
         if ($this->experience()->doesntExist()) {
-            $level = Level::query()
+            $level = $levelClass::query()
                 ->where(column: 'next_level_experience', operator: '<=', value: $amount)
                 ->orderByDesc(column: 'next_level_experience')
                 ->first();
@@ -118,7 +119,7 @@ protected function getMultipliers(int $amount): int
 
     public function experience(): HasOne
     {
-        return $this->hasOne(related: Experience::class);
+        return $this->hasOne(related: config('level-up.models.experience'));
     }
 
     protected function dispatchEvent(int $amount, string $type, ?string $reason): void
@@ -146,7 +147,7 @@ public function getLevel(): int
 
     public function experienceHistory(): HasMany
     {
-        return $this->hasMany(related: ExperienceAudit::class);
+        return $this->hasMany(related: config('level-up.models.experience_audit'));
     }
 
     public function deductPoints(int $amount, ?string $reason = null): Experience
@@ -196,7 +197,9 @@ public function withMultiplierData(array|callable $data): static
 
     public function nextLevelAt(?int $checkAgainst = null, bool $showAsPercentage = false): int
     {
-        $nextLevel = Level::firstWhere(column: 'level', operator: '=', value: is_null($checkAgainst) ? $this->getLevel() + 1 : $checkAgainst);
+        $levelClass = config(key: 'level-up.models.level');
+
+        $nextLevel = $levelClass::firstWhere(column: 'level', operator: '=', value: is_null($checkAgainst) ? $this->getLevel() + 1 : $checkAgainst);
 
         if ($this->levelCapExceedsUserLevel()) {
             return 0;
@@ -206,7 +209,7 @@ public function nextLevelAt(?int $checkAgainst = null, bool $showAsPercentage =
             return 0;
         }
 
-        $currentLevelExperience = Level::firstWhere(column: 'level', operator: '=', value: $this->getLevel())->next_level_experience;
+        $currentLevelExperience = $levelClass::firstWhere(column: 'level', operator: '=', value: $this->getLevel())->next_level_experience;
 
         if ($showAsPercentage) {
             return (int) ((($this->getPoints() - $currentLevelExperience) / ($nextLevel->next_level_experience - $currentLevelExperience)) * 100);

src/Concerns/HasAchievements.php

@@ -7,7 +7,6 @@
 use LevelUp\Experience\Events\AchievementAwarded;
 use LevelUp\Experience\Events\AchievementProgressionIncreased;
 use LevelUp\Experience\Models\Achievement;
-use LevelUp\Experience\Models\Pivots\AchievementUser;
 
 trait HasAchievements
 {
@@ -33,11 +32,11 @@ public function grantAchievement(Achievement $achievement, $progress = null): vo
 
     public function achievements(): BelongsToMany
     {
-        return $this->belongsToMany(related: Achievement::class)
+        return $this->belongsToMany(related: config(key: 'level-up.models.achievement'))
             ->withTimestamps()
             ->withPivot(columns: 'progress')
             ->where('is_secret', false)
-            ->using(AchievementUser::class);
+            ->using(config(key: 'level-up.models.achievement_user'));
     }
 
     public function incrementAchievementProgress(Achievement $achievement, int $amount = 1)
@@ -53,21 +52,21 @@ public function incrementAchievementProgress(Achievement $achievement, int $amou
 
     public function allAchievements(): BelongsToMany
     {
-        return $this->belongsToMany(related: Achievement::class)
+        return $this->belongsToMany(related: config(key: 'level-up.models.achievement'))
             ->withPivot(columns: 'progress');
     }
 
     public function achievementsWithProgress(): BelongsToMany
     {
-        return $this->belongsToMany(related: Achievement::class)
+        return $this->belongsToMany(related: config(key: 'level-up.models.achievement'))
             ->withPivot(columns: 'progress')
             ->where('is_secret', false)
             ->wherePivotNotNull(column: 'progress');
     }
 
     public function secretAchievements(): BelongsToMany
     {
-        return $this->belongsToMany(related: Achievement::class)
+        return $this->belongsToMany(related: config(key: 'level-up.models.achievement'))
             ->withPivot(columns: 'progress')
             ->where('is_secret', true);
     }

src/Concerns/HasStreaks.php

@@ -12,7 +12,6 @@
 use LevelUp\Experience\Events\StreakUnfroze;
 use LevelUp\Experience\Models\Activity;
 use LevelUp\Experience\Models\Streak;
-use LevelUp\Experience\Models\StreakHistory;
 
 trait HasStreaks
 {
@@ -68,7 +67,7 @@ protected function hasStreakForActivity(Activity $activity): bool
 
     public function streaks(): HasMany
     {
-        return $this->hasMany(related: Streak::class);
+        return $this->hasMany(related: config('level-up.models.streak'));
     }
 
     protected function startNewStreak(Activity $activity): Model|Streak
@@ -112,7 +111,9 @@ protected function archiveStreak(Activity $activity): void
     {
         $latestStreak = $this->getStreakLastActivity($activity);
 
-        StreakHistory::create([
+        $streakHistoryClass = config(key: 'level-up.models.streak_history');
+
+        $streakHistoryClass::create([
             config(key: 'level-up.streaks.foreign_key', default: 'user_id') => $this->id,
             'activity_id' => $activity->id,
             'count' => $latestStreak->count,
@@ -150,7 +151,7 @@ public function freezeStreak(Activity $activity, ?int $days = null): bool
 
     public function unFreezeStreak(Activity $activity): bool
     {
-        Event::dispatch(new StreakUnfroze());
+        Event::dispatch(new StreakUnfroze);
 
         return $this->getStreakLastActivity($activity)
             ->update(['frozen_until' => null]);

src/LevelUpServiceProvider.php

@@ -37,7 +37,7 @@ public function register(): void
         parent::register();
 
         $this->app->register(provider: EventServiceProvider::class);
-        $this->app->singleton(abstract: 'leaderboard', concrete: fn () => new LeaderboardService());
+        $this->app->singleton(abstract: 'leaderboard', concrete: fn () => new LeaderboardService);
         $this->app->register(provider: MultiplierServiceProvider::class);
     }
 }

src/Listeners/PointsIncreasedListener.php

@@ -9,6 +9,8 @@ class PointsIncreasedListener
 {
     public function __invoke(PointsIncreased $event): void
     {
+        $levelModel = config(key: 'level-up.models.level');
+
         if (config(key: 'level-up.audit.enabled')) {
             $event->user->experienceHistory()->create([
                 'points' => $event->pointsAdded,
@@ -17,15 +19,15 @@ public function __invoke(PointsIncreased $event): void
             ]);
         }
 
-        if (Level::count() === 0) {
-            Level::add([
+        if ($levelModel::count() === 0) {
+            $levelModel::add([
                 'level' => config(key: 'level-up.starting_level'),
                 'next_level_experience' => null,
             ]);
         }
 
         // Get the next level experience needed for the user's current level
-        $nextLevel = Level::firstWhere(column: 'level', operator: '=', value: $event->user->getLevel() + 1);
+        $nextLevel = $levelModel::firstWhere(column: 'level', operator: '=', value: $event->user->getLevel() + 1);
 
         if (! $nextLevel) {
             // If there is no next level, return
@@ -35,7 +37,7 @@ public function __invoke(PointsIncreased $event): void
         // Check if user's points are equal or greater than the next level's required experience
         if ($event->user->getPoints() >= $nextLevel->next_level_experience) {
             // Find the highest level the user can achieve with current points
-            $highestAchievableLevel = Level::query()
+            $highestAchievableLevel = $levelModel::query()
                 ->where(column: 'next_level_experience', operator: '<=', value: $event->user->getPoints())
                 ->orderByDesc(column: 'level')
                 ->first();

src/Models/Activity.php

@@ -16,6 +16,6 @@ class Activity extends Model
 
     public function streaks(): HasMany
     {
-        return $this->hasMany(related: Streak::class);
+        return $this->hasMany(related: config(key: 'level-up.models.streak'));
     }
 }

src/Models/Experience.php

@@ -25,6 +25,6 @@ public function user(): BelongsTo
 
     public function status(): BelongsTo
     {
-        return $this->belongsTo(related: Level::class, foreignKey: 'level_id');
+        return $this->belongsTo(related: config('level-up.models.level'), foreignKey: 'level_id');
     }
 }

src/Models/Streak.php

@@ -24,6 +24,6 @@ public function user(): BelongsTo
 
     public function activity(): BelongsTo
     {
-        return $this->belongsTo(related: Activity::class);
+        return $this->belongsTo(related: config(key: 'level-up.models.activity'));
     }
 }

tests/Fixtures/Level.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace LevelUp\Experience\Tests\Fixtures;
+
+class Level extends \LevelUp\Experience\Models\Level
+{
+    public function extra_function(): string
+    {
+        return 'extra_function';
+    }
+}

tests/Models/LevelTestWithCustomModel.php

@@ -0,0 +1,41 @@
+<?php
+
+use LevelUp\Experience\Exceptions\LevelExistsException;
+
+uses()->group('levels');
+
+beforeEach(function (): void {
+    config()->set('level-up.models.level', \LevelUp\Experience\Tests\Fixtures\Level::class);
+});
+
+it(description: 'is a custom model', closure: function (): void {
+    $levelClass = config('level-up.models.level');
+
+    $level = $levelClass::add([
+        'level' => 6,
+        'next_level_experience' => 750,
+    ]);
+
+    expect(value: $level[0])->toBeInstanceOf($levelClass);
+    expect(value: $level[0]->extra_function())->toBe(expected: 'extra_function');
+});
+
+it(description: 'can create a level with custom model', closure: function (): void {
+
+    $level = config('level-up.models.level')::add([
+        'level' => 6,
+        'next_level_experience' => 750,
+    ]);
+
+    expect(value: $level[0]->level)->toBe(expected: 6);
+
+    $this->assertDatabaseHas(table: 'levels', data: [
+        'level' => 6,
+        'next_level_experience' => 750,
+    ]);
+});
+
+it(description: 'throws an error if a level exists with custom model', closure: function (): void {
+    config('level-up.models.level')::add(level: 1, pointsToNextLevel: 100);
+    config('level-up.models.level')::add(level: 1, pointsToNextLevel: 100);
+})->throws(exception: LevelExistsException::class, exceptionMessage: 'The level with number "1" already exists');

tests/Pest.php

@@ -7,7 +7,7 @@
 
 uses(TestCase::class, FastRefreshDatabase::class)
     ->beforeEach(hook: function (): void {
-        $this->user = new User();
+        $this->user = new User;
 
         $this->user->fill(attributes: [
             'name' => 'Chris Mellor',