PHPackages ipapikas/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. ipapikas/dice ActiveLibrary[Utility & Helpers](/categories/utility) ipapikas/dice ============= Dice allows you to pick an option from a given pool with a given set of probabilities. v2.1.1(1y ago)18.3k↓15%1MITPHPPHP ^8.3 Since Jul 4Pushed 1y ago1 watchersCompare [ Source](https://github.com/ioannis-papikas/dice)[ Packagist](https://packagist.org/packages/ipapikas/dice)[ RSS](/packages/ipapikas-dice/feed)WikiDiscussions 2.0 Synced 1mo ago READMEChangelog (1)Dependencies (1)Versions (11)Used By (0) Dice ==== [](#dice) Dice allows you to pick an option from a given pool with a given set of probabilities. [![StyleCI](https://camo.githubusercontent.com/57a75f72d0c63cbf4b6e542428c6d939ce544fd5379cfbd4d7b6a16810cf3ab6/68747470733a2f2f7374796c6563692e696f2f7265706f732f39363132373836312f736869656c643f6272616e63683d312e30)](https://styleci.io/repos/96127861)[![Latest Stable Version](https://camo.githubusercontent.com/793635d26b7e6df562be3e567c20194cd2c59e17cb9574e0391a8f15e9c41e1f/68747470733a2f2f706f7365722e707567782e6f72672f69706170696b61732f646963652f762f737461626c653f666f726d61743d666c61742d737175617265)](https://packagist.org/packages/ipapikas/dice)[![Total Downloads](https://camo.githubusercontent.com/ca7598e660ee356aa1e60718e0de4862c715d0333ef65a1b9b0ec8b18d0fb9cd/68747470733a2f2f706f7365722e707567782e6f72672f69706170696b61732f646963652f646f776e6c6f6164733f666f726d61743d666c61742d737175617265)](https://packagist.org/packages/ipapikas/dice)[![License](https://camo.githubusercontent.com/0d2f1ce992d5759bb5ac1970ab05fe29703832d974b6fe7aef230c658973aaef/68747470733a2f2f706f7365722e707567782e6f72672f69706170696b61732f646963652f6c6963656e73653f666f726d61743d666c61742d737175617265)](https://packagist.org/packages/ipapikas/dice) - [Introduction](#introduction) - [Installation](#installation) - [Through the composer](#through-the-composer) - [How It Works](#how-it-works) - [Distributions](#distributions) Introduction ------------ [](#introduction) Dice is a basic library that offers a random handler for simulating the throw of a Dice. In other words, it allows you to choose an option from a given set of options with specified probabilities. Dice provides a set of Distributions and Randomizers to allow you to select your own. You can select Distributions that have equal probabilities (Dice, Coin etc.) or build your own Distributions that might not have the same probabilities, depending on the usage. Dice is still in **beta** version and we are making extended tests and use cases to validate its use and create a stable version. Installation ------------ [](#installation) You can install Dice simply by adding the files into your project or using the composer. ### Through the composer [](#through-the-composer) Add the following line to your `composer.json` file: ``` "ipapikas/dice": "^1.0" ``` Roller ------ [](#roller) Dice includes a main Roller that receives a Distribution and a Randomizer and selects the next value of the given Distribution. Example: ``` use \Dice\Distributions\CoinDistribution; use \Dice\Random\MTRand; use \Dice\Roller; // Create new Distribution $coin = new CoinDistribution(); // Create a new Randomizer $randomizer = new MTRand(); // Create new Roller $roller = new Roller($coin, $randomizer); // "Roll" the Dice and get the next item from the distribution // In this example, the value can be either 1 (Head) or 2 (Tail), // based on the Distribution $value = $roller->roll(); ``` How It Works ------------ [](#how-it-works) Roller has the main logic of the library here. Roller is the main handler that is responsible for taking the next value of the distribution and making sure that there is enough logic to be able to choose among a set of values. Roller's work is to take all value possibilities and expand them into a world where there are 100 (or 1000 or more) pebbles. Based on the probability distribution, the Roller selects a specific number of pebbles and colors them with the value of the Distribution. Based on the probability, it selects the right amount of pebbles in order to allow the the Distribution to be biased or unbiased. After the expansion is over, it uses the Randomizer to select a pebble from 1 to 100 (or 1000 or more). Since the pebbles are a lot more than the values in the Distribution, we can make sure that it can work without making any biased decisions or leaving anything out. **Pebbles** The number of pebbles is determined based on the amount of precision is needed for the given probabilities. If the probabilities are just 50% each, 10 pebbles are enough to choose a number between 1 and 10 and determine which pebbles are which value. If the probabilities are in as low as 1.5%, the amount of pebbles will be 1000, to allow 1.5% to be seen a 15 pebbles at least. **Keep in mind** Based on the description above, the amount of pebbles is determined by the amount of precision. It is essential to build your Distributions to use `ProbabilityValidator` to make sure that your probabilities sum up to 1. Otherwise, Roller will not be able to select properly your values and it will leave some cases (pebbles) out. For example, if you have the following probabilities: - 10% - 15% - 25% - 30% - 10% - 15% The above sum up to 105% (or 1.05). The amount of pebbles will be set to 100, leaving out 5 pebbles for the last probability, which will be capped to the following: - 10% - 15% - 25% - 30% - 10% - **10%** Or there are cases where a value might be removed from the pebble pool, because it was completely above 1. Example: - 10% - 15% - 25% - 30% - 20% - **10%** -> This probability will be excluded completely Distributions ------------- [](#distributions) You can easily create your own distribution that will match your needs. All you have to do is to setup your validators, if any. In your code, you can set your own items as dynamic values based on your own logic. Example: ``` use Dice\Distributions\AbstractDistribution; use Dice\Validators\ProbabilityValidator; use Dice\Validators\UnBiasedValidator; /** * Class WeatherDistribution */ class WeatherDistribution extends AbstractDistribution { const SUNNY = 1; const RAIN = 2; const CLOUDY = 3; const SNOW = 4; /** * WeatherDistribution constructor. */ public function __construct() { // Set validators $this->setValidators([ new ProbabilityValidator(), new UnBiasedValidator(), ]); } /** * @return mixed */ public function getItems() { return [ self::SUNNY => 1 / 4, self::RAIN => 1 / 4, self::CLOUDY => 1 / 4, self::SNOW => 1 / 4, ]; } } ``` If you are developing a game, you can build the above Distribution to decide what the weather be like every single day. Or, you can set the Distribution to be biased and be more rainy than usual (66% chance of rain and 11% of any other weather): ``` use Dice\Distributions\AbstractDistribution; use Dice\Validators\ProbabilityValidator; /** * Class RainyWeatherDistribution */ class RainyWeatherDistribution extends AbstractDistribution { const SUNNY = 1; const RAIN = 2; const CLOUDY = 3; const SNOW = 4; /** * RainyWeatherDistribution constructor. */ public function __construct() { // Set validators $this->setValidators([ new ProbabilityValidator(), ]); } /** * @return mixed */ public function getItems() { return [ self::SUNNY => 1 / 9, self::RAIN => 2 / 3, self::CLOUDY => 1 / 9, self::SNOW => 1 / 9, ]; } } ``` ### Health Score 46 — FairBetter than 93% of packages Maintenance45 Moderate activity, may be stable Popularity26 Limited adoption so far Community10 Small or concentrated contributor base Maturity84 Battle-tested with a long release history Bus Factor1 Top contributor holds 98.4% 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 ~312 days Recently: every ~0 days Total 10 Last Release 434d ago Major Versions v0.2 → v1.0.12018-01-14 v1.0.1 → v2.0.02024-11-13 PHP version history (2 changes)v0.1PHP ^7.0 v2.0.0PHP ^8.3 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/2780884?v=4)[Ioannis Papikas](/maintainers/ioannis-papikas)[@ioannis-papikas](https://github.com/ioannis-papikas) --- Top Contributors [![ioannis-papikas](https://avatars.githubusercontent.com/u/2780884?v=4)](https://github.com/ioannis-papikas "ioannis-papikas (62 commits)")[![ipatramanis](https://avatars.githubusercontent.com/u/33205987?v=4)](https://github.com/ipatramanis "ipatramanis (1 commits)") --- Tags distributionprobabilitiesrandom ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/ipapikas-dice/health.svg) ``` [![Health](https://phpackages.com/badges/ipapikas-dice/health.svg)](https://phpackages.com/packages/ipapikas-dice) ``` ### Alternatives [jeroendesloovere/vcard This VCard PHP class can generate a vCard with some data. When using an iOS device it will export as a .ics file because iOS devices don't support the default .vcf files. 5193.6M12](/packages/jeroendesloovere-vcard)[coderflex/laravel-ticket Laravel Ticket System, to help you manage your tickets eaisly 43178.0k1](/packages/coderflex-laravel-ticket)[prestashop/ps_shoppingcart PrestaShop module ps\_shoppingcart 117.6M2](/packages/prestashop-ps-shoppingcart)[prestashop/ps_crossselling PrestaShop - Cross selling 117.3M2](/packages/prestashop-ps-crossselling)[laracraft-tech/laravel-useful-additions A collection of useful Laravel additions! 58109.4k](/packages/laracraft-tech-laravel-useful-additions)[aaronddm/xml-builder A simple PHP based XML builder 29135.0k1](/packages/aaronddm-xml-builder) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)