{"id":20789515,"url":"https://github.com/kusabi/dice","last_synced_at":"2025-03-12T00:28:32.750Z","repository":{"id":57009989,"uuid":"218465017","full_name":"kusabi/dice","owner":"kusabi","description":"A table-top dice library for PHP","archived":false,"fork":false,"pushed_at":"2020-11-06T14:36:06.000Z","size":30,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-01-18T10:27:19.934Z","etag":null,"topics":["dice","dnd","library","php","table-top"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kusabi.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":".github/contributing.md","funding":null,"license":null,"code_of_conduct":".github/code_of_conduct.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-10-30T07:12:26.000Z","updated_at":"2020-11-06T15:14:15.000Z","dependencies_parsed_at":"2022-08-21T15:10:17.371Z","dependency_job_id":null,"html_url":"https://github.com/kusabi/dice","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kusabi%2Fdice","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kusabi%2Fdice/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kusabi%2Fdice/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kusabi%2Fdice/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kusabi","download_url":"https://codeload.github.com/kusabi/dice/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243135397,"owners_count":20241961,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dice","dnd","library","php","table-top"],"created_at":"2024-11-17T15:24:38.181Z","updated_at":"2025-03-12T00:28:32.726Z","avatar_url":"https://github.com/kusabi.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PHP Dice\n\n![Tests](https://github.com/kusabi/dice/workflows/tests/badge.svg)\n[![codecov](https://codecov.io/gh/kusabi/dice/branch/main/graph/badge.svg)](https://codecov.io/gh/kusabi/dice)\n[![Licence Badge](https://img.shields.io/github/license/kusabi/dice.svg)](https://img.shields.io/github/license/kusabi/dice.svg)\n[![Release Badge](https://img.shields.io/github/release/kusabi/dice.svg)](https://img.shields.io/github/release/kusabi/dice.svg)\n[![Tag Badge](https://img.shields.io/github/tag/kusabi/dice.svg)](https://img.shields.io/github/tag/kusabi/dice.svg)\n[![Issues Badge](https://img.shields.io/github/issues/kusabi/dice.svg)](https://img.shields.io/github/issues/kusabi/dice.svg)\n[![Code Size](https://img.shields.io/github/languages/code-size/kusabi/dice.svg?label=size)](https://img.shields.io/github/languages/code-size/kusabi/dice.svg)\n\n\u003csup\u003eA library designed to simulate the table-top dice for games like Dungeons and Dragons.\u003c/sup\u003e\n\n\n## Compatibility and dependencies\n\nThis library is compatible with PHP version `5.6`, `7.0`, `7.1`, `7.2`, `7.3` and `7.4`.\n\nThis library has no dependencies.\n\n## Installation\n\nInstallation is simple using composer.\n\n```bash\ncomposer require kusabi/dice\n```\n\nOr simply add it to your `composer.json` file\n\n```json\n{\n    \"require\": {\n        \"kusabi/dice\": \"^1.0\"\n    }\n}\n```\n\n## Using the library\n\nThe simplest way to use the library is by using the Dice factory class.\n\nA simple example would be\n\n```php\nuse Kusabi\\Dice\\DiceFactory;\n\n$result = DiceFactory::createFromString('5d12+4')-\u003egetRoll();\n```\n\n\n## Using the dice class\n\nThis library contains 4 dice implementations that when used together can simulate a huge range of possibilities.\n\nThe first class is `Dice`. \n\nA `Dice` object can represent most basic rolls in a table-top game.\n\nIt takes 3 optional parameters to set the number of sides, the multiplier and the offset.\n\nWithout any parameters it will default to represent 1d6.\n\n```php\nuse Kusabi\\Dice\\Dice;\n\n$dice = new Dice(12, 2, 5);\n$min = $dice-\u003egetMinimumRoll();\n$max = $dice-\u003egetMaximumRoll();\n$result = $dice-\u003egetRoll();\n\n$string = (string) $dice; // 2d12+5\n```\n\n## Using the single dice class\n\nThe other three dice classes can be used in combination, to create much more complex dice setups.\n\nThe first of these is `SingleDice`. A `SingleDice` object takes a single parameter which represents the number of sides it has.\n\n```php\nuse Kusabi\\Dice\\SingleDice;\n\n$dice = new SingleDice(4);\n$min = $dice-\u003egetMinimumRoll();\n$max = $dice-\u003egetMaximumRoll();\n$result = $dice-\u003egetRoll();\n\n$string = (string) $dice; // 1d4\n```\n\n## Using the dice modifier class\n\nThe `DiceModifier` class uses the [Decorator](https://sourcemaking.com/design_patterns/decorator) pattern to augment the results of another implementation of `DiceInterface`.\n\nIt takes two arguments, the first is another object that implements `DiceInterface` and the second is an integer to augment the result by.\n\nThe example below simulates how you might represent `1D12+4`.\n\n```php\nuse Kusabi\\Dice\\SingleDice;\nuse Kusabi\\Dice\\DiceModifier;\n\n$dice = new DiceModifier(New SingleDice(12), 4);\n$min = $dice-\u003egetMinimumRoll();\n$max = $dice-\u003egetMaximumRoll();\n$result = $dice-\u003egetRoll();\n```\n\n## Using the dice group class\n\nThe `DiceGroup` can cluster multiple implementations of `DiceInterface` together, and returns the sum of results from all of them.\n\nBecause 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.\n\nThe example below simulates how you might represent `5D12+4`.\n\n```php\nuse Kusabi\\Dice\\Dice;\nuse Kusabi\\Dice\\DiceModifier;\nuse Kusabi\\Dice\\DiceGroup;\nuse Kusabi\\Dice\\SingleDice;\n\n$dice = new DiceModifier(\n    new DiceGroup(\n        new SingleDice(12), \n        new SingleDice(12), \n        new SingleDice(12), \n        new Dice(12), \n        new Dice(12)\n    ), 4\n);\n$min = $dice-\u003egetMinimumRoll();\n$max = $dice-\u003egetMaximumRoll();\n$result = $dice-\u003egetRoll();\n```\n\n## Using the dice factory\n\nThe `DiceFactory` makes creating a die implementation simpler.\n\nYou can pass it the common string form of a die instead of figuring out how to build it.\n\n```php\nuse Kusabi\\Dice\\DiceFactory;\n\n$dice = DiceFactory::createFromString('5d12+4');\n$min = $dice-\u003egetMinimumRoll();\n$max = $dice-\u003egetMaximumRoll();\n$result = $dice-\u003egetRoll();\n```\n\nor more simply\n\n```php\nuse Kusabi\\Dice\\DiceFactory;\n\n$result = DiceFactory::createFromString('5d12+4')-\u003egetRoll();\n```\n\nThe class will throw an `/InvalidArgumentException` if it fails to parse the string so make sure you plan for that.\n\n```php\nuse Kusabi\\Dice\\DiceFactory;\n\ntry {\n    $result = DiceFactory::createFromString('5d12+4')-\u003egetRoll();\n} catch(\\InvalidArgumentException $exception) {\n    echo \"Could not parse the string\";\n}\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkusabi%2Fdice","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkusabi%2Fdice","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkusabi%2Fdice/lists"}