PHPackages                             fr-esco/php-dice - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Parsing & Serialization](/categories/parsing)
4. /
5. fr-esco/php-dice

ActiveLibrary[Parsing & Serialization](/categories/parsing)

fr-esco/php-dice
================

A generic RPG dice roller syntax and library.

v1.0.0(10y ago)0376[2 issues](https://github.com/fr-esco/php-dice/issues)MITPHPPHP >=5.4

Since May 3Pushed 8y ago1 watchersCompare

[ Source](https://github.com/fr-esco/php-dice)[ Packagist](https://packagist.org/packages/fr-esco/php-dice)[ RSS](/packages/fr-esco-php-dice/feed)WikiDiscussions master Synced 3w ago

READMEChangelogDependenciesVersions (3)Used By (0)

php-dice [![Packagist Version](https://camo.githubusercontent.com/857f96328500ab52c97466ff62e5ab34f5e74eaa7cf14ecbea536d0d913bcbce/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f66722d6573636f2f7068702d646963652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/fr-esco/php-dice) [![Total Downloads](https://camo.githubusercontent.com/db7ace790c86d12070cdbc6b45870a82d73a9ab69a7126ed0003b43d03692103/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f66722d6573636f2f7068702d646963652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/fr-esco/php-dice) [![Software License](https://camo.githubusercontent.com/07aef1928285df2f50e7815eead6154ca637f4ee5997717f180f157802334c49/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f66722d6573636f2f7068702d646963652e7376673f7374796c653d666c61742d737175617265)](LICENSE.md)
==================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================

[](#php-dice---)

A generic RPG dice roller syntax and library.

Getting started
---------------

[](#getting-started)

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

### Download

[](#download)

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

```
composer require "fr-esco/php-dice"
```

### Usage

[](#usage)

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;
```

### Exception Handling

[](#exception-handling)

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);
}
```

### Customization

[](#customization)

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](src/DefaultScope.php) implementation for examples).

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

Example
-------

[](#example)

- 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`

Development
-----------

[](#development)

### Technology Stack

[](#technology-stack)

The grammar is built with [PEG.js](http://pegjs.org/). Its PHP version is generated by [php-pegjs](https://www.npmjs.com/package/php-pegjs).

### Customization

[](#customization-1)

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
```

### Visual Test

[](#visual-test)

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.

License
-------

[](#license)

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

###  Health Score

27

—

LowBetter than 47% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity12

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity59

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

3709d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/4931297?v=4)[Francesco Colamonici](/maintainers/fr-esco)[@fr-esco](https://github.com/fr-esco)

---

Top Contributors

[![fr-esco](https://avatars.githubusercontent.com/u/4931297?v=4)](https://github.com/fr-esco "fr-esco (21 commits)")

---

Tags

parserdicerollrpglauncherdie

### Embed Badge

![Health badge](/badges/fr-esco-php-dice/health.svg)

```
[![Health](https://phpackages.com/badges/fr-esco-php-dice/health.svg)](https://phpackages.com/packages/fr-esco-php-dice)
```

###  Alternatives

[nikic/php-parser

A PHP parser written in PHP

17.4k936.5M2.3k](/packages/nikic-php-parser)[doctrine/lexer

PHP Doctrine Lexer parser library that can be used in Top-Down, Recursive Descent Parsers.

11.2k942.7M149](/packages/doctrine-lexer)[erusev/parsedown

Parser for Markdown.

15.1k155.2M841](/packages/erusev-parsedown)[league/commonmark

Highly-extensible PHP Markdown parser which fully supports the CommonMark spec and GitHub-Flavored Markdown (GFM)

3.0k426.1M943](/packages/league-commonmark)[masterminds/html5

An HTML5 parser and serializer.

1.8k260.4M293](/packages/masterminds-html5)[sabberworm/php-css-parser

Parser for CSS Files written in PHP

1.8k204.2M72](/packages/sabberworm-php-css-parser)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)