README

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

Part	State
Configuration: limits, custom dice, notations, appearance, translation domain, store, entity manager	Implemented and tested
`DiceRolls`: parse, read DiceParser, write, translate, roll, replayable rolls, replay, verifiable rolls and verification, a member's rolls and their erasure	Implemented and tested
Journal of replayable rolls in Doctrine, or in memory	Implemented and tested
`DiceMacros`: macros of a site, a table and a member, named by token, in Doctrine or in memory	Implemented and tested
`DiceAppearance` extension point	Implemented and tested
`DiceExpression` constraint and `DiceExpressionType` field	Implemented and tested
Twig: `dice_notation`, `dice_dialect`, `dice_roll`, `dice_roll_detail`, `dice_text`	Implemented and tested
Dialects added by tag	Implemented and tested

Documentation

Document	What it covers
Installation	Requirements, registering the bundle, the journal's table.
Configuration	Every option of `tilttek_dice`, with its default.
Rolling	`DiceRolls`: plain, replayable and verifiable rolls, the journal, erasing a member's rolls.
Macros	`DiceMacros`: the shelves of a site, a table and a member, defining, resolving and erasing macros.
Forms and validation	`DiceExpressionType` and the `DiceExpression` constraint.
Templates	The Twig filters and functions, the detail of a roll, its classes and its words.
Extension points	`DiceAppearance`, dialects by tag, the journal's port.
Exceptions	What the bundle raises.
Testing	The bundle's tests, and how to test an application that rolls dice.
Reference	Every 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.

tilttek / dice-bundle

Package info

Security

Statistics