A generic RPG dice roller syntax and library.

php-dice is designed to work out of the box. It means that installation requires minimal steps.

php-dice can be installed using composer. Run following command to download and install php-dice:

composer require "fr-esco/php-dice"

As shown in index.php, once required the library, you can instantiate the parser:

$parser = new dice\Parser;

Then, you can parse your expression:

$result = $parser->parse($expression);

Later in your code, you can evaluate the parsed result, where the returned object can be inspected for debugging purposes:

$result->evaluate();

Finally, you can print out either a raw string representation of the parsed expression or its beautified version by running respectively:

echo $result;
# or
echo $result->render();

The final result is stored in its value property.

$result->value;

You should always wrap the parsing phase in a try / catch block:

try {
    $result = $parser->parse($expression);
} catch (dice\SyntaxError $ex) {
    $stack = ['Syntax error:', $ex->getMessage(),
        'At line', $ex->grammarLine,
        'column', $ex->grammarColumn,
        'offset', $ex->grammarOffset];
    echo implode(' ', $stack);
}

You can also optionally provide a custom scope with additional functions or variables that should be evaluated:

$result = $parser->parse($expression, [
    'foo' => 2,
    'bar' => function () {
        return 3;
    },
], '\custom\namespace\Scope');

You can provide an associative array using as key any at least 2 characters long string that could appear in your expression, and as value any number or function to execute (see DefaultScope implementation for examples).

You can also specify your Scope Class, that has to extend dice\Scope.

• Expression (space-insensitive): d6 + foo * bar() / defaultSides + min(d12, 2d4) + rerollBelow(5, 3d6)
• Render after evaluation: { 1d6 : [ 2 ] } + { foo : 2 } * { bar ( ): 3 } / { defaultSides : 6 } + { min ( { 1d12 : [ 10 ] }, { 2d4 : [ 1, 2 ] } ): 3 } + { rerollBelow ( 5, { 3d6 : [ 6, 6, 4 ] } ): 18 }
• Stringified version: 1d6 + foo * bar() / defaultSides + min(1d12, 2d4) + rerollBelow(5, 3d6)
• Value (rolled): 24

The grammar is built with PEG.js. Its PHP version is generated by php-pegjs.

If you need to customize the grammar/dice.pegphp, you can regenerate src/Parser via Javascript:

# Install node modules
npm install

# Build dice\Parser for PHP
npm run build

Serve index.php with your favourite webserver and browse to http://localhost/php-dice/index.php.

You can enter the expression to parse in the textbox and submit the form by clicking on the "Roll" button.

Details and results will be shown below.

php-dice is released under the MIT License. See the bundled LICENSE.md for details.