PHPackages                             kusabi/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. [Utility & Helpers](/categories/utility)
4. /
5. kusabi/dice

ActiveLibrary[Utility & Helpers](/categories/utility)

kusabi/dice
===========

A table top dice library for PHP

1.0.2(5y ago)04MITPHPPHP >=5.6CI failing

Since Nov 1Pushed 5y ago1 watchersCompare

[ Source](https://github.com/kusabi/dice)[ Packagist](https://packagist.org/packages/kusabi/dice)[ RSS](/packages/kusabi-dice/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (1)Dependencies (3)Versions (4)Used By (0)

PHP Dice
========

[](#php-dice)

[![Tests](https://github.com/kusabi/dice/workflows/tests/badge.svg)](https://github.com/kusabi/dice/workflows/tests/badge.svg)[![codecov](https://camo.githubusercontent.com/521e8e57a1c53ad0702a0abac3ed069d48159913445ede23c7096ddd24c19365/68747470733a2f2f636f6465636f762e696f2f67682f6b75736162692f646963652f6272616e63682f6d61696e2f67726170682f62616467652e737667)](https://codecov.io/gh/kusabi/dice)[![Licence Badge](https://camo.githubusercontent.com/ade59d47a0f2f7939917e7d1b8d2fa9bcb50600c0fb5459c10985bc5f13fb824/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f6b75736162692f646963652e737667)](https://img.shields.io/github/license/kusabi/dice.svg)[![Release Badge](https://camo.githubusercontent.com/41b657a2d96633ae8126aebe69813ed89656de8b236c2a6b7ef6b289d54f28b8/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f72656c656173652f6b75736162692f646963652e737667)](https://img.shields.io/github/release/kusabi/dice.svg)[![Tag Badge](https://camo.githubusercontent.com/1ed1ffbf70d1164add3e39e0afa4e98f6d1e2499ce7d97892452664673331881/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f7461672f6b75736162692f646963652e737667)](https://img.shields.io/github/tag/kusabi/dice.svg)[![Issues Badge](https://camo.githubusercontent.com/262073201f524f6863bf67884aaba08a921c9fc1e046bc63d708fc64112bf56e/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6973737565732f6b75736162692f646963652e737667)](https://img.shields.io/github/issues/kusabi/dice.svg)[![Code Size](https://camo.githubusercontent.com/73d2f50be3efa8825f169d3bc2ee22aaed49e45fbbb6840e29f6e5965265c4e1/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c616e6775616765732f636f64652d73697a652f6b75736162692f646963652e7376673f6c6162656c3d73697a65)](https://img.shields.io/github/languages/code-size/kusabi/dice.svg)

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

Compatibility and dependencies
------------------------------

[](#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)

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

[](#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
--------------------

[](#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
---------------------------

[](#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
-----------------------------

[](#using-the-dice-modifier-class)

The `DiceModifier` class uses the [Decorator](https://sourcemaking.com/design_patterns/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
--------------------------

[](#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
----------------------

[](#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";
}
```

###  Health Score

23

—

LowBetter than 27% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity3

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity55

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

Every ~185 days

Total

3

Last Release

2019d ago

PHP version history (2 changes)1.0.0PHP ~7.2

1.0.1PHP >=5.6

### Community

Maintainers

![](https://www.gravatar.com/avatar/62f4942978644437b5ff3d7bd3f6411580413d327b001104acd4914f43ab63b6?d=identicon)[kusabi](/maintainers/kusabi)

---

Top Contributors

[![kusabi](https://avatars.githubusercontent.com/u/22000941?v=4)](https://github.com/kusabi "kusabi (13 commits)")

---

Tags

dicedndlibraryphptable-top

###  Code Quality

TestsPHPUnit

Code StylePHP CS Fixer

### Embed Badge

![Health badge](/badges/kusabi-dice/health.svg)

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

###  Alternatives

[lexxpavlov/settingsbundle

Symfony2/3/4 Settings bundle provides flexible settings (Boolean, Integer, Float, String, Text, Html), easily configurable with Sonata Admin

104.5k](/packages/lexxpavlov-settingsbundle)

PHPackages © 2026

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