Laravel Gamify: Gamification System with Points & Badges support
Use ansezz/laravel-gamify to quickly add point & badges in your Laravel app.
1 - You can install the package via composer:
$ composer require ansezz/laravel-gamify2 - 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' => [
//...
Ansezz\Gamify\GamifyServiceProvider::class
]In Laravel 5.5 and above the service provider automatically.
3 - Now publish the migration for gamify tables:
php artisan vendor:publish --provider="Ansezz\Gamify\GamifyServiceProvider" --tag="migrations"
Note: It will generate migration for points, badges, gamify_groups, pointables, badgables tables, you will need to run composer require doctrine/dbal in order to support dropping and adding columns.
php artisan migrateYou can publish the config file:
php artisan vendor:publish --provider="Ansezz\Gamify\GamifyServiceProvider" --tag="config"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.
1. After package installation now add the Gamify trait on App\User model or any model who acts as user in your app.
use Ansezz\Gamify\Gamify;
use Illuminate\Notifications\Notifiable;
use Illuminate\Foundation\Auth\User as Authenticatable;
class User extends Authenticatable
{
use Notifiable, Gamify;2. Next step is to create a point.
- The point class is option because we save the point in database.
- You can create a point directly in your database without class.
- Create the point class if you need to add a check before achieve the point or if you wanna define a dynamic point value.
php artisan gamify:point PostCreatedThey will ask you if you wanna create the database badge record.
class attribute in badges table will take the class with namespace in this case:
App\Gamify\Points\PostCreated
It will create a Point class named PostCreated under app/Gamify/Points/ folder.
<?php
namespace App\Gamify\Points;
use Ansezz\Gamify\BasePoint;
class PostCreated extends BasePoint
{
public function __invoke($point, $subject)
{
return true;
}
}in __invoke you can add any condition to check if user achieve the point else return true , esle we use config('gamify.point_is_archived') by default you can change it in you config file gamify.php.
$user = auth()->user();
$point = Point::find(1);
// or you can use facade function
Gamify::achievePoint($point);
// or via HasBadge trait method
$user->achievePoint($point);In some cases you would want to undo a given point.
$user = auth()->user();
$point = Point::find(1);
// or you can use facade function
Gamify::undoPoint($point);
// or via HasPoint trait method
$user->undoPoint($point);You can also pass second argument as $event (Boolean) in function achievePoint & undoPoint ($point, $event), default is true, to disable sending PointsChanged event.
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.
To get the total user points achieved you have achieved_points attribute available..
// get integer point
$user->achieved_points; // 20the package stores all the points event log so you can get the history of points via the following relation:
foreach($user->points as $point) {
// name of the point type
$point->name;
// how many points
$point->point;
}the package stores all the badges in database so you can get the history of badges via the following relation:
foreach($user->badges as $badge) {
// name of the point type
$point->name;
// how many points
$point->image;
}Whenever user point changes it fires \Ansezz\Gamify\Events\PointsChanged event which has the following payload:
class PointsChanged implements ShouldBroadcast {
...
public function __construct(Model $subject, int $point, bool $increment)
{
$this->subject = $subject;
$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 points.
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 file.
To generate a badge you can run following provided command:
They will ask you if you wanna create the database badge record.
class attribute in badges table will take the class with namespace in this case:
App\Gamify\Badges\PostCreated
php artisan gamify:badge PostCreatedIt will create a BadgeType class named PostCreated under app/Gamify/Badges/ folder.
For each level you need to define a function by level name to check if the subject is achieve the badge, esle we use config('gamify.badge_is_archived') by default you can change it in you config file gamify.php.
<?php
namespace App\Gamify\Badges;
use Ansezz\Gamify\BaseBadge;
class PostCreated extends BaseBadge
{
/**
* @param $badge
* @param $subject
*
* @return bool
*/
public function beginner($badge, $subject)
{
return $subject->achieved_points >= 100;
}
/**
* @param $badge
* @param $subject
*
* @return bool
*/
public function intermediate($badge, $subject)
{
return $subject->achieved_points >= 200;
}
/**
* @param $badge
* @param $subject
*
* @return bool
*/
public function advanced($badge, $subject)
{
return $subject->achieved_points >= 300;
}
}// to reset point back to zero
$user->resetPoint();$badage = Badge::find(1);
$user = auth()->user();
$badge->isAchieved($user);// sync all badges for current subject using Facade
Gamify::syncBadges($user);
// or via HasBadge trait method
$user->syncBadges();$badge = Badge::find(1);
// sync all badges for current subject using Facade
Gamify::syncBadge($badge, $user)
// or via HasBadge trait method
$user->syncBadge($badge);Whenever user point changes it fires \Ansezz\Gamify\Events\BadgeAchieved event which has the following payload:
class BadgeAchieved implements ShouldBroadcast {
...
public function __construct($subject, $badge)
{
$this->subject = $subject;
$this->badge = $badge;
}
}<?php
return [
// Reputation model
'point_model' => '\Ansezz\Gamify\Point',
// 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' => '\Ansezz\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,
// Badge achieved vy default if check function not exit
'badge_is_archived' => false,
// point achieved vy default if check function not exit
'point_is_archived' => true,
];Please see CHANGELOG for more information on what has changed recently.
The package contains some integration/smoke tests, set up with Orchestra. The tests can be run via phpunit.
$ composer testPlease see CONTRIBUTING for details.
If you discover any security related issues, please email ansezzouaine@gmail.com instead of using the issue tracker.
- Anass Ez-zouaine (Author)
The MIT License (MIT). Please see License File for more information.