PHPackages                             niktomo/weighted-sample - 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. niktomo/weighted-sample

ActiveLibrary

niktomo/weighted-sample
=======================

Weighted random sampling with box-gacha and destructive draw modes

v0.1.0(1mo ago)00MITPHPPHP ^8.2CI passing

Since Mar 29Pushed 1mo agoCompare

[ Source](https://github.com/niktomo/weighted-sample)[ Packagist](https://packagist.org/packages/niktomo/weighted-sample)[ Docs](https://github.com/niktomo/weighted-sample)[ RSS](/packages/niktomo-weighted-sample/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (3)Versions (2)Used By (0)

weighted-sample
===============

[](#weighted-sample)

[日本語版 README はこちら](README-ja.md)

Weighted random sampling for PHP 8.2+. Three pool types cover the most common use cases: repeatable draws, destructive draws, and box-gacha style limited inventory.

[![CI](https://github.com/niktomo/weighted-sample/actions/workflows/ci.yml/badge.svg)](https://github.com/niktomo/weighted-sample/actions/workflows/ci.yml)[![PHP](https://camo.githubusercontent.com/187240af044d09d5b14a1d9d9ebdf3f7a993e4c7bc09bdb46b4ba661a891bf5b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e322532422d626c7565)](https://www.php.net)[![License](https://camo.githubusercontent.com/f8df3091bbe1149f398a5369b2c39e896766f9f6efba3477c63e9b4aa940ef14/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e)](LICENSE)

---

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

[](#installation)

```
composer require niktomo/weighted-sample
```

---

Pool Types
----------

[](#pool-types)

ClassDraw behaviorExhaustible`WeightedPool`Always draws from the full setNo`DestructivePool`Drawn item is removedYes`BoxPool`Each item has a count; removed when count reaches 0Yes---

WeightedPool
------------

[](#weightedpool)

Immutable pool. `draw()` always selects from all items according to their weights. Suitable for gacha, lotteries, and any scenario where items can be drawn repeatedly.

```
use WeightedSample\Pool\WeightedPool;

$pool = WeightedPool::of(
    [
        ['name' => 'SSR', 'weight' => 5],
        ['name' => 'SR',  'weight' => 15],
        ['name' => 'R',   'weight' => 80],
    ],
    fn($item) => $item['weight'],
);

$result = $pool->draw(); // ['name' => 'R', 'weight' => 80]  (most likely)
```

---

DestructivePool
---------------

[](#destructivepool)

Each drawn item is removed from the pool. Raises `EmptyPoolException` when exhausted. Suitable for raffles, shuffled draws, and scenarios where each item can only be drawn once.

```
use WeightedSample\Pool\DestructivePool;
use WeightedSample\Exception\EmptyPoolException;

$pool = DestructivePool::of(
    [
        ['id' => 1, 'weight' => 10],
        ['id' => 2, 'weight' => 30],
        ['id' => 3, 'weight' => 60],
    ],
    fn($item) => $item['weight'],
);

while (! $pool->isEmpty()) {
    $item = $pool->draw(); // each item drawn exactly once
}
```

---

BoxPool
-------

[](#boxpool)

Each item has a finite count. Drawing decrements the count; the item is removed when count reaches 0. Suitable for box-gacha, limited stock, and prize pools with fixed quantities.

```
use WeightedSample\Pool\BoxPool;

$pool = BoxPool::of(
    [
        ['name' => 'Gold',   'weight' => 10, 'stock' => 1],
        ['name' => 'Silver', 'weight' => 30, 'stock' => 3],
        ['name' => 'Bronze', 'weight' => 60, 'stock' => 6],
    ],
    fn($item) => $item['weight'],
    fn($item) => $item['stock'],
);

while (! $pool->isEmpty()) {
    $item = $pool->draw(); // up to 10 draws total (1 + 3 + 6)
}
```

---

Item Filtering
--------------

[](#item-filtering)

By default, items with `weight ≤ 0` (or `count ≤ 0` for `BoxPool`) are silently excluded. You can inject a custom filter to change this behavior.

### Default: PositiveValueFilter (silent exclusion)

[](#default-positivevaluefilter-silent-exclusion)

```
use WeightedSample\Filter\PositiveValueFilter;

// weight=0 items are excluded automatically — no exception thrown
$pool = WeightedPool::of($items, fn($i) => $i['weight']);
```

### StrictValueFilter (throw on invalid)

[](#strictvaluefilter-throw-on-invalid)

```
use WeightedSample\Filter\StrictValueFilter;

// Throws InvalidArgumentException if any item has weight ≤ 0
$pool = WeightedPool::of(
    $items,
    fn($i) => $i['weight'],
    filter: new StrictValueFilter(),
);
```

### CompositeFilter (combine multiple filters)

[](#compositefilter-combine-multiple-filters)

```
use WeightedSample\Filter\CompositeFilter;
use WeightedSample\Filter\PositiveValueFilter;

$myFilter = new class implements \WeightedSample\Filter\ItemFilterInterface {
    public function accepts(mixed $item, int $weight, ?int $count): bool
    {
        return $item['enabled'] === true;
    }
};

$pool = WeightedPool::of(
    $items,
    fn($i) => $i['weight'],
    filter: new CompositeFilter([new PositiveValueFilter(), $myFilter]),
);
```

---

Seeded Randomizer
-----------------

[](#seeded-randomizer)

Inject a seeded randomizer for deterministic results — useful in tests and simulations.

```
use WeightedSample\Randomizer\SeededRandomizer;

$pool = WeightedPool::of(
    $items,
    fn($i) => $i['weight'],
    randomizer: new SeededRandomizer(42), // fixed seed
);

// Always produces the same sequence for seed=42
$result = $pool->draw();
```

The default (no seed) uses `\Random\Engine\Secure` for cryptographically safe randomness.

---

Weight Distribution
-------------------

[](#weight-distribution)

All selection is performed using **prefix sum + binary search** (O(log n)) with integer arithmetic only — no floating-point rounding.

### Benchmark results

[](#benchmark-results)

**WeightedPool — 1,000,000 draws (SSR=1%, SR=9%, R=90%)**

```
Item        Draws    Actual%  Expected%     Diff
SSR         10050     1.005%     1.000%   +0.005%
SR          90058     9.006%     9.000%   +0.006%
R          899892    89.989%    90.000%   -0.011%

```

**WeightedPool — 100 items (weight 1–100), 1,000,000 draws**

```
Item        Draws    Actual%  Expected%     Diff
w1            199     0.020%     0.020%   +0.000%
w2            377     0.038%     0.040%   -0.002%
...
w100        20049     2.005%     1.980%   +0.025%
Max deviation: 0.0264%

```

Run the full benchmark:

```
docker compose run --rm benchmark
# or without Docker:
php benchmark/run.php
```

---

Requirements
------------

[](#requirements)

- PHP 8.2+
- No runtime dependencies

License
-------

[](#license)

MIT

###  Health Score

34

—

LowBetter than 77% of packages

Maintenance90

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity36

Early-stage or recently created project

 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

46d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/1d5f48320c88e00c997df26416eb613aa49554a6d1e719552a4e00fd83bffec5?d=identicon)[tomonori855-hub](/maintainers/tomonori855-hub)

---

Top Contributors

[![niktomo](https://avatars.githubusercontent.com/u/266456726?v=4)](https://github.com/niktomo "niktomo (10 commits)")

---

Tags

randomAlgorithmlotteryprobabilityselectionweightedsamplegacha

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/niktomo-weighted-sample/health.svg)

```
[![Health](https://phpackages.com/badges/niktomo-weighted-sample/health.svg)](https://phpackages.com/packages/niktomo-weighted-sample)
```

###  Alternatives

[paragonie/random_compat

PHP 5.x polyfill for random\_bytes() and random\_int() from PHP 7

8.2k655.0M405](/packages/paragonie-random-compat)[markrogoyski/math-php

Math Library for PHP. Features descriptive statistics and regressions; Continuous and discrete probability distributions; Linear algebra with matrices and vectors, Numerical analysis; special mathematical functions; Algebra

2.4k7.1M40](/packages/markrogoyski-math-php)[ircmaxell/random-lib

A Library For Generating Secure Random Numbers

84130.2M119](/packages/ircmaxell-random-lib)[ihor/nspl

Non-standard PHP library (NSPL) - functional primitives toolbox and more

381368.5k](/packages/ihor-nspl)[pragmarx/random

Create random chars, numbers, strings

714.2M5](/packages/pragmarx-random)[orangesoft/throttler

Load balancer between nodes.

1732.3k1](/packages/orangesoft-throttler)

PHPackages © 2026

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