Skip to content

tilttek/luck-tokens-bundle

✅ published

Luck, inspiration and fate tokens for a Symfony application's tables, every move kept in the database.

tilttek/luck-tokens-bundle integrates tilttek/luck-tokens with Symfony. It keeps the ledgers of the tables, and their rules when the application edits them, in tables on a Doctrine DBAL connection, added to the schema the ORM generates so that the application's migrations create them. The rules may also come from the configuration or from a service of the application. A balance is read from an index, never by adding up the ledger; two writers at once on a table are told apart by the primary key, and the second one reads the ledger again. An optional Symfony lock runs the operations of a holder, or of a whole table, one after the other. The events reach the application's event dispatcher; who spends the tokens of whom can be decided by the security voters; a member who leaves is erased under a pseudonym, through phil/privacy-bundle or a listener of the application.

It is for a Symfony application whose tables hand out tokens — inspiration, bennies, fate points — and wants each one granted, spent and passed once, with an audit the game master and the players can read.

It requires Symfony's DependencyInjection and Config, Doctrine DBAL, the PSR event dispatcher, tilttek/luck-tokens and phil/resource. The ORM, the Lock and Security components and phil/privacy-bundle are optional: the schema listener, the locks, the access through the voters and the erasure module are registered only when they are installed and, for the locks and the voters, asked for.

The design follows the other bundles of the monorepo: an AbstractBundle with its configuration, services declared by LuckTokensServices, DBAL stores and the library's memory stores for tests, tables added by a schema listener.

Status

PartState
Configuration tilttek_luck_tokens: store, connection, rules, tables, clock, size of a ledger, access, locks, member kindImplemented and tested
DbalTokenLedger and DbalTokenRules, with their two tablesImplemented and tested
The DBAL stores on SQLite, MySQL 8.4 and PostgreSQL 17, four processes at once includedImplemented and tested
The tables in the schema the ORM generates, for the migrationsImplemented and tested
LockedLuckTokens: the operations under a Symfony lock, by holder or by tableImplemented and tested
The events through the application's dispatcherImplemented and tested
SecurityHolderAccess and HolderControlVoter: the access asked of the security votersImplemented and tested
Erasure of a member under a pseudonym for phil/privacy-bundleImplemented and tested

Documentation

DocumentWhat it covers
InstallationRequirements, enabling the bundle, the migration.
ConfigurationEvery key of tilttek_luck_tokens, with its default.
The ledgers in the databaseThe tables, the indexes, writers at once, the rules kept there.
LocksLockedLuckTokens, the scopes, the store of the locks.
Who controls whomEach holder their own, the security voters, a service of the application.
EventsListening to the tokens' events.
Erasing a memberThe pseudonym, the privacy bundle, a listener of the application.
Extension pointsThe services, aliases and tags the application uses.
TestingThe bundle's tests, on SQLite, MySQL and PostgreSQL, its benchmark, and testing an application.
ReferenceEvery class of the bundle, with its role.

Quick start

composer require tilttek/luck-tokens-bundle
# config/packages/tilttek_luck_tokens.yaml
tilttek_luck_tokens:
    tables:
        'table:12':
            game_masters: ['member:7']
            kinds:
                - { key: inspiration, name: Inspiration, cap: 1, transferable: true }
                - { key: fate, name: Fate points, cap: 10, refresh: each-session, refresh_to: 3 }
use Phil\Resource\ResourceReference;
use Tilttek\LuckTokens\LuckTokens;

final readonly class Reroll
{
    public function __construct(private LuckTokens $tokens) {}

    public function __invoke(int $memberId, string $operation): void
    {
        $member = ResourceReference::of('member', (string) $memberId);
        $this->tokens->spend(ResourceReference::of('table', '12'), 'inspiration', $member, 1, $member, $operation, 'Reroll');
    }
}

Then bin/console doctrine:migrations:diff writes the migration of the ledger's table.

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.