Skip to content
Tilttek
Français

tilttek/progression-bundle

✅ published

Levels, seasons and streaks for a Symfony application, from the journal of its members' activity.

tilttek/progression-bundle integrates tilttek/progression with Symfony. The tracks — their curves, rules, seasons and milestones — and the streaks are written in the configuration and checked when the container is compiled. The experience, the milestones reached and the streaks are kept in Doctrine DBAL, in five tables the bundle adds to the schema the ORM generates, so that the application's migrations create them. The projection that turns the members' activity into experience and streaks is tagged for tilttek/activity-bundle, which keeps it up to date at each gesture, catches it up and rebuilds it. A level up or down, a milestone reached and a broken streak become events of the application's dispatcher; Twig functions and two templates show the progress bar of a track and a streak; a command sweeps the broken streaks, another shows a subject's progression; and a member's progression is exported and erased with their account through phil/privacy-bundle.

It is for a Symfony application that rewards what its members do and shows them how far they have come. The library alone suits an application without Symfony.

It requires tilttek/progression, Doctrine DBAL, the PSR event dispatcher and Symfony's configuration and container; the ORM, the console, Twig, the translator and phil/privacy-bundle are optional, and the bundle registers what uses them only when they are installed.

The design follows the library: the stores implement its three contracts, ProgressionServices wires the services, DispatchingObserver turns what the library tells into events, ProgressionExtension is the Twig side.

Status

PartState
Configuration of the tracks, streaks, timezones and stores, checked at compile timeImplemented and tested
DbalExperienceStore, DbalMilestoneStore, DbalStreakStore and the five tables, with the schema listenerImplemented and tested
The projection tagged for tilttek/activity-bundle, the member's timezone from the activity's contextImplemented and tested
Events LevelUp, LevelDown, ReachedMilestone and StreakBrokenImplemented and tested
Twig functions and the templates of the progress bar and the streak, in English and FrenchImplemented and tested
Commands tilttek:progression:sweep and tilttek:progression:showImplemented and tested
Export and erasure of a member for phil/privacy-bundleImplemented and tested

Documentation

DocumentWhat it covers
InstallationRequirements, installing, the tables and the projection.
ConfigurationEvery option, with an example.
DatabaseThe five tables, their keys and the insertion written once.
EventsThe events the bundle dispatches and how to reward a milestone.
TemplatesThe Twig functions, the progress bar and the streak, and their translations.
CommandsSweeping the broken streaks and showing a subject.
PrivacyWhat a member's export holds and what their erasure removes.
Extension pointsReplacing a store, the timezone of a member, the observer.
ExceptionsWhat the bundle raises.
TestingThe bundle's tests, and testing an application that uses it.
ReferenceEvery class and service of the bundle.

Quick start

// config/bundles.php
Tilttek\ActivityBundle\TilttekActivityBundle::class => ['all' => true],
Tilttek\ProgressionBundle\TilttekProgressionBundle::class => ['all' => true],
# config/packages/tilttek_progression.yaml
tilttek_progression:
    timezone: America/Toronto
    tracks:
        player:
            curve: { type: quadratic, base: 50, levels: 60 }
            rules: { games: { verbs: ['game.played'], experience: 20, cap: { amount: 100, period: day } } }
            milestones: { veteran: { level: 10 } }
    streaks:
        daily-play: { verbs: ['game.played'], grace: { allowed: 1, window: 7 } }
{{ include('@TilttekProgression/bar.html.twig', {standing: tilttek_progression_standing('member:44', 'player')}) }}

Requirements

PHP 8.5 or later, Symfony 8.2, Doctrine DBAL 4.5.

Contributing

Contributions are welcome on the PHIL monorepo: read the contribution guide and the code of conduct. Report a vulnerability privately, as the security policy explains, never in a public issue.

License

MIT, © Philippe Gamache, doing business as Le Gnome Archiviste; a Tilttek project. See LICENSE.