Level-Up高级定制指南替换自定义模型与配置项实现深度业务集成【免费下载链接】level-upLevel-Up is a Laravel package introducing gamification into your applications. Users earn experience points (XP) and levels through interactions, while also unlocking achievements. It promotes engagement, competition, and fun through its dynamic leaderboard feature. Customisable to fit your specific needs项目地址: https://gitcode.com/gh_mirrors/le/level-upLevel-Up 是一个为 Laravel 应用注入游戏化能力的开源包用户可以通过互动获得经验值XP、升级、解锁成就并登上动态排行榜。本指南将带你掌握Level-Up 高级定制的核心技巧通过替换自定义模型与调整配置项把游戏化能力无缝融入你的业务系统实现真正的深度业务集成。即使你是新手也能一步步完成从默认配置到完全自定义的蜕变。为什么需要对 Level-Up 做高级定制开箱即用的 Level-Up 已经覆盖了经验值、等级、成就、连击Streak、排行榜等常见玩法但真实业务往往有特殊诉求 等级表需要附带额外的业务字段如 VIP 标识、专属权益 用户主键不是默认的user_id而是member_id 需要把经验值、成就等数据存储到已有的业务表中 排行榜需要按自定义用户模型实时生成这些场景都可以在不改动包源码的前提下通过配置文件 自定义模型优雅解决。认识核心配置文件一切定制的起点Level-Up 的所有可调参数都集中在发布后的配置文件中。安装并发布配置composer require cjmellor/level-up php artisan vendor:publish --taglevel-up-migrations php artisan migrate php artisan vendor:publish --taglevel-up-config发布后你会得到config/level-up.php它就像一个总控台我们逐一拆解它的秘密。配置项快速总览配置键作用默认值models.*指定各功能使用的模型类包内置模型user.foreign_key用户表外键名user_iduser.model绑定的用户模型App\Models\Useruser.users_table用户表名userstable经验值数据表名experiencesstarting_level新用户起始等级1multiplier.*经验倍数机制开关与路径开启level_cap.*等级上限控制100 级audit.enabled经验变更审计关闭archive_streak_history.enabled连击历史归档开启freeze_duration连击冻结默认天数1替换自定义模型让每个功能都长出你的业务触角配置文件中models块是Level-Up 自定义模型的第一入口它支持替换的模型包括models [ achievement LevelUp\Experience\Models\Achievement::class, activity LevelUp\Experience\Models\Activity::class, experience LevelUp\Experience\Models\Experience::class, experience_audit LevelUp\Experience\Models\ExperienceAudit::class, level LevelUp\Experience\Models\Level::class, streak LevelUp\Experience\Models\Streak::class, streak_history LevelUp\Experience\Models\StreakHistory::class, achievement_user LevelUp\Experience\Models\Pivots\AchievementUser::class, ],最快配置方法继承 覆盖最稳妥的替换方式是继承默认模型再补充你自己的字段与方法。例如为等级模型添加一个会员权益描述?php namespace App\Models; use LevelUp\Experience\Models\Level as BaseLevel; class Level extends BaseLevel { protected $fillable [ level, next_level_experience, benefit, // 新增业务字段 ]; public function benefitText(): string { return $this-benefit ?? 暂无专属权益; } }然后在配置中把models.level指向你的新类models [ // ...其他模型保持不变 level App\Models\Level::class, ],整个包的等级创建、升级判断、排行榜都会自动改用你的模型你甚至可以用Level::add()继续批量创建等级结构Level::add( [level 1, next_level_experience null], [level 2, next_level_experience 100], [level 3, next_level_experience 250], ); 提示Level 1的next_level_experience必须为null它是所有用户的默认起点。为什么替换能立刻生效因为包内部处处通过config(level-up.models.level)这类动态调用获取模型类而不是写死类名。你可以亲眼验证这一点——查看 src/Concerns/GiveExperience.php 中addPoints()的实现或 src/Models/Experience.php 里status()关系的写法都依赖配置动态解析。用测试确认替换成功官方测试 tests/Models/LevelTestWithCustomModel.php 演示了标准做法先在beforeEach里把配置指向自定义类再断言创建出的实例类型与新增方法config()-set(level-up.models.level, \App\Models\Level::class); $level config(level-up.models.level)::add([ level 6, next_level_experience 750, ]); expect($level[0])-toBeInstanceOf($levelClass); expect($level[0]-extra_function())-toBe(extra_function);照葫芦画瓢你就能为成就、连击、经验审计等所有模块建立可测试的自定义模型体系。用户模型与外键定制适配你的会员体系user块决定了 Level-Up 如何与你现有的用户体系对接user [ foreign_key user_id, model App\Models\User::class, users_table users, ],三步接入自定义用户模型绑定模型把user.model指向你的用户类如App\Models\Member指定外键如果你的表用member_id同步修改foreign_key声明表名把users_table改为真实的表名如membersuser [ foreign_key member_id, model App\Models\Member::class, users_table members, ],这套配置同时影响经验关系、等级归属和排行榜查询——查看 src/Services/LeaderboardService.php 你就会发现排行榜生成时正是用user.model和user.users_table拼接 SQL 关联条件的。在用户模型上挂载对应 Trait 后即可直接调用积分、成就、连击等方法use LevelUp\Experience\Concerns\GiveExperience; use LevelUp\Experience\Concerns\HasAchievements; use LevelUp\Experience\Concerns\HasStreaks; class Member extends Authenticatable { use GiveExperience, HasAchievements, HasStreaks; }业务表与经验值存储定制更换经验值表名想让经验数据落在已有的业务表里修改顶层table即可table member_xp,src/Models/Experience.php 在构造时会读取该配置作为表名所以无需修改迁移文件你的经验记录就会写入新表。调整起始等级新用户默认从 1 级开始如需从 0 级或 5 级起步starting_level 5,⚠️ 注意addPoints()的初始等级判断会参考该值请确保与你的等级表结构一致。玩法策略定制倍数、上限与风控经验倍数配置Multipliermultiplier块控制促销翻倍等玩法multiplier [ enabled true, path app_path(Multipliers), namespace App\\Multipliers\\, ],用 Artisan 命令快速生成一个倍数类php artisan level-up:multiplier IsMonthDecember生成的类实现Multiplier契约qualifies()判断是否命中、setMultiplier()返回倍数。整个解析流程由 src/Services/MultiplierService.php 驱动你可以通过path配置把倍数类放到任意目录。等级上限配置Level Cap限制玩家成长空间防止数值膨胀level_cap [ enabled true, level 100, points_continue true, ],level最高可达到的等级points_continue达到上限后是否继续累计经验值审计与连击历史audit [ enabled false, // 开启后记录每次加分/扣分明细 ], archive_streak_history [ enabled true, // 连击中断时归档历史 ], freeze_duration 1, // 连击冻结默认天数开启审计后你可以通过$user-experienceHistory回溯每次经验变更的原因与类型非常适合做运营风控与对账。用 .env 环境变量快速切换大部分配置都支持环境变量覆盖无需改动代码即可按环境切换策略MULTIPLIER_ENABLEDtrue LEVEL_CAP_ENABLEDtrue LEVEL_CAP50 LEVEL_CAP_POINTS_CONTINUEfalse AUDIT_POINTStrue ARCHIVE_STREAK_HISTORY_ENABLEDtrue STREAK_FREEZE_DURATION3例如测试环境关闭倍数、正式环境开启审计、大促期间临时调高等级上限都可以通过.env一行搞定。最佳实践清单 ✅继承而非重写优先继承包内置模型避免丢失默认逻辑与关系定义统一配置入口把模型替换集中在config/level-up.php不要散落在业务代码里善用测试验证参考 tests/Models/LevelTestWithCustomModel.php 的写法为每个自定义模型补测试环境隔离用.env区分开发/测试/生产的不同玩法参数升级友好配置文件与源码分离包升级时只需核对config/level-up.php的差异结语掌握Level-Up 配置项与替换自定义模型两大武器后游戏化系统就不再是套模板而是真正长在你业务里的有机部分。从一条member_id外键到一套带权益字段的等级模型每一步定制都在拉近通用包与专属产品之间的距离。现在就打开config/level-up.php动手打造属于你的游戏化引擎吧【免费下载链接】level-upLevel-Up is a Laravel package introducing gamification into your applications. Users earn experience points (XP) and levels through interactions, while also unlocking achievements. It promotes engagement, competition, and fun through its dynamic leaderboard feature. Customisable to fit your specific needs项目地址: https://gitcode.com/gh_mirrors/le/level-up创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考