PHPackages                             bentools/picker - 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. bentools/picker

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

bentools/picker
===============

Helps you pick a random item with weight management.

3.0(9mo ago)312.2k↓33.3%1MITPHPPHP >=8.2CI passing

Since Aug 28Pushed 9mo ago1 watchersCompare

[ Source](https://github.com/bpolaszek/picker)[ Packagist](https://packagist.org/packages/bentools/picker)[ RSS](/packages/bentools-picker/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (4)Dependencies (4)Versions (8)Used By (0)

[![Latest Stable Version](https://camo.githubusercontent.com/5f870d1527b6ac40a0fbab7989458a273dab5e4d75ac87a35a75ddd1bb1dacc4/68747470733a2f2f706f7365722e707567782e6f72672f62656e746f6f6c732f7069636b65722f762f737461626c65)](https://packagist.org/packages/bentools/picker)[![License](https://camo.githubusercontent.com/fbf21ce4df9285cc33d10e1396022e2933cfdb450c0ee2cdced3bfa9f0f77899/68747470733a2f2f706f7365722e707567782e6f72672f62656e746f6f6c732f7069636b65722f6c6963656e7365)](https://packagist.org/packages/bentools/picker)[![CI Workflow](https://github.com/bpolaszek/picker/actions/workflows/php.yml/badge.svg)](https://github.com/bpolaszek/picker/actions/workflows/php.yml)[![Coverage Status](https://camo.githubusercontent.com/5fc9d1e8e55cc095997a941f01942319a6e1216b470d605edd1ac49408163ab5/68747470733a2f2f636f766572616c6c732e696f2f7265706f732f6769746875622f62706f6c61737a656b2f7069636b65722f62616467652e7376673f6272616e63683d6d6173746572)](https://coveralls.io/github/bpolaszek/picker?branch=master)[![Total Downloads](https://camo.githubusercontent.com/eb4f2d8248a38af03dcf4ec309a6b8304a6e8dbf851a2b4bd6e078952e34aa5f/68747470733a2f2f706f7365722e707567782e6f72672f62656e746f6f6c732f7069636b65722f646f776e6c6f616473)](https://packagist.org/packages/bentools/picker)

Picker
======

[](#picker)

A PHP library for randomly picking items from collections and generating random numbers with advanced options like seeding, weighting, and more.

Features
--------

[](#features)

- Pick random items from collections
- Generate random numbers with optional seeding
- Support for weighted item selection
- Option to allow or prevent duplicates in selections
- Consistent results with seeded randomization

Quick Start
-----------

[](#quick-start)

### Picking Items from a Collection

[](#picking-items-from-a-collection)

#### Basic usage

[](#basic-usage)

```
use BenTools\Picker\Picker;

$items = ['apple', 'banana', 'cherry'];
$picker = Picker::fromItems($items);
$randomItem = $picker->pick(); // Returns a random item from the array
```

#### Prevent duplicates

[](#prevent-duplicates)

It will avoid, as much as possible, picking the same item twice in a row.

If all items have been picked, it will cycle through them again.

```
use BenTools\Picker\Picker;
use BenTools\Picker\ItemPicker\ItemPickerOptions;

$options = new ItemPickerOptions(allowDuplicates: false);
$picker = Picker::fromItems($items, $options);
$randomItem = $picker->pick(); // Will cycle through all items before repeating
```

### Direct Number Generation

[](#direct-number-generation)

```
use function BenTools\Picker\random_int;

// Alternative to PHP's built-in random_int with optional seeding
$randomNumber = random_int(1, 100); // Behaves like PHP's random_int()
$seededNumber = random_int(1, 100, 12345); // Deterministic output for given seed
```

Advanced Usage
--------------

[](#advanced-usage)

### Item Picker Options

[](#item-picker-options)

```
use BenTools\Picker\Picker;
use BenTools\Picker\ItemPicker\ItemPickerOptions;
use BenTools\Picker\ItemPicker\Algorithm\Algorithm;

$options = new ItemPickerOptions(
    algorithm: Algorithm::RANDOM, // Selection algorithm
    defaultWeight: 1,             // Default weight for items
    allowDuplicates: true,        // Whether to allow the same item to be picked multiple times
    maxLoops: PHP_INT_MAX,        // Maximum number of times to loop through all items
    seed: 12345,                  // Optional seed for reproducible results
    // weights: $customWeightProvider // Custom weight provider implementation
);

$picker = Picker::fromItems(['apple', 'banana', 'cherry'], $options);
```

Use Cases
---------

[](#use-cases)

- Randomizing elements in games
- Implementing A/B testing
- Creating fair selection mechanisms
- Generating random but reproducible test data
- Implementing weighted random selection for various algorithms

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

[](#installation)

This library requires PHP 8.2+.

> composer require bentools/picker

Tests
-----

[](#tests)

> ./vendor/bin/pest

See also
--------

[](#see-also)

[bentools/split-test-analyzer](https://github.com/bpolaszek/split-test-analyzer)

[bentools/cartesian-product](https://github.com/bpolaszek/cartesian-product)

###  Health Score

48

—

FairBetter than 95% of packages

Maintenance55

Moderate activity, may be stable

Popularity28

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity80

Battle-tested with a long release history

 Bus Factor1

Top contributor holds 62.5% 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

Every ~481 days

Recently: every ~407 days

Total

7

Last Release

297d ago

Major Versions

1.0.1 → 2.02021-02-07

2.1.1 → 3.x-dev2025-07-25

PHP version history (3 changes)1.0PHP >=5.6

2.0PHP >=7.3

3.x-devPHP >=8.2

### Community

Maintainers

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

---

Top Contributors

[![bpolaszek](https://avatars.githubusercontent.com/u/5569077?v=4)](https://github.com/bpolaszek "bpolaszek (5 commits)")[![misaert](https://avatars.githubusercontent.com/u/12974251?v=4)](https://github.com/misaert "misaert (3 commits)")

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/bentools-picker/health.svg)

```
[![Health](https://phpackages.com/badges/bentools-picker/health.svg)](https://phpackages.com/packages/bentools-picker)
```

PHPackages © 2026

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