Level Up Laravel Package

Product Decisions This Supports

• Retention and engagement loops as a configurable surface, not a build project. v3 turns the package from "points and badges" into a full progression system: points → levels → tiers → achievements → challenges → streaks → leaderboards → leagues. Each of those is a lever a PM can sequence into a roadmap (Week 1: achievements; Week 4: weekly XP board; Quarter 2: divisions with promotion/relegation) without re-architecting between steps.
• Competitive and social features you can scope in a single sprint. Named Boards let you declare a metric/period/tier combination in config and expose it via Leaderboard::board() — a "Top 10 this week", "Friends leaderboard", or "Guild ranking" becomes a product surface rather than an engineering epic. restrictTo() covers friends lists, cohorts, guilds, and tournament brackets with ranks computed inside the restricted population, which is the difference between a global board nobody can win and a local board everyone can.
• Seasonal and time-boxed campaigns. period(Period::Day|Week|Month) and since(start:, until:) make weekly resets, monthly contests, and launch-window events first-class. week_starts_on and timezone are config knobs, so a PM can specify "resets Monday 00:00 local" without a spec negotiation.
• Re-engagement notification triggers, already evented. The snapshot command persists tracked boards, diffs consecutive runs, and fires LeaderboardRankChanged, UserEnteredTrackedDepth, and UserLeftTrackedDepth. That is the raw material for "you dropped to 4th", "you're 2 spots from promotion", and "you entered the top 100" messaging — the highest-leverage retention copy, delivered by the package rather than invented per feature.
• League/division ladders (the Duolingo model). Lazy cohort enrollment, currentDivision(), cohortStandings(), and a rollover command that promotes/relegates and fires UserDivisionChanged. This is a proven retention structure that's expensive to get right (cohort sizing, tie handling, rollover idempotency) and it ships as a command you schedule.
• Achievement design that maps to real behaviour. The optional absolute count on achievements means "50 games played" or "12 articles read" can be shown as a genuine progress bar rather than a percentage abstraction — a meaningful UX upgrade for onboarding checklists and goal-gradient screens.
• Ranking beyond XP. Built-in level, streak, achievements, and challenges metrics (plus custom RankingMetric implementations) let you rank on the behaviour you actually want to reward. If the product goal is consistency rather than volume, you can board on streaks without touching the points economy.
• Build vs buy, settled on cost. The v3 feature set — window-function ranking with competition semantics (1,1,3), tiebreak determinism, snapshot retention, cohort rollover, atomic point mutations — is roughly a quarter of engineering plus ongoing maintenance. For a team whose differentiator is not "we wrote a ranking query," adopting is the correct call; reserve build for cases where ranking is the product.
• Roadmap safety improved by v3's transactional fixes. Points/level/tier/multiplier events now implement ShouldDispatchAfterCommit and mutations are wrapped in DB::transaction(). That removes a class of "user got the reward email for points that rolled back" incidents, which is the kind of thing that quietly blocks gamification launches in finance- and entitlement-sensitive products.
• Experimentation and analytics. Auditing now defaults to true and time-windowed XP boards read from the experience_audits ledger — you get a queryable progression history for cohort analysis ("do users who hit level 5 in week 1 retain?") without a separate instrumentation project.

When to Consider This Package

Consider it when:

• The product is a Laravel application with a conventional User model and a relational database, and gamification is a feature, not the product itself.
• You want progression mechanics that stack — achievements feeding points feeding levels feeding tiers feeding boards — rather than a single badge wall.
• Retention is a named OKR and you need competitive or social loops (leaderboards, leagues, streaks) on a timeline shorter than a rebuild.
• Your database is MySQL 8+, MariaDB 10.2+, PostgreSQL, or SQLite 3.25+. This is now a hard gate: leaderboard ranks use SQL window functions, and MySQL 5.7 is explicitly unsupported. Confirm the production engine before committing — for some teams this release is an infrastructure project disguised as a dependency bump.
• You can schedule two commands (level-up:snapshot-boards, level-up:league-rollover) and own their operational health — missed runs mean stale boards and un-promoted users, which is a visible product failure.
• You accept the audit ledger's storage growth (now on by default) or can explicitly opt out and forgo periodic XP boards (AUDIT_POINTS=false triggers MetricRequiresAuditingException for those metrics — a deliberate either/or).

Look elsewhere when:

• You are not on Laravel, or you maintain a hand-rolled XP/economy layer whose invariants the package would collide with.
• You already run an event-sourced or warehouse-backed progression model and only need a presentation layer.
• You need real-time, high-frequency ranking (millions of concurrent users, sub-second board updates). SQL window functions are correct and auditable but not a substitute for a Redis sorted set at that scale; this package is the wrong tool and the migration won't be cheap later.
• You want only a simple badge wall. The v3 surface area — boards, snapshots, cohorts, divisions, rollover — is real operational and cognitive overhead. Adoption cost should be matched to ambition.
• You are on MySQL 5.7 or MariaDB below 10.2, or you cannot take a schema migration window.
• You are mid-freeze on your User model. The removal of trait method aliasing means colliding challenges() / streaks() / experience() / experienceHistory() methods must be renamed or composed into a wrapper model — a refactor that touches every call site.

Upgrade posture (v2.x → v3.0.0): treat this as a planned migration, not a patch. The Multiplier::scopeTo() removal, the multiplier_scopes polymorphic table being replaced by multiplier_user / multiplier_tier pivots (with an automatic backfill migration), and the removed MultiplierScope model and config keys are all breaking. Leaderboard::generate() now returns LeaderboardEntry objects (->user, ->score, ->rank) instead of User collections, so any existing board UI or API contract needs updating. setPoints() now recalculates level and tier and fires UserLevelledUp / UserTierUpdated — admin tooling that previously wrote points silently will now trigger side effects and notifications. Budget a sprint, rehearse the backfill on a production-shaped dataset, and verify the alter_experience_audits_type_to_string down-migration on PostgreSQL if you support rollbacks.

How to Pitch It (Stakeholders)

To executives: This package gives us a mature engagement stack — points, levels, achievements, streaks, leaderboards, and promotion/relegation leagues — as a dependency instead of a quarter of engineering. The v3 release is the one that makes it strategically interesting: competitive boards, re-engagement events, and seasonal resets are the mechanics that move retention, and they're now configuration rather than bespoke code. The commercial case is time-to-market and optionality: we can ship one loop (weekly leaderboard), measure it, and add or remove the next (leagues) without a new build each time. It requires a database version we should confirm (MySQL 8+ or Postgres), and if we're behind on that, the upgrade is worth doing on its own merits.

To engineering: It's a well-scoped domain package with a clear ownership boundary — progression state in our database, ranking computed in SQL with window functions, and lifecycle handled by two scheduled commands. v3 is a breaking major: typed multiplier pivots replace the polymorphic table (with an automatic backfill), scopeTo() becomes scopeToUser() / scopeToTier(), leaderboards return LeaderboardEntry value objects, and trait aliasing helpers are gone. The wins are real though — point mutations are now transactional, package events implement ShouldDispatchAfterCommit so listeners don't fire on rolled-back transactions, achievement relations are invalidated on mutation instead of needing manual refresh(), and setPoints() no longer silently desyncs level and tier. Risk is concentrated in the migration and the leaderboard return-type change; everything else is mechanical.

To the product and design team: We get progress bars backed by real counts ("50 games played", not "72%"), time-windowed boards that reset on a schedule we specify (including timezone and week-start), friends/guild-scoped rankings, and a division ladder with promotion and relegation. We also get the notification hooks for "you moved up / you're about to drop" without asking engineering to instrument anything new. Two constraints to design around: XP-based periodic boards depend on auditing being enabled (a storage decision, not a free toggle), and ranks are computed on a schedule via snapshots — so boards are near-real-time, not live, and copy should reflect that.