PHPackages                             jifish/ezdice - 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. jifish/ezdice

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

jifish/ezdice
=============

A really simple PHP library for parsing dice notation and rolling.

1.2.0(1w ago)567MITPHPPHP >=8.0

Since Nov 11Pushed 1w ago1 watchersCompare

[ Source](https://github.com/JiFish/ezdice)[ Packagist](https://packagist.org/packages/jifish/ezdice)[ Docs](https://github.com/JiFish/ezdice)[ RSS](/packages/jifish-ezdice/feed)WikiDiscussions master Synced 5d ago

READMEChangelog (9)DependenciesVersions (11)Used By (0)

EZDice
======

[](#ezdice)

A really simple PHP library for parsing dice notation and rolling. By Joseph Fowler aka JiFish.

Works in PHP 8+.

Why use EZDice?
---------------

[](#why-use-ezdice)

EZDice was written because I wasn't happy with similar libraries. EZDice has the following advantages over other offerings:

- No Bloat. EZDice is one simple class with no dependencies.
- Provides the state of each die after the roll, not just the total.
- Forgiving parser designed for humans.
- Option to easily replace the RNG.
- MIT licensed, ensuring you can use it freely in any project.

Usage
-----

[](#usage)

Here's a basic example

```
require 'ezdice.php';

$ezd = new ezdice\EZDice();
echo($ezd->roll('1d20+2d4'));
echo(' Rolls:');
foreach($ezd->getDiceStates() as $die) {
    echo(' ['.$die['value'].'] ');
}

```

Example Output:

```
23 Rolls: [17] [4] [2]

```

Installing with Composer
------------------------

[](#installing-with-composer)

You don't have to use composer to include EZDice in your project, but you can:

`composer require jifish/ezdice`

Methods
-------

[](#methods)

### roll($diceStr)

[](#rolldicestr)

Parse **$diceStr** as dice notation, then roll those dice. Returns *(int)* total of all rolls and modifiers, or *false* if none were found.

The parser is very forgiving, ignoring whitespace and anything else it doesn't recognize. It is also case-insensitive. Dice notation is briefly documented below.

### getTotal()

[](#gettotal)

Returns *(int)* that is the total of the last roll.

### getDiceStates()

[](#getdicestates)

Returns an *(array)* of dice that describes the state of the dice after the last roll. Each die is also an *(array)* with the following keys:

- **sides** - *(int)* the number of sides the die has
- **value** - *(int)* the value the die rolled
- **dropped** - *(bool)* *true* if this dice was dropped, otherwise *false*. Dropped dice aren't counted towards the total.
- **negative** - *(bool)* *true* if this dice was subtracted from the total, *false* if it was added.
- **type** - *(str)* string with the type of dice this is. e.g. "d6" or "dF"
- **group** - *(int)* the group number this die belongs to, starting from 1 for the first group found.

### getModifier()

[](#getmodifier)

Returns a *(string)* representing the total of all modifiers in the last roll. If there were no modifiers, or they cancelled out, an empty string is returned. You can cast this to an *(int)* if needed.

e.g. if you rolled `1d8+10+1d4-2` this method would return `+8`.

### getDiceGroupNumber()

[](#getdicegroupnumber)

Returns an *(int)* containing the total number of dice groups in the last roll. e.g. if you rolled `10d4-1d6`, this method would return `2`.

### getDiceModsNumber()

[](#getdicemodsnumber)

Returns an *(int)* containing the total number of modifiers in the last roll. e.g. if you rolled `10+1d6+5-1`, this method would return `3`.

### strContainsDice($diceStr)

[](#strcontainsdicedicestr)

Parse **$diceStr** and returns true if it contains at least one dice roll, otherwise returns false. Useful for verifying user input. Modifiers without dice don't count.

### strIsStrictlyDice($diceStr, $allowWhitespace = true, $mustContainDice = true)

[](#strisstrictlydicedicestr-allowwhitespace--true-mustcontaindice--true)

Parse **$diceStr** and determine if it only contains dice and modifiers. Whitespace is allowed unless **$allowWhitespace** is set to false, but strings containing only whitespace will never pass. Set **$mustContainDice** to false to allow plain modifiers without dice (e.g. `-4`) to pass. Returns true if **$diceStr** passes, otherwise false.

The **roll** function ignores stuff it can't parse, so this function may be useful if you need to verify a string doesn't contain additional junk.

### rollStrict($diceStr, $allowWhitespace = true, $mustContainDice = true)

[](#rollstrictdicestr-allowwhitespace--true-mustcontaindice--true)

Convenience function that returns false if **$diceStr** is not strictly dice (as above), but otherwise works the same as **roll()**.

Dice Notation
-------------

[](#dice-notation)

- Dice notation is in the form (number of dice)**d**(dice sides). e.g. `2d10`.
- Number of dice can be omitted to get one die of that type, e.g. `d12`
- Additional dice can be chained with **+** and **-** operators. e.g. `2d10+1d6`.
- Modifiers can also be given. e.g. `2d10-5`
- d% can be used as a shorthand for a percentile dice. `1d%` and `1d100` are equivalent.
- Append a roll with -L to drop the lowest dice in that group, or -H to drop the highest. Dropped dice are excluded from the total. e.g. `2d20-L` will roll 2 twenty sided dice and drop the lowest. You can also specify a number of dice to drop e.g. `6d6-H3` will drop the highest 3 rolls.
- dF can be used to roll a Fudge/FATE dice. Fudge dice have 3 outcomes: -1, 0, and +1.
- Whitespace, and anything else not recognized as a dice or a modifier, is treated like a **+** operator. e.g. `foo10 1d4bar1d4  5` is equivalent to `5+1d4+1d4+10`, or simply `2d4+15`. If this is an issue, use **rollStrict**.
- Groups of zero dice, or dice with zero sides e.g. `0d0` are invalid and won't be parsed.

Replacing the random number generator
-------------------------------------

[](#replacing-the-random-number-generator)

By default *mt\_rand()* is used as the RNG, which should be fine for most applications. If you want to change this, you can extend the class and override the method **getRandomNumber($max)**, which should return an int equal to or between 1 to $max.

```
class WeightedDice extends ezdice\EZDice {
    protected function getRandomNumber(int $max): int {
        if (mt_rand(0,1)) return $max;
        return mt_rand(1,$max);
    }
}

```

Legalese
--------

[](#legalese)

Released under the MIT license. Copyright (c) 2021 - 2025 Joseph Fowler.

###  Health Score

48

—

FairBetter than 94% of packages

Maintenance98

Actively maintained with recent releases

Popularity14

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity61

Established project with proven stability

 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 ~204 days

Recently: every ~346 days

Total

9

Last Release

13d ago

Major Versions

0.3.0 → 1.0.02022-09-25

PHP version history (2 changes)0.1.0PHP >=7.0

1.2.0PHP >=8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/e48d250a957e43aeb5f5f5d123baf95def93b06ead9e2efc47862b399f011b0c?d=identicon)[JiFish](/maintainers/JiFish)

---

Top Contributors

[![JiFish](https://avatars.githubusercontent.com/u/1314002?v=4)](https://github.com/JiFish "JiFish (20 commits)")

---

Tags

dicedice-notationdice-rollerdielibraryphpphp7php8randomdicerollrpgdice rollerdierollerdice notation

### Embed Badge

![Health badge](/badges/jifish-ezdice/health.svg)

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

###  Alternatives

[paragonie/random_compat

PHP 5.x polyfill for random\_bytes() and random\_int() from PHP 7

8.2k655.0M405](/packages/paragonie-random-compat)[ircmaxell/random-lib

A Library For Generating Secure Random Numbers

84130.2M119](/packages/ircmaxell-random-lib)[mistic100/randomcolor

Generate attractive random colors

2431.4M6](/packages/mistic100-randomcolor)[pragmarx/random

Create random chars, numbers, strings

714.2M5](/packages/pragmarx-random)[paragonie/random-lib

A Library For Generating Secure Random Numbers

703.3M26](/packages/paragonie-random-lib)[nubs/random-name-generator

A library to create interesting, sometimes entertaining, random names.

135680.2k3](/packages/nubs-random-name-generator)

PHPackages © 2026

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