PHPackages                             battlerattle/shuffle-bag - 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. battlerattle/shuffle-bag

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

battlerattle/shuffle-bag
========================

Shuffle Bag for better random distribution

v1.0-beta(13y ago)323MITPHP

Since Apr 20Pushed 12y ago1 watchersCompare

[ Source](https://github.com/BattleRattle/shuffle-bag)[ Packagist](https://packagist.org/packages/battlerattle/shuffle-bag)[ RSS](/packages/battlerattle-shuffle-bag/feed)WikiDiscussions master Synced 4w ago

READMEChangelogDependenciesVersions (2)Used By (0)

Shuffle Bag
===========

[](#shuffle-bag)

Build status: [![Build Status](https://camo.githubusercontent.com/b3142ee5ec9412b71f2a723a85aa02931c86cfde52f82437b56ab2609be44f78/68747470733a2f2f7472617669732d63692e6f72672f426174746c65526174746c652f73687566666c652d6261672e706e673f6272616e63683d6d6173746572)](https://travis-ci.org/BattleRattle/shuffle-bag)

Scrutinizer: [![Scrutinizer Quality Score](https://camo.githubusercontent.com/704a50a117f67a6c6333ca5fb2698a5298ae8cc547a4295afde351db8e71dc7a/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f426174746c65526174746c652f73687566666c652d6261672f6261646765732f7175616c6974792d73636f72652e706e673f733d39363232343331303663393566633764376133343165653536323437353139346161666665373737)](https://scrutinizer-ci.com/g/BattleRattle/shuffle-bag/)

Packagist: [![Latest Stable Version](https://camo.githubusercontent.com/67412463bd8262259d6cfd5d80123e46636ea2be8bcb36480d04404741f5225f/68747470733a2f2f706f7365722e707567782e6f72672f626174746c65726174746c652f73687566666c652d6261672f762f737461626c652e706e67)](https://packagist.org/packages/battlerattle/shuffle-bag)

This is a Shuffle Bag implementation, highly inspired by [this nice article](http://gamedev.tutsplus.com/tutorials/implementation/shuffle-bags-making-random-feel-more-random/) and its C# example.

What is a Shuffle Bag?
----------------------

[](#what-is-a-shuffle-bag)

A Shuffle Bag can be used for picking random items while reaching the targeted distribution after max. X picks, where X means the sum of all amounts the items were added.

The Shuffle Bag could be used in games in order to provide a certain amount of randomness while having the guarantee to keep the game balanced at the same time.

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

[](#installation)

The easiest way to install this library is to use [Composer](http://getcomposer.org/)Add the package "battlerattle/shuffle-bag" to your composer.json

```
{
    "require": {
        "battlerattle/shuffle-bag": "v1.0-beta"
    }
}
```

Example
-------

[](#example)

Imagine you want 3 different items to be picked with a probability of 10%, 30% and 60%. Add those items 1, 3 and 6 times to your bag and after 10 picks you got the targeted distribution. Add those items 10, 30 and 60 times in order to get a better randomness, because you could get the first item 10 times in row by random, but after max. 100 picks, you reached the target distribution again.

Usage
-----

[](#usage)

Here we implement the example as described above:

```
use BattleRattle\ShuffleBag\ArrayShuffleBag;

$bag = new ArrayShuffleBag();

// add your items with a certain probability
$bag->add('item 1', 1);
$bag->add('item 2', 3);
$bag->add('item 3', 6);

// pick a random item
$item = $bag->next();
```

In order to use the same bag over multiple requests, you need to store the bag in a persistent storage. Here we use the PersistentShuffleBag with Redis ([Predis](https://github.com/nrk/predis)) as storage:

```
use BattleRattle\ShuffleBag\PersistentShuffleBag;
use BattleRattle\ShuffleBag\Storage\RedisStorage;
use Predis\Client;

$redisClient = new Client();
$storage = new RedisStorage($redisClient);
$bag = new PersistentShuffleBag($storage);

$bag->add('foo', 42);
$bag->add('bar', 1337);

$item = $bag->next();
```

###  Health Score

24

—

LowBetter than 31% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity10

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity49

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

4819d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/1455740?v=4)[Norman Soetbeer](/maintainers/BattleRattle)[@BattleRattle](https://github.com/BattleRattle)

---

Top Contributors

[![BattleRattle](https://avatars.githubusercontent.com/u/1455740?v=4)](https://github.com/BattleRattle "BattleRattle (21 commits)")

### Embed Badge

![Health badge](/badges/battlerattle-shuffle-bag/health.svg)

```
[![Health](https://phpackages.com/badges/battlerattle-shuffle-bag/health.svg)](https://phpackages.com/packages/battlerattle-shuffle-bag)
```

PHPackages © 2026

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