Download the PHP package gstt/laravel-achievements without Composer
On this page you can find all versions of the php package gstt/laravel-achievements. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download gstt/laravel-achievements
More information about gstt/laravel-achievements
Files in gstt/laravel-achievements
Package laravel-achievements
Short Description Achievements for Laravel 5.3+
License MIT
Informations about the package laravel-achievements
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.
Add the Service Provider to your config/app
file in the providers
section.
Backup your database and run the migrations in order to setup the required tables on the database.
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.
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:
Unlocking Achievements
Achievements can be unlocked by using the Achiever
trait.
This trait contains the unlock
method, that can be used to unlock an Achievement. The unlock
method expects an
Achievement
instance:
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
:
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:
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:
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.
You can also search for a specific achievement using the achievementStatus()
method.
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.
License
Laravel Achievements is open-sourced software licensed under the MIT license.