PHPackages                             christhompsontldr/laravel-rng - 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. christhompsontldr/laravel-rng

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

christhompsontldr/laravel-rng
=============================

Deterministic, stream-isolated RNG for Laravel using PHP native Random extension

v1.0.0(3mo ago)013MITPHPPHP ^8.4

Since Feb 11Pushed 3mo agoCompare

[ Source](https://github.com/ChrisThompsonTLDR/laravel-rng)[ Packagist](https://packagist.org/packages/christhompsontldr/laravel-rng)[ RSS](/packages/christhompsontldr-laravel-rng/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (11)Versions (2)Used By (0)

Laravel RNG
===========

[](#laravel-rng)

Deterministic, stream-isolated RNG for Laravel using PHP's native Random extension. Ideal for games, simulations, and reproducible seeding pipelines.

Installation
------------

[](#installation)

```
composer require christhompsontldr/laravel-rng
```

Configuration
-------------

[](#configuration)

Publish the config file:

```
php artisan vendor:publish --tag=rng-config
```

Environment variables:

VariableDescription`RNG_MASTER_SEED`Master seed for deterministic RNG. When set, all streams produce reproducible sequences.`RNG_LOGGING`When `true`, each roll is logged for audit (use `rng:audit` to view).Basic Usage
-----------

[](#basic-usage)

```
use Rng\RngManager;

$rng = app(RngManager::class);
$stream = $rng->for('my_stream');

// Integer in range (inclusive)
$roll = $stream->int(1, 20);  // d20

// Boolean with probability (0.0 - 1.0)
$hit = $stream->chance(0.75);  // 75% hit chance

// Pick one item from array (uniform)
$item = $stream->pick(['sword', 'shield', 'potion']);
```

Streams are isolated: `seeding` and `combat` produce independent sequences from the same master seed.

RPG Seeding Example
-------------------

[](#rpg-seeding-example)

Reproducible unit generation for a low-fantasy game:

```
use Rng\RngManager;

$rng = app(RngManager::class);
$seeding = $rng->for('seeding');

$archetypes = ['scout', 'heavy', 'mixed'];
$units = [];

for ($i = 0; $i < 25; $i++) {
    $arch = $seeding->pick($archetypes);
    $cp = $seeding->int(60, 90);
    $ipBudget = 100 - $cp;
    $units[] = compact('arch', 'cp', 'ipBudget');
}
// Same master seed → same 25 units every run
```

With a database factory (e.g. Newland `UnitFactory`):

```
$rng = app(RngManager::class);
$seeding = $rng->for('seeding');

for ($i = 0; $i < 25; $i++) {
    $arch = $seeding->pick(['scout', 'heavy', 'mixed']);
    $cp = $seeding->int(60, 90);
    UnitFactory::new()
        ->lowFantasy()
        ->archetype($arch)
        ->cpValue($cp)
        ->create(['ip_budget' => 100 - $cp]);
}
```

Combat Example
--------------

[](#combat-example)

Deterministic combat rolls per turn:

```
$rng = app(RngManager::class);
$combat = $rng->for('combat');

// Initiative
$initiative = $combat->int(1, 20);

// Attack roll
$attackRoll = $combat->int(1, 20);

// Damage
$damage = $combat->int(2, 12);

// Hit chance (e.g. 65%)
$hit = $combat->chance(0.65);
```

When `rng.logging` is `true`, each roll is logged with stream name, roll index, type, and result. Run `php artisan rng:audit` to inspect.

Testing
-------

[](#testing)

Override the master seed in tests for predictable fixtures:

```
// In setUp() or test
config(['rng.default_master_seed' => 42]);

$rng = app(RngManager::class);
$stream = $rng->for('seeding');
$arch = $stream->pick(['scout', 'heavy']);  // Deterministic
```

Or inject directly when not using the container:

```
$manager = new \Rng\RngManager(42);
$stream = $manager->for('seeding');
```

Use `rng:test-seed` to generate a sample roll sequence for fixtures:

```
php artisan rng:test-seed
# Seed: 42
# [16, 4, 13, 19, 1]

php artisan rng:test-seed 12345
# Seed: 12345
# [19, 7, 14, 18, 20]
```

Artisan Commands
----------------

[](#artisan-commands)

CommandDescription`rng:seed {seed}`Set `RNG_MASTER_SEED` in `.env``rng:audit`Show logged rolls (when logging enabled)`rng:test-seed {seed?}`Output seed and sample d20 sequence for fixturesRequirements
------------

[](#requirements)

- PHP 8.4+
- Laravel 12+

License
-------

[](#license)

MIT

###  Health Score

39

—

LowBetter than 86% of packages

Maintenance82

Actively maintained with recent releases

Popularity8

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity51

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

Unknown

Total

1

Last Release

97d ago

### Community

Maintainers

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

---

Top Contributors

[![codeingboss](https://avatars.githubusercontent.com/u/37710297?v=4)](https://github.com/codeingboss "codeingboss (1 commits)")

---

Tags

randomlaravelRNGdeterministicseeded

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/christhompsontldr-laravel-rng/health.svg)

```
[![Health](https://phpackages.com/badges/christhompsontldr-laravel-rng/health.svg)](https://phpackages.com/packages/christhompsontldr-laravel-rng)
```

###  Alternatives

[barryvdh/laravel-ide-helper

Laravel IDE Helper, generates correct PHPDocs for all Facade classes, to improve auto-completion.

14.9k123.0M687](/packages/barryvdh-laravel-ide-helper)[wnx/laravel-stats

Get insights about your Laravel Project

1.8k1.8M7](/packages/wnx-laravel-stats)[livewire/flux

The official UI component library for Livewire.

9475.0M86](/packages/livewire-flux)[laragear/preload

Effortlessly make a Preload script for your Laravel application.

119363.5k](/packages/laragear-preload)[glhd/conveyor-belt

14797.0k](/packages/glhd-conveyor-belt)[getsolaris/laravel-make-service

A MVCS pattern create a service command for Laravel 5+

81161.3k](/packages/getsolaris-laravel-make-service)

PHPackages © 2026

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