README

Picker

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

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

Picking Items from a Collection

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

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

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

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

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

This library requires PHP 8.2+.

composer require bentools/picker

Tests

./vendor/bin/pest

bentools / picker

Maintainers

Details