Skip to content
Tilttek
Français

tilttek/dice-bundle

✅ published

Dice for a Symfony application: configured, rolled, kept to be replayed, checked in forms and shown in templates.

tilttek/dice-bundle integrates tilttek/dice with Symfony. It builds the library from the configuration — its limits, the custom dice of the application, the notations of more languages —, rolls from a secure source, keeps replayable rolls in a Doctrine journal and replays them, keeps the macros of a site, a table and a member, makes verifiable rolls, and gives a form field with its constraint, Twig filters and functions, and an accessible detail of a roll. An extension point dresses a member's dice with the appearance of a set they own. It does not animate dice, draw the roller's page, decide who may roll, nor own any dice set: the application does.

It is for Symfony applications that roll dice for their members: a dice roller page, a play-by-post forum, a character sheet, a game table. An application without Symfony takes tilttek/dice alone.

It is an AbstractBundle on Symfony 8.2 with Doctrine ORM 3. The form type, the constraint and the Twig extension are registered only when Symfony Form, Validator and Twig are installed. A member is an opaque ResourceReference of phil/resource: the bundle reads no name, address or account.

The design is small: the bundle class reads the configuration, DiceServices registers the services, DiceRolls is the service the application calls, DiceMacros keeps and resolves macros, RecordedRoll is a row of the journal, and DiceAppearance is the port that dresses a member's dice.

Status

PartState
Configuration: limits, custom dice, notations, appearance, translation domain, store, entity managerImplemented and tested
DiceRolls: parse, read DiceParser, write, translate, roll, replayable rolls, replay, verifiable rolls and verification, a member's rolls and their erasureImplemented and tested
Journal of replayable rolls in Doctrine, or in memoryImplemented and tested
DiceMacros: macros of a site, a table and a member, named by token, in Doctrine or in memoryImplemented and tested
DiceAppearance extension pointImplemented and tested
DiceExpression constraint and DiceExpressionType fieldImplemented and tested
Twig: dice_notation, dice_dialect, dice_roll, dice_roll_detail, dice_textImplemented and tested
Dialects added by tagImplemented and tested

Documentation

DocumentWhat it covers
InstallationRequirements, registering the bundle, the journal's table.
ConfigurationEvery option of tilttek_dice, with its default.
RollingDiceRolls: plain, replayable and verifiable rolls, the journal, erasing a member's rolls.
MacrosDiceMacros: the shelves of a site, a table and a member, defining, resolving and erasing macros.
Forms and validationDiceExpressionType and the DiceExpression constraint.
TemplatesThe Twig filters and functions, the detail of a roll, its classes and its words.
Extension pointsDiceAppearance, dialects by tag, the journal's port.
ExceptionsWhat the bundle raises.
TestingThe bundle's tests, and how to test an application that rolls dice.
ReferenceEvery type of the bundle, with its role.

Quick start

composer require tilttek/dice-bundle
# config/packages/tilttek_dice.yaml
tilttek_dice:
    custom_dice:
        coin:
            faces:
                - { id: heads, label: 'Heads', value: 1, shape: circle }
                - { id: tails, label: 'Tails', value: 0, shape: square }
use Tilttek\DiceBundle\Application\DiceRolls;

public function __invoke(DiceRolls $dice): Response
{
    $recorded = $dice->rollReplayable('4d6kh3 + 1d{coin}');

    return $this->render('dice/roll.html.twig', ['replay' => $dice->replay($recorded->id())]);
}
{{ dice_roll_detail(replay.result) }}

Requirements

PHP 8.5 or later, Symfony 8.2, Doctrine ORM 3.7, tilttek/dice and phil/resource 0.1. Symfony Form, Validator, Twig and Translation are optional.

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.