An implementation of an Achievement System in Laravel, inspired by Laravel's Notification system.
Table of Contents
- Requirements
- Installation
- Creating Achievements
- Unlocking Achievements
- Adding Progress
- Retrieving Achievements
- Event Listeners
- License
Requirements
- Laravel 5.3 or higher
- PHP 5.6 or higher
Installation
Default installation is via Composer.
composer require gstt/laravel-achievements
Add the Service Provider to your config/app file in the providers section.
'providers' => [
...
Gstt\Achievements\AchievementsServiceProvider::class,
Backup your database and run the migrations in order to setup the required tables on the database.
php artisan migrate
Creating Achievements
Similar to Laravel's implementation of Notifications, each Achievement is represented by a single class (typically stored in the app\Achievements directory.) This directory will be created automatically for you when you run the make:achievement command.
php artisan make:achievement UserMadeAPost
This command will put a fresh Achievement in your app/Achievements directory with only has two properties defined: name and description. You should change the default values for these properties to something that better explains what the Achievement is and how to unlock it. When you're done, it should look like this:
<?php
namespace App\Achievements;
use Gstt\Achievements\Achievement;
class UserMadeAPost extends Achievement
{
/*
* The achievement name
*/
public $name = "Post Created";
/*
* A small description for the achievement
*/
public $description = "Congratulations! You have made your first post!";
}
Unlocking Achievements
Achievements can be unlocked by using the Achiever trait.
<?php
namespace App;
use Gstt\Achievements\Achiever;
use Illuminate\Foundation\Auth\User as Authenticatable;
class User extends Authenticatable
{
use Achiever;
}
This trait contains the unlock method, that can be used to unlock an Achievement. The unlock method expects an Achievement instance:
use App\Achievements\UserMadeAPost
$user->unlock(new UserMadeAPost());
Remember that you're not restricted to the User class. You may add the Achiever trait to any entity that could unlock Achievements.
Adding Progress
Instead of directly unlocking an achievement, you can add a progress to it. For example, you may have an achievement UserMade10Posts and you want to keep track of how the user is progressing on this Achievement.
In order to do that, you must set an additional parameter on your UserMade10Posts class, called $points:
<?php
namespace App\Achievements;
use Gstt\Achievements\Achievement;
class UserMade10Posts extends Achievement
{
/*
* The achievement name
*/
public $name = "10 Posts Created";
/*
* A small description for the achievement
*/
public $description = "Wow! You have already created 10 posts!";
/*
* The amount of "points" this user need to obtain in order to complete this achievement
*/
public $points = 10;
}
You may now control the progress by the methods addProgress and removeProgress on the Achiever trait. Both methods expect an Achievement instance and an amount of points to add or remove:
use App\Achievements\UserMade10Posts;
$user->addProgress(new UserMade10Posts(), 1); // Adds 1 point of progress to the UserMade10Posts achievement
In addition, you can use the methods resetProgress to set the progress back to 0 and setProgress to set it to a specified amount of points:
use App\Achievements\FiveConsecutiveSRanks;
if($rank != 'S'){
$user->resetProgress(new FiveConsecutiveSRanks());
} else {
$user->addProgress(new FiveConsecutiveSRanks(), 1);
}
use App\Achievements\Have1000GoldOnTheBag;
$user->setProgress(new Have100GoldOnTheBag(), $user->amountOfGoldOnTheBag);
Once an Achievement reach the defined amount of points, it will be automatically unlocked.
Retrieving Achievements
The Achiever trait also adds a convenient relationship to the entity implementing it: achievements(). You can use it to retrieve progress for all achievements the entity has interacted with. Since achievements() is a relationship, you can use it as a QueryBuilder to filter data even further.
$achievements = $user->achievements;
$unlocked_today = $user->achievements()->where('unlocked_at', '>=', Carbon::yesterday())->get();
You can also search for a specific achievement using the achievementStatus() method.
$details = $user->achievementStatus(new UserMade10Posts());
There are also three additional helpers on the Achiever trait: lockedAchievements(), inProgressAchievements() and unlockedAchievements().
Event Listeners
Listening to all Achievements
Laravel Achievements provides two events that can be listened to in order to provide "Achievement Unlocked" messages or similar. Both events receive the instance of AchievementProgress that triggered them.
The Gstt\Achievements\Event\Progress event triggers whenever an Achiever makes progress, but doesn't unlock an Achievement. The Gstt\Achievements\Event\Unlocked event triggers whenever an Achiever actually unlocks an achievement.
Details on how to listen to those events are explained on Laravel's Event documentation.
Listening to specific Achievements
The event listeners mentioned above triggers for all Achievements. If you would like to add an event listener for only a specific Achievement, you can do so by implementing the methods whenUnlocked or whenProgress on the Achievement class.
<?php
namespace App\Achievements;
use Gstt\Achievements\Achievement;
class UserMade50Posts extends Achievement
{
/*
* The achievement name
*/
public $name = "50 Posts Created";
/*
* A small description for the achievement
*/
public $description = "Wow! You have already created 50 posts!";
/*
* The amount of "points" this user need to obtain in order to complete this achievement
*/
public $points = 50;
/*
* Triggers whenever an Achiever makes progress on this achievement
*/
public function whenProgress($progress)
{
}
/*
* Triggers whenever an Achiever unlocks this achievement
*/
public function whenUnlocked($progress)
{
}
}
License
Laravel Achievements is open-sourced software licensed under the MIT license.
![[REQUEST] Improve returned data](https://avatars.githubusercontent.com/u/5951126?v=4)
31 Dec 18, 2022
46 Oct 1, 2022
9 Dec 14, 2022
13 May 16, 2022
43 Dec 21, 2022
9 Nov 10, 2022
19 Jul 5, 2021
49 Jun 22, 2022
686 Dec 28, 2022
3.5k Jan 8, 2023
68 Dec 12, 2022
52 Jul 17, 2022
658 Jan 6, 2023
1 Oct 14, 2021
307 Sep 23, 2022
1 Jan 11, 2022
340 Jan 6, 2023
61 Mar 1, 2022
110 Dec 25, 2022