Merge pull request #91 from cjmellor/add-better-methods

feat: Add Extra Methods

README.md

@@ -370,18 +370,6 @@ Achievement::create([
 ]);
 ```
 
-### Revoke Achievement
-
-You can revoke an achievement from a user using the `revokeAchievement` method:
-
-```php
-$user->revokeAchievement($achievement);
-```
-
-The method will throw an exception if you try to revoke an achievement that the user doesn't have. You can revoke both standard and secret achievements, and it will also remove any associated progress.
-
-When an achievement is revoked, a `AchievementRevoked` event is dispatched.
-
 ### Gain Achievement
 
 To use Achievements in your User model, you must first add the Trait.
@@ -410,9 +398,21 @@ $user->grantAchievement($achievement);
 To retrieve your Achievements:
 
 ```php
-$user->achievements;
+$user->getUserAchievements();
 ```
 
+### Revoke Achievement
+
+You can revoke an achievement from a user using the `revokeAchievement` method:
+
+```php
+$user->revokeAchievement($achievement);
+```
+
+The method will throw an exception if you try to revoke an achievement that the user doesn't have. You can revoke both standard and secret achievements, and it will also remove any associated progress.
+
+When an achievement is revoked, a `AchievementRevoked` event is dispatched.
+
 ### Add progress to Achievement
 
 ```php
@@ -436,11 +436,7 @@ $user->achievementsWithProgress()->get();
 Check Achievements that have a certain amount of progression:
 
 ```php
-$user->achievements
-    ->first()
-    ->pivot()
-    ->withProgress(25)
-    ->get();
+$user->achievementsWithSpecificProgress(25)->get();
 ```
 
 ### Increase Achievement Progression

src/Concerns/HasAchievements.php

@@ -4,6 +4,7 @@
 
 use Exception;
 use Illuminate\Database\Eloquent\Relations\BelongsToMany;
+use Illuminate\Support\Collection;
 use LevelUp\Experience\Events\AchievementAwarded;
 use LevelUp\Experience\Events\AchievementProgressionIncreased;
 use LevelUp\Experience\Events\AchievementRevoked;
@@ -57,6 +58,11 @@ public function incrementAchievementProgress(Achievement $achievement, int $amou
         return $newProgress;
     }
 
+    public function getUserAchievements(): Collection
+    {
+        return $this->achievements;
+    }
+
     public function achievementsWithProgress(): BelongsToMany
     {
         return $this->belongsToMany(related: config(key: 'level-up.models.achievement'))
@@ -65,6 +71,12 @@ public function achievementsWithProgress(): BelongsToMany
             ->wherePivotNotNull(column: 'progress');
     }
 
+    public function achievementsWithSpecificProgress(int $progress): BelongsToMany
+    {
+        return $this->achievements()
+            ->wherePivot(column: 'progress', operator: '>=', value: $progress);
+    }
+
     public function secretAchievements(): BelongsToMany
     {
         return $this->belongsToMany(related: config(key: 'level-up.models.achievement'))

tests/Concerns/HasAchievementsTest.php

@@ -13,7 +13,7 @@
 test(description: 'a User can earn an Achievement', closure: function (): void {
     $this->user->grantAchievement($this->achievement);
 
-    expect($this->user)->achievements->toHaveCount(1);
+    expect($this->user)->getUserAchievements()->toHaveCount(1);
 
     $this->assertDatabaseHas(table: 'achievement_user', data: [
         'user_id' => $this->user->id,
@@ -24,7 +24,7 @@
 test(description: 'a User can earn an Achievement with progress', closure: function (): void {
     $this->user->grantAchievement($this->achievement, 50);
 
-    expect($this->user)->achievements->toHaveCount(1);
+    expect($this->user)->getUserAchievements()->toHaveCount(1);
 
     $this->assertDatabaseHas(table: 'achievement_user', data: [
         'user_id' => $this->user->id,
@@ -65,7 +65,7 @@
     $this->user->grantAchievement(Achievement::factory()->secret()->create());
 
     expect($this->user)->secretAchievements->toHaveCount(1)
-        ->and($this->user)->achievements->toHaveCount(0);
+        ->and($this->user)->getUserAchievements()->toHaveCount(0);
 });
 
 test(description: 'a User can see all Achievements', closure: function (): void {
@@ -80,7 +80,7 @@
     $this->user->grantAchievement($this->achievement, 50);
     $this->user->grantAchievement(Achievement::factory()->create(), 50);
 
-    expect($this->user)->achievements->first()->pivot->withProgress(50)->toHaveCount(2);
+    expect($this->user->achievementsWithSpecificProgress(50)->get())->toHaveCount(count: 2);
 });
 
 it(description: 'can increment the progress of an Achievement', closure: function (): void {
@@ -90,7 +90,7 @@
 
     $this->user->incrementAchievementProgress($this->achievement, 1);
 
-    expect($this->user)->achievements->first()->pivot->progress->toBe(expected: 51);
+    expect($this->user)->getUserAchievements()->first()->pivot->progress->toBe(expected: 51);
 
     Event::assertDispatched(
         event: AchievementProgressionIncreased::class,
@@ -110,20 +110,20 @@
     $this->user->grantAchievement($this->achievement);
     $this->user->grantAchievement($this->achievement);
 
-    expect($this->user)->achievements->toHaveCount(count: 1);
+    expect($this->user)->getUserAchievements()->toHaveCount(count: 1);
 })->throws(exception: Exception::class, exceptionMessage: 'User already has this Achievement');
 
 test(description: 'a User can have an Achievement revoked', closure: function (): void {
     // First grant the achievement
     $this->user->grantAchievement($this->achievement);
 
-    expect($this->user)->achievements->toHaveCount(count: 1);
+    expect($this->user)->getUserAchievements()->toHaveCount(count: 1);
 
     // Now revoke it
     $this->user->revokeAchievement($this->achievement);
 
     expect($this->user->fresh())
-        ->achievements->toHaveCount(count: 0)
+        ->getUserAchievements()->toHaveCount(count: 0)
         ->and($this->user->achievements()->where('achievement_id', $this->achievement->id)->exists())->toBeFalse();
 
     $this->assertDatabaseMissing(table: 'achievement_user', data: [