jawabapp / laravel-gamify
Add gamification in laravel app with reputation point and badges support
Requires
- php: >=7.1.33
- laravel/framework: ~5.4.0|~5.5.0|~5.6.0|~5.7.0|~5.8.0|^6.0|^7.0|^8.0
Requires (Dev)
- mockery/mockery: ^0.9.4 || ~1.0
- orchestra/testbench: ~3.8|^4.0
- phpunit/phpunit: ~8.5
This package is auto-updated.
Last update: 2024-10-29 06:13:02 UTC
README
Use jawabapp/laravel-gamify
to quickly add reputation point & badges in your Laravel app.
Installation
1 - You can install the package via composer:
$ composer require jawabapp/laravel-gamify
2 - If you are installing on Laravel 5.4 or lower you will be needed to manually register Service Provider by adding it in config/app.php
providers array.
'providers' => [ //... Jawabapp\Gamify\GamifyServiceProvider::class ]
In Laravel 5.5 and above the service provider automatically.
publish the config file:
php artisan vendor:publish --provider="Jawabapp\Gamify\GamifyServiceProvider" --tag="config"
3 - Now publish the migration for gamify tables:
php artisan vendor:publish --provider="Jawabapp\Gamify\GamifyServiceProvider" --tag="migrations"
Note: It will generate migration for reputations
, badges
and user_badges
tables along with add reputation field migration for users
table to store the points, you will need to run composer require doctrine/dbal
in order to support dropping and adding columns.
php artisan migrate
If your payee (model who will be getting the points) model is App\User
then you don't have to change anything in config/gamify.php
.
Getting Started
1. After package installation now add the Gamify trait on App\User
model or any model who acts as user in your app.
use Jawabapp\Gamify\Gamify; use Illuminate\Notifications\Notifiable; use Illuminate\Foundation\Auth\User as Authenticatable; class User extends Authenticatable { use Notifiable, Gamify;
⭐️ 👑 Reputation Point
2. Next step is to create a point.
php artisan gamify:point PostCreated
It will create a PointType class named PostCreated
under app/Gamify/Points/
folder.
<?php namespace App\Gamify\Points; use Jawabapp\Gamify\PointType; class PostCreated extends PointType { /** * Number of points * * @var int */ public $points = 20; /** * Point constructor * * @param $subject */ public function __construct($subject) { $this->subject = $subject; } /** * User who will be receive points * * @return mixed */ public function payee() { return $this->getSubject()->user; } }
Give point to User
Now in your Controller where a Post is created you can give points like this:
$user = $request->user(); $post = $user->posts()->create($request->only(['title', 'body'])); // you can use helper function givePoint(new PostCreated($post)); // or via HasReputation trait method $user->givePoint(new PostCreated($post));
Undo a given point
In some cases you would want to undo a given point, for example, a user deletes his post.
// via helper function undoPoint(new PostCreated($post)); $post->delete(); // or via HasReputation trait method $user->undoPoint(new PostCreated($post)); $post->delete();
You can also pass second argument as $user in helper function givePoint(new PostCreated($post, $user))
, default is auth()->user().
Pro Tip 👌 You could also hook into the Eloquent model event and give point on created
event. Similarly, deleted
event can be used to undo the point.
Get total reputation
To get the total user reputation you have $user->getPoints($formatted = false)
method available. Optioally you can pass $formatted = true
to get reputation as 1K+, 2K+ etc.
// get integer point $user->getPoints(); // 20 // formatted result $user->getPoints(true); // if point is more than 1000 1K+
Get reputation history
Since package stores all the reputation event log so you can get the history of reputation via the following relation:
foreach($user->reputations as $reputation) { // name of the point type $reputation->name // payee user $reputation->payee // how many points $reputation->point // model on which point was given $reputation->subject }
If you want to get all the points given on a subject
model. You should define a morphMany
relations. For example on post model.
/** * Get all the post's reputation. */ public function reputations() { return $this->morphMany('Jawabapp\Gamify\Reputation', 'subject'); }
Now you can get all the reputation given on a Post
using $post->reputations
.
Configure a Point Type
Point payee
In most of the case your subject model which you pass into point new PostCreated($post)
will be related to the User via some relation.
class PostCreated extends PointType { public $points = 20; protected $payee = 'user'; // dont need this, payee property will return subject realtion // public function payee() // { // return $this->getSubject()->user; // } }
Dynamic point
If a point is calculated based on some logic you should add getPoints()
method to do the calculation and always return an integer.
class PostCreated extends PointType { protected $payee = 'user'; public function getPoints() { return $this->getSubject()->user->getPoint() * 10; } }
Point qualifier
This is an optional method which returns boolean if its true then this point will be given else it will be ignored. It's will be helpful if you want to determine the qualification for point dynamically.
Prevent duplicate reputation
By default, you can give points multiple times for same model subject. But you can prevent it by adding the following property to the class:
class PostCreated extends PointType { // prevent duplicate point public $allowDuplicates = false; protected $payee = 'user'; }
Event on reputation changed
Whenever user point changes it fires \Jawabapp\Gamify\Events\ReputationChanged
event which has the following payload:
class ReputationChanged implements ShouldBroadcast { ... public function __construct(Model $user, int $point, bool $increment) { $this->user = $user; $this->point = $point; $this->increment = $increment; } }
This event also broadcast in configured channel name so you can listen to it from your frontend via socket to live update reputation points.
🏆 🏅 Achievement Badges
Similar to Point type you have badges. They can be given to users based on rank or any other criteria. You should define badge level in config/gamify.php
.
// All the levels for badge 'badge_levels' => [ 'beginner' => 1, 'intermediate' => 2, 'advanced' => 3, ], // Default level 'badge_default_level' => 1
Badge levels are stored as tinyint
so keep the value as an integer value. It will be faster to do the sorting when needed.
Create a Badge
To generate a badge you can run following provided command:
php artisan gamify:badge FirstContribution
It will create a BadgeType class named FirstContribution
under app/Gamify/Badges/
folder.
<?php namespace App\Gamify\Badges; use Jawabapp\Gamify\BadgeType; class FirstContribution extends BadgeType { /** * Description for badge * * @var string */ protected $description = ''; /** * Check is user qualifies for badge * * @param $user * @return bool */ public function qualifier($user) { return $user->getPoints() >= 1000; } }
As you can see this badge has a $description
field and a qualifier($user)
method.
Gamify package will listen for any change in reputation point and it will run the user against all the available badges and assign all the badges user is qualified.
Change badge name
By default, badge name will be a pretty version on the badge class name. In the above case it will be First Contribution
.
You can change it by adding a $name
property in class or you can override getName()
method if you want to name it dynamically.
Change badge icon
Similar to name you can change it by $icon
property or by getIcon()
method. When you define icon on the class you need to specify full path with extension.
config/gamify.php
folder badge_icon_folder
and badge_icon_extension
won't be used.
Change badge level
You have same $level
property or by getLevel()
method to change it.
Its like category of badges, all badges are defined in config/gamify.php
as badge_levels
. If none is specified then badge_default_level
will be used from config.
Warning ⚠️ Don't forget to clear the cache whenever you make any changes add or remove badges by running php artisan cache:forget gamify.badges.all
. ⚠️
Get badges of user
You can get a users badges by calling $user->badges
which will return collection of badges for a user.
Use without Badge
If your app doesn't need Badges you should just use HasReputations
trait instead of Gamify
.
Use without reputation history
If you dont need to maintain the history of all the point user has rewarded and you just want to increment and decrement reputation, you should use following method:
// to add point $user->addPoint($point = 1); // to reduce point $user->reducePoint($point = 1); // to reset point back to zero $user->resetPoint();
You dont need to generate point class for this.
Config Gamify
<?php return [ // Model which will be having points, generally it will be User 'payee_model' => '\App\User', // Reputation model 'reputation_model' => '\Jawabapp\Gamify\Reputation', // Allow duplicate reputation points 'allow_reputation_duplicate' => true, // Broadcast on private channel 'broadcast_on_private_channel' => true, // Channel name prefix, user id will be suffixed 'channel_name' => 'user.reputation.', // Badge model 'badge_model' => '\Jawabapp\Gamify\Badge', // Where all badges icon stored 'badge_icon_folder' => 'images/badges/', // Extention of badge icons 'badge_icon_extension' => '.svg', // All the levels for badge 'badge_levels' => [ 'beginner' => 1, 'intermediate' => 2, 'advanced' => 3, ], // Default level 'badge_default_level' => 1 ];
Changelog
Please see CHANGELOG for more information on what has changed recently.
Testing
The package contains some integration/smoke tests, set up with Orchestra. The tests can be run via phpunit.
$ composer test
Contributing
Please see CONTRIBUTING for details.
Security
If you discover any security related issues, please email saquibweb@gmail.com instead of using the issue tracker.
Credits
- Mohd Saqueib Ansari (Author)
About QCode.in
QCode.in (https://www.qcode.in) is a blog by Saqueib which covers All about Full Stack Web Development.
License
The MIT License (MIT). Please see License File for more information.