https://github.com/bpolaszek/picker
Helps you pick a random item with weight management.
https://github.com/bpolaszek/picker
Last synced: 3 months ago
JSON representation
Helps you pick a random item with weight management.
- Host: GitHub
- URL: https://github.com/bpolaszek/picker
- Owner: bpolaszek
- License: mit
- Created: 2017-08-28T13:29:26.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2022-10-05T13:44:31.000Z (over 3 years ago)
- Last Synced: 2024-09-12T22:48:03.350Z (over 1 year ago)
- Language: PHP
- Size: 9.77 KB
- Stars: 3
- Watchers: 3
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://packagist.org/packages/bentools/picker)
[](https://packagist.org/packages/bentools/picker)
[](https://github.com/bpolaszek/picker/actions/workflows/php.yml)
[](https://coveralls.io/github/bpolaszek/picker?branch=master)
[](https://packagist.org/packages/bentools/picker)
# 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
```php
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.
```php
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
```php
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
```php
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](https://github.com/bpolaszek/split-test-analyzer)
[bentools/cartesian-product](https://github.com/bpolaszek/cartesian-product)