Skip to content

bpolaszek/picker

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

8 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Latest Stable Version License CI Workflow Coverage Status Total Downloads

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

See also

bentools/split-test-analyzer

bentools/cartesian-product

About

Helps you pick a random item with weight management.

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Contributors 2

  •  
  •  

Languages