particle-academy/laravel-fun-lab
| Install | |
|---|---|
composer require particle-academy/laravel-fun-lab |
|
| Latest Version: | v0.7.0 |
| PHP: | ^8.4 |
| Laravel: | 13 |
| Older releases: | 11 · 12 |
| License: | MIT |
| Last Updated: | Nov 5, 2026 |
| Links: | GitHub · Packagist |
Laravel Fun Lab
Analytics disguised as gamification — turn user activity into meaningful engagement insights.
Laravel Fun Lab (LFL) is an analytics-driven gamification layer for Laravel applications. Track user engagement through XP, achievements, and prizes while capturing structured activity data that apps normally never track.
For agents. This package is listed on the Fancy MCP catalog server at
https://ui.particle.academy/mcp(streamable HTTP, no API key; MCP idfancy-ui), with install commands and docs, alongside the rest of the kit. How an agent installs and uses this package is in AGENTS.md.
Features
- 🎯 Event-Driven Architecture - Every action, reward, or update is an observable event
- 🎮 GamedMetrics XP System - Create independent XP buckets with automatic level progression
- 📊 MetricLevelGroups - Combine multiple XP metrics with weights for composite leveling
- 🏆 Achievements - Define and grant achievements with auto-unlock on level-up
- 🎁 Prizes - Reward users with virtual or physical prizes
- 📈 Built-in Analytics - Query aggregate engagement data for behavioral insights
- 🔌 Extensible - Macros, hooks, and custom implementations
- ⚡ Drop-In Simple - Install → Track → Award workflow
Installation
composer require particle-academy/laravel-fun-lab
php artisan lfl:install
Quick Start
1. Add the Awardable Trait
Add the Awardable trait to any model you want to gamify:
use LaravelFunLab\Traits\Awardable;
class User extends Authenticatable
{
use Awardable;
}
// Works with any model!
class Team extends Model
{
use Awardable;
}
The Awardable trait gives your model a Profile that tracks XP, achievements, and prizes.
2. Create GamedMetrics (XP Categories)
GamedMetrics are independent XP buckets. Each metric tracks its own XP and levels:
use LaravelFunLab\Facades\LFL;
// Create XP categories
LFL::setup(a: 'gamed-metric', with: ['slug' => 'combat-xp', 'name' => 'Combat XP']);
LFL::setup(a: 'gamed-metric', with: ['slug' => 'crafting-xp', 'name' => 'Crafting XP']);
LFL::setup(a: 'gamed-metric', with: ['slug' => 'social-xp', 'name' => 'Social XP']);
3. Define Levels for Metrics
Levels are XP thresholds that can auto-unlock achievements:
// Define levels for combat-xp
LFL::setup(a: 'metric-level', with: ['metric' => 'combat-xp', 'level' => 1, 'xp' => 0, 'name' => 'Novice']);
LFL::setup(a: 'metric-level', with: ['metric' => 'combat-xp', 'level' => 2, 'xp' => 100, 'name' => 'Apprentice']);
LFL::setup(a: 'metric-level', with: ['metric' => 'combat-xp', 'level' => 3, 'xp' => 500, 'name' => 'Warrior']);
LFL::setup(a: 'metric-level', with: ['metric' => 'combat-xp', 'level' => 4, 'xp' => 1000, 'name' => 'Champion']);
4. Award XP
Award XP using the fluent award() method:
// Award XP to a specific GamedMetric
LFL::award('combat-xp')
->to($user)
->amount(50)
->because('defeated boss')
->save();
// Check the profile
$profile = $user->getProfile();
echo $profile->total_xp; // Total XP across all metrics
5. Create and Grant Achievements
// Create an achievement
LFL::setup(a: 'achievement', with: ['slug' => 'first-login', 'name' => 'First Login', 'description' => 'Welcome!', 'icon' => 'star']);
// Grant the achievement
LFL::grant('first-login')
->to($user)
->because('completed onboarding')
->save();
// Check if user has an achievement
if ($user->hasAchievement('first-login')) {
// ...
}
6. Create and Grant Prizes
// Create a prize
LFL::setup(
a: 'prize',
with: [
'slug' => 'premium-access',
'name' => '1 Month Premium Access',
'type' => 'virtual',
'inventory' => 100, // Limited quantity
]
);
// Grant the prize
LFL::grant('premium-access')
->to($user)
->because('won monthly contest')
->save();
7. Check Level Progress
// Check if user has reached a specific level in a metric
if (LFL::hasLevel($user, 3, metric: 'combat-xp')) {
echo "You're a Warrior!";
}
// Check level in a metric group
if (LFL::hasLevel($user, 10, group: 'overall-power')) {
echo "You've reached Overall Power Level 10!";
}
8. Create Metric Level Groups
Combine multiple metrics with weights for composite leveling:
// Create a group
LFL::setup(a: 'metric-level-group', with: ['slug' => 'overall-power', 'name' => 'Overall Power']);
// Add metrics to the group with weights
LFL::setup(a: 'metric-level-group-metric', with: ['group' => 'overall-power', 'metric' => 'combat-xp', 'weight' => 1.0]);
LFL::setup(a: 'metric-level-group-metric', with: ['group' => 'overall-power', 'metric' => 'crafting-xp', 'weight' => 0.5]);
// Define levels for the group
LFL::setup(a: 'metric-level-group-level', with: ['group' => 'overall-power', 'level' => 1, 'xp' => 0, 'name' => 'Beginner']);
LFL::setup(a: 'metric-level-group-level', with: ['group' => 'overall-power', 'level' => 10, 'xp' => 5000, 'name' => 'Expert']);
9. Leaderboards
// Get top users by XP
$leaders = LFL::leaderboard()
->for(User::class)
->by('xp')
->take(10);
API Summary
| Method | Purpose |
|---|---|
LFL::setup() |
Create GamedMetrics, MetricLevels, MetricLevelGroups, Achievements, Prizes |
LFL::award($metric) |
Award XP to a GamedMetric (fluent builder) |
LFL::grant($slug) |
Grant an Achievement or Prize (fluent builder) |
LFL::hasLevel($user, $level, metric: or group:) |
Check if user has reached a level |
LFL::profile($user) |
Get the user's gamification profile |
LFL::leaderboard() |
Build leaderboard queries |
LFL::analytics() |
Build analytics queries |
Documentation
- Usage Guide - Examples and patterns
- API Reference - PHP facade + REST API documentation
- React / SPA Integration - Auth contract, CORS, Echo, typed clients
- Broadcasting - Real-time event channels and payloads
- Configuration - All configuration options
- Extending - Custom implementations and hooks
Requirements
- PHP 8.4+
- Laravel 13.x
License
MIT License - see LICENSE for details.
⭐ Star Fancy Dev Kit
If this package is useful to you, a quick ⭐ on the repo really helps us build a better kit. Thank you!
Related Packages
Version History
| Version | Released | PHP | Laravel | License |
|---|---|---|---|---|
| v0.7.0 | ^8.4 | ^13.0 | MIT | |
| v0.6.0 | ^8.4 | ^13.0 | MIT | |
| v0.5.0 | ^8.2 | ^11.0| | MIT | |
| v0.4.2 | ^8.2 | ^11.0| | MIT | |
| v0.4.1 | ^8.2 | ^11.0| | MIT | |
| v0.4.0 | ^8.2 | ^11.0| | MIT | |
| v0.3.1 | ^8.2 | ^11.0| | MIT | |
| v0.3.0 | ^8.2 | ^11.0| | MIT | |
| v0.2 | ^8.2 | ^11.0| | MIT | |
| v0.1 | ^8.2 | ^11.0| | MIT |