Alea Laravel Package

Product Decisions This Supports

• Feature: reproducible randomization. Any feature that says "random" but must be stable — a shuffled feed, a "random pick of the day," rotating hero content, a sampled set of recommendations — needs a seedable PRNG. Alea gives you seed → same sequence, which turns a page that can never be cached into one you can cache by seed.
• Experimentation and bucketing. Deterministic variant assignment (hash(userId) → variant) can be done with any hash, but a seeded PRNG lets you go further: per-user content sampling, not just variant labels, computed identically in PHP and in the browser. This is the core product unlock — no round trip, no flicker, no server-side lookup table for assignment.
• Build vs. buy vs. port. Alea is ~a page of algorithm code with zero transitive dependencies and an MIT license. The real build-vs-buy decision is not "adopt this package" but "adopt this algorithm." Buy (depend) if cross-language Alea parity matters; vendor/port (30–80 lines plus test vectors) if you only need PHP-side determinism and want to own the surface area.
• Caching and cost roadmap. Seeded randomness is a cache strategy, not just a feature. Decisions like "can we personalize this endpoint without killing CDN hit rate?" get a yes if the randomness is a function of a seed rather than of request time.
• Testability as a roadmap enabler. Nondeterministic code is untestable code. Adopting a seedable generator lets QA and CI replay exact sequences, which lowers the cost of shipping any randomized feature and removes a recurring "flaky test" tax from the roadmap.
• Explicit non-use cases to record as decisions. Not for security tokens, password resets, promotional draws with real prizes, or anything with legal/fairness exposure. Documenting that boundary is itself a product decision — it prevents a future team from reaching for the wrong tool.

When to Consider This Package

Consider it when:

• You need the same random sequence produced by PHP and JavaScript (Alea is a port of the JS Alea PRNG; parity is the entire point and the only reason to accept the governance cost).
• You need output that is stable across PHP upgrades. mt_rand() changed behaviour in PHP 7.1; Alea's sequence won't drift under you, which matters if seeds are persisted or embedded in URLs.
• You need isolated RNG state — a generator object you can pass around and re-seed, without mt_srand() globally poisoning unrelated code paths.
• Seeds will be stored or shared (cache keys, shareable links, experiment assignments) and must remain valid for months.

Look elsewhere when:

• You need cryptographic randomness — use random_bytes() / random_int(). Never this.
• You are PHP 8.2+ only and have no browser-parity requirement: Random\Randomizer with Xoshiro256StarStar gives you native seeded reproducibility with zero dependencies and a vendor-backed future. This is the strongest competing option and should be evaluated first.
• You need statistical distributions (weighted choice, normal, Poisson) or quality guarantees — reach for a dedicated stats/random library; Alea's value is reproducibility, not distributional richness.
• You need a maintained, semver-tagged, issue-tracked dependency. Be honest about the signals here: 3 stars, 0 dependents, an opportunity score of 0.015, and a repo that is explicitly a mirror of Gerrit with contributions routed through a Wikimedia developer account. There is no GitHub PR workflow, no community to share maintenance with, and effectively no external production usage to lean on.
• Your team cannot absorb ownership. With those adoption signals, treat this as "a proven algorithm with a convenient wrapper," not "a community-standard package." Plan to pin the version, wrap it behind your own interface, and add golden test vectors so you can replace it.

How to Pitch It (Stakeholders)

To executives (30 seconds): "This is a very small, MIT-licensed utility from Wikimedia that makes random choices repeatable — the same seed always produces the same result, in PHP and in the browser. That lets us ship randomized features that are still cacheable and A/B tests that are consistent without a database lookup. Cost is near zero and risk is low because the code is tiny and we can replace it. The caveat is that it's essentially a one-org project with no community momentum, so we should budget a small amount of engineering ownership rather than assume it's a standard dependency."

To engineering (the actual ask):

• What it is: a seedable pseudorandom number generator, a PHP port of the JavaScript Alea PRNG. Small, MIT, no meaningful dependency graph.
• Why we'd take the dependency: byte-for-byte parity with the JS implementation, and a sequence that doesn't change when PHP's internals change. That is the only justification — everything else is achievable natively.
• Integration: composer require, construct a generator with a seed derived from user/session/content ID, inject it where randomness is needed. One day of work, plus tests.
• Risks and mitigations: Gerrit-only contribution path (no GitHub PRs — bug fixes are ours or nobody's); mirror can lag; version pinning is mandatory. Mitigate by hiding it behind our own Randomizer interface and committing golden vectors so a swap to Random\Randomizer (PHP 8.2+) or a vendored port is a contained change.
• Decision gate: if the browser-parity requirement doesn't survive product scoping, we drop this dependency and use native PHP 8.2 seeded randomizers instead. Confirm that requirement before we write the integration ticket.