Laravel Rng Laravel Package

Getting Started

Begin by installing the package via Composer: composer require christhompsontldr/laravel-rng. Immediately after, publish the config file with php artisan vendor:publish --tag=rng-config to expose config/rng.php. The first real-world use case is reproducible seeding—e.g., generating consistent game units for testing. Set RNG_MASTER_SEED=42 in .env, then in a service or tinker: app(\Rng\RngManager::class)->for('seeding')->int(1, 20) will always yield the same sequence for that stream and seed. If you skip RNG_MASTER_SEED, randomness is cryptographically secure but not reproducible.

Implementation Patterns

• Stream-based isolation: Create separate streams for logically distinct domains (seeding, combat, loot) via $rng->for('name') to prevent unintended cross-stream dependency—e.g., loot drops shouldn’t advance initiative counters.
• Deterministic testing fixtures: In phpunit.xml, set <env name="RNG_MASTER_SEED" value="12345"/>, or in setUp(), inject config(['rng.default_master_seed' => 42]) so factories produce identical models every run.
• Audit trail for critical logic: Enable RNG_LOGGING=true, simulate a turn-based match, then inspect results with php artisan rng:audit. Ideal for debugging inconsistent multiplayer outcomes or validating RNG fairness in compliance contexts.
• CLI seed discovery: Run php artisan rng:test-seed 1337 to preview the first few rolls for a given seed—use this to pick a "lucky" seed that yields balanced initial states for seed-based tests.
• Direct manager instantiation: For shell scripts or helpers outside Laravel’s container (e.g., a cron-initiated simulation), instantiate \Rng\RngManager directly with new \Rng\RngManager(42)—no service provider needed.

Gotchas and Tips

• Config timing matters: Changing config('rng.default_master_seed') mid-request after a stream has been accessed is ineffective—manager instances retain their internal seed. Always set the seed before first access (e.g., in AppServiceProvider@boot or test setUp()).
• .env caching traps: If you update RNG_MASTER_SEED in .env but forget php artisan config:clear, your app continues using the old cached config—always clear config in multi-stage deploys.
• Avoid unintended reseeding: Calling $rng->for('combat') multiple times creates independent streams with separate internal states. If you need a single shared combat stream, bind it as a singleton: $this->app->singleton('rng.combat', fn() => app(RngManager::class)->for('combat')).
• Production ≠ determinism: In non-test environments, omit RNG_MASTER_SEED to preserve high-quality randomness from PHP’s Randomizer. Only set the seed when you need reproducibility (e.g., simulation pipelines, test runners).
• CLI audit filtering: Output from rng:audit can get verbose—use shell piping (php artisan rng:audit | grep combat | tail -n 20) to isolate last 20 combat rolls when debugging.