PHP Dice

^{A library designed to simulate the table-top dice for games like Dungeons and Dragons.}

Compatibility and dependencies

This library is compatible with PHP version 5.6, 7.0, 7.1, 7.2, 7.3 and 7.4.

This library has no dependencies.

Installation

Installation is simple using composer.

composer require kusabi/dice

Or simply add it to your composer.json file

{
    "require": {
        "kusabi/dice": "^1.0"
    }
}

Using the library

The simplest way to use the library is by using the Dice factory class.

A simple example would be

use Kusabi\Dice\DiceFactory;

$result = DiceFactory::createFromString('5d12+4')->getRoll();

Using the dice class

This library contains 4 dice implementations that when used together can simulate a huge range of possibilities.

The first class is Dice.

A Dice object can represent most basic rolls in a table-top game.

It takes 3 optional parameters to set the number of sides, the multiplier and the offset.

Without any parameters it will default to represent 1d6.

use Kusabi\Dice\Dice;

$dice = new Dice(12, 2, 5);
$min = $dice->getMinimumRoll();
$max = $dice->getMaximumRoll();
$result = $dice->getRoll();

$string = (string) $dice; // 2d12+5

Using the single dice class

The other three dice classes can be used in combination, to create much more complex dice setups.

The first of these is SingleDice. A SingleDice object takes a single parameter which represents the number of sides it has.

use Kusabi\Dice\SingleDice;

$dice = new SingleDice(4);
$min = $dice->getMinimumRoll();
$max = $dice->getMaximumRoll();
$result = $dice->getRoll();

$string = (string) $dice; // 1d4

Using the dice modifier class

The DiceModifier class uses the Decorator pattern to augment the results of another implementation of DiceInterface.

It takes two arguments, the first is another object that implements DiceInterface and the second is an integer to augment the result by.

The example below simulates how you might represent 1D12+4.

use Kusabi\Dice\SingleDice;
use Kusabi\Dice\DiceModifier;

$dice = new DiceModifier(New SingleDice(12), 4);
$min = $dice->getMinimumRoll();
$max = $dice->getMaximumRoll();
$result = $dice->getRoll();

Using the dice group class

The DiceGroup can cluster multiple implementations of DiceInterface together, and returns the sum of results from all of them.

Because one of those instances can be a Dice, SingleDice, DiceModifier or even another DiceGroup and because this object can itself by placed into a DiceModifier instance, the possibilities are fairly sufficient.

The example below simulates how you might represent 5D12+4.

use Kusabi\Dice\Dice;
use Kusabi\Dice\DiceModifier;
use Kusabi\Dice\DiceGroup;
use Kusabi\Dice\SingleDice;

$dice = new DiceModifier(
    new DiceGroup(
        new SingleDice(12), 
        new SingleDice(12), 
        new SingleDice(12), 
        new Dice(12), 
        new Dice(12)
    ), 4
);
$min = $dice->getMinimumRoll();
$max = $dice->getMaximumRoll();
$result = $dice->getRoll();

Using the dice factory

The DiceFactory makes creating a die implementation simpler.

You can pass it the common string form of a die instead of figuring out how to build it.

use Kusabi\Dice\DiceFactory;

$dice = DiceFactory::createFromString('5d12+4');
$min = $dice->getMinimumRoll();
$max = $dice->getMaximumRoll();
$result = $dice->getRoll();

or more simply

use Kusabi\Dice\DiceFactory;

$result = DiceFactory::createFromString('5d12+4')->getRoll();

The class will throw an /InvalidArgumentException if it fails to parse the string so make sure you plan for that.

use Kusabi\Dice\DiceFactory;

try {
    $result = DiceFactory::createFromString('5d12+4')->getRoll();
} catch(\InvalidArgumentException $exception) {
    echo "Could not parse the string";
}