Skip to content

Configuration

tilttek/leaderboards-bundle
tilttek_leaderboards:
    store: doctrine              # or memory, for tests
    valkey:
        enabled: true            # or `valkey: true`; false by default
        dsn: 'redis://localhost:6379'   # read by Symfony Cache
        # client: app.valkey     # or the service of a client the application has, instead of the DSN
        prefix: tilttek_leaderboards
    connection: default          # the Doctrine DBAL connection
    timezone: America/Toronto    # the timezone of the boards that name none
    boards:
        games-month:
            measure: count       # count, total, best, days — from the journal —; latest, highest — reported
            verbs: ['game.played', 'game.won']
            context: { ranked: true }
            period: month        # day, week, month, quarter, year, season, ever (the default), window
            ties: shared         # first (the default) or shared
            tie_breaks:          # up to two, in turn, before the ties
                - { measure: count, order: asc }                      # count, total, highest, lowest, reported
                - { measure: lowest, order: asc, context: seconds }   # a context integer instead of the quantity
            snapshot_size: 10    # 1 to 1000, 100 by default
        summer:
            measure: total
            verbs: ['quest.*']
            period: season
            timezone: Europe/Paris
            seasons:
                - { code: summer-2026, start: '2026-06-21', end: '2026-09-22' }
        level:
            measure: latest
        weekly-xp:
            measure: total
            verbs: ['lesson.done']
            period: week         # a league needs a weekly board
            league:
                tiers: [bronze, silver, gold, sapphire, diamond]   # from the lowest
                division_size: 30   # 2 to 100
                promoted: 7         # the first of a division who go up
                relegated: 5        # the last of a full division who go down
                formed_by: volume   # arrival (the default) or volume of the week before
        regular:
            measure: days
            verbs: ['lesson.done']
            period: window
            window: 7            # the days of the window, today included: 1 to 366
            title: { name: regular, threshold: 5 }
        game-records:
            measure: best
            verbs: ['game.scored']
            per_object: true     # a ranking for each object of the activities
        house-cup:
            measure: total
            verbs: ['quest.done']
            period: month
            chance: { dice: 2, faces: 6 }   # the luck added to the score of a team
    projection: leaderboards     # the name of the projection's checkpoint
    schedule:
        enabled: true            # or `schedule: true`; false by default
        frequency: '1 hour'      # how often the snapshots and settlements due are looked for
    secret: '%kernel.secret%'    # the secret the luck of the teams is drawn from
    kit_subdirectory: ~          # where the recipes of the kit are; the Toolkit's subdirectory when null
    celebration:
        enabled: true            # or `celebration: false`; true by default
        effect: confetti         # or fireworks
        celebrate_on: period_close   # or score_change
    translation_domain: tilttek_leaderboards
    privacy:
        member_kind: member      # the kind of a member's reference, for phil/privacy-bundle
OptionDefaultWhat it says
storedoctrineWhere the boards are kept: Doctrine DBAL, or memory for tests
valkey.enabledfalseWhether the contributions and the scores are kept in Valkey; the snapshots, choices and leagues stay in store
valkey.dsnredis://localhost:6379The Valkey server, as Symfony Cache's RedisAdapter::createConnection() reads it, with the redis extension, Relay or Predis
valkey.clientnullThe service of a Valkey client the application already has, used instead of dsn: Redis or RedisCluster of the redis extension, a Relay client, a Predis client, or ValkeyGlide of valkey-glide-php; Symfony Cache is then not needed
valkey.prefixtilttek_leaderboardsThe prefix of the keys, between braces, a hash tag that keeps them on one node of a cluster
connectiondefaultThe DBAL connection of the nine tables
timezoneUTCThe timezone of the periods of the boards that name none
boards.<name>.measure—What the board ranks on; required
boards.<name>.verbs[]The verbs read from the journal, as patterns; at least one for count, total, best and days, none for latest and highest
boards.<name>.context{}The facts an activity's context must hold to count: integers, booleans or strings
boards.<name>.periodeverThe period the board ranks over
boards.<name>.window0The days of a sliding window, today included, for a board ranked over one: 1 to 366
boards.<name>.timezonenullThe board's own timezone
boards.<name>.seasons[]The seasons of a board ranked by season, each with its code, start and end
boards.<name>.tiesfirstEqual scores, after the tie-breaks, to the first who reached them, or shared ranks
boards.<name>.tie_breaks[]Up to two measures that order equal scores: each a measure — count, total, highest, lowest, or reported on a reported board —, an order, desc (the default) or asc, and a context integer read instead of the quantity
boards.<name>.per_objectfalseWhether the board ranks members for each object of the activities
boards.<name>.titlenoneA title — its name, threshold and leader, false by default — held while a score in the period under way reaches the threshold, by the leader alone with leader
boards.<name>.chancenoneThe luck added to the score of each team: dice (1 to 10, 1 by default) of faces (2 to 100, 6)
boards.<name>.snapshot_size100How many members a snapshot keeps
boards.<name>.league.tiers—The tiers of the board's league, from the lowest; required with a league
boards.<name>.league.division_size30How many members a division holds
boards.<name>.league.promoted7How many of the first of a division go up a tier
boards.<name>.league.relegated5How many of the last of a full division go down a tier
boards.<name>.league.formed_byarrivalHow a tier's divisions are filled: in the order of arrival, or by the volume of the week before
projectionleaderboardsThe name of the projection
schedule.enabledfalseWhether Symfony Scheduler takes the snapshots and settles the weeks due (Scheduling)
schedule.frequency1 hourHow often, as Symfony Scheduler reads a frequency
secret%kernel.secret%The secret the luck of the teams is drawn from
kit_subdirectorynullWhere the recipes of the kit are, under the components directory; the subdirectory of the ux_toolkit configuration when null (Templates)
celebration.enabledtrueWhether tilttek_leaderboards_celebration() tells a member they reached the top; false makes it return null and the celebration template render nothing (Templates)
celebration.effectconfettiWhat the kit's Celebration draws where motion is not reduced: confetti or fireworks
celebration.celebrate_onperiod_closeWhen a first place is told and celebrated: period_close, for who finished first of the snapshot once the period closed; score_change, for who takes the lead of the period under way as their score changes (Events). A promotion into the highest tier is told when its week is settled either way. It applies to the TopReached events even when celebration.enabled is false
translation_domaintilttek_leaderboardsThe domain of the template's texts and of the boards' names, boards.<name>
privacy.member_kindmemberThe kind of the member reference a data subject stands for

The boards' names are kept as written — games-month stays games-month —; the context's keys follow Symfony's normalisation, first-time becoming first_time. A board that does not hold together — a journal measure without verbs, a season out of a seasons board, a timezone that is none, a league on a board that is not weekly or that moves more members than a division holds, a window on a board that is not ranked over one, a reported tie-break on a board read from the journal — fails when the container is compiled.

The services keep no state between requests: they are safe in a worker. The stores in memory, for tests, empty themselves when the kernel resets.