User Ranking Bundle Laravel Package

Getting Started

tourze/user-ranking-bundle 1.0.1 is a patch release over 1.0.0 with no changelog detail beyond the compare link, so treat it as a maintenance bump: no new features, no documented deprecations, no breaking changes announced. There is still no prior assessment, so this is the first full baseline.

Minimal steps:

1. composer require tourze/user-ranking-bundle:^1.0 — pin to ^1.0.1 if you want the patch fixes, but read the diff first (see Gotchas).
2. Register the bundle in config/bundles.php (Tourze\UserRankingBundle\UserRankingBundle::class => ['all' => true]). Note the "bundle" naming: this is a Symfony-style bundle, not a Laravel service provider. If you are in Laravel, expect to wire it manually — see Gotchas before committing.
3. Run php bin/console doctrine:schema:update --dump-sql (or generate a migration) and inspect the ranking table it wants to create before applying.
4. Look first at the bundle's Entity/ and Repository/ directories — the ranking model and the query that produces the ordered list are the two things you will actually touch day to day. DependencyInjection/ tells you what is configurable.
5. First use case: a leaderboard ordered by an integer score. Seed a handful of users with scores, then call the ranking repository's ordered lookup and render the top N. Get that working before wiring score updates into your domain events.

Implementation Patterns

Read path — leaderboard queries. Keep the ranking repository as the single source of ordered results. Wrap it in your own LeaderboardService so controllers and API resources never touch the bundle's query builder directly; that is your seam for swapping in caching or a different storage later.

Write path — score updates. Do not let domain code write scores inline in controllers. Emit an event (OrderPaid, LessonCompleted, VoteCast) and have a listener call the bundle's score-update API. This keeps recompute logic in one place and makes it replayable when you need to backfill after a scoring-rule change.

Periodic leaderboards. If the bundle only stores a running total, model windows (daily/weekly/all-time) as separate score rows keyed by period, or recompute into a snapshot table on a schedule. Do not try to derive "this week's rank" from a single cumulative column — it will not be correct and it will not be cheap.

API layer. Expose rank and score together, and include the viewer's own rank even when they are outside the top N ("you are #4,182"). This is the single most requested addition to any leaderboard endpoint and is much easier to add at the service layer than to bolt on later.

Integration tips.

• Fire score recomputation after the transaction commits (DB::afterCommit / Symfony's kernel.terminate or an async message) so a rollback does not leave a stale rank.
• Cache the top-N payload with a short TTL and a version key bumped on write; do not cache per-user ranks, they change constantly.
• Add a console command that recomputes all ranks from source-of-truth data. You will need it the first time a scoring rule changes, and you will want it to be idempotent.

Gotchas and Tips

The release notes are empty. 1.0.1 ships only a GitHub compare link. Before upgrading, run composer update tourze/user-ranking-bundle --dry-run and read git diff 1.0.0..1.0.1. For a 1.0.x patch, expect bugfixes only, but with no documented contract you should treat the diff as the source of truth. If you cannot review the diff, stay on 1.0.0 until you can.

"Bundle" means Symfony, not Laravel. The package name and tourze/* conventions point to a Symfony bundle relying on Doctrine ORM and the Symfony DI container. Under Laravel you will not get package auto-discovery, and the entity mappings will not register themselves. Budget for an adapter layer (or a different package) rather than assuming composer require is enough. Verify this in a scratch app before scoping work.

Doctrine coupling. If your Laravel app uses Eloquent, you will either pull in Doctrine alongside it (two ORMs, two migration systems, one confused team) or bypass the bundle's entities and use only its ranking logic. Decide which before you start; retrofitting is painful.

Ties and rank stability. Leaderboards with duplicate scores need a deterministic tiebreaker (score desc, then updated_at asc, then id). Without one, pagination shows the same user twice or skips users between pages as ranks shift mid-scroll.

Index the score column. An ORDER BY score DESC LIMIT 50 over an unindexed table degrades linearly as your user base grows. Confirm the generated schema includes an index on the ranking column, and add a composite (period, score) index if you model windows.

N+1 on the display layer. Rendering a leaderboard usually needs each user's name and avatar. Eager-load or batch-fetch those in one query; the ranking query returning IDs only is a feature, not a bug.

Config quirks. Bundle configuration lives under a user_ranking-style key in config/packages/. If the bundle ships a Configuration.php, read it — defaults for page size, table prefix, and user class are the usual suspects when things silently attach to the wrong entity.

Extension points. The repository and the score-update service are the realistic override points (decoration or subclassing). Prefer Symfony service decoration over editing vendor code; the 1.0.x line is young and you should assume you will upgrade again soon.

Pin and monitor. ^1.0.1 is fine, but with a pre-1.1 package from a prolific single-maintainer org, watch for a 1.1 that reshapes the entity schema. Subscribe to releases and re-run your recompute command after every minor bump.