Flexible Item Methods

Method Names

• probability

• elimination

• weightedElimination

• roundRobin

• cumulative

• batched

• timeBased

• weightedBatch

• sequential

• rangeWeighted

Shared Options

• count (int, default 1)

• check (bool, default true)

Additional option:

• withReplacement applies to batched only (default false)

Method Requirements and Semantics

probability

Required item keys: name, weight

Weighted draw with replacement.

elimination

Required item keys: name

Uniform draw without replacement.

weightedElimination

Required item keys: name, weight

Weighted draw without replacement.

roundRobin

Required item keys: name

Cycles through items in deterministic order.

cumulative

Required item keys: name

Maintains cumulative scores and picks highest score each step.

batched

Required item keys: name

Batch draw for count picks, replacement controlled by withReplacement.

timeBased

Required item keys: name, weight, time

Applies urgency boost based on elapsed time since last pick.

Supported time values:

• minute

• hourly

• daily

• weekly

• monthly

weightedBatch

Required item keys: name, weight

Batch variant of weighted probability draw.

sequential

Required item keys: name

Deterministic sequential traversal.

rangeWeighted

Required item keys: name, min, max, weight

Chooses a range by weight then samples in that range.

Return type behavior:

• integer result when both min and max are integers

• float result otherwise

Examples

Probability:

<?php
$result = $draw->execute([
    'method' => 'probability',
    'items' => [
        ['name' => 'item1', 'weight' => 0.2],
        ['name' => 'item2', 'weight' => 0.8],
    ],
    'options' => ['count' => 3],
]);

Elimination:

<?php
$result = $draw->execute([
    'method' => 'elimination',
    'items' => [
        ['name' => 'item1'],
        ['name' => 'item2'],
        ['name' => 'item3'],
    ],
    'options' => ['count' => 2],
]);

Weighted Elimination:

<?php
$result = $draw->execute([
    'method' => 'weightedElimination',
    'items' => [
        ['name' => 'item1', 'weight' => 10],
        ['name' => 'item2', 'weight' => 20],
    ],
    'options' => ['count' => 2],
]);

Round Robin:

<?php
$result = $draw->execute([
    'method' => 'roundRobin',
    'items' => [
        ['name' => 'item1'],
        ['name' => 'item2'],
    ],
    'options' => ['count' => 4],
]);

Cumulative:

<?php
$result = $draw->execute([
    'method' => 'cumulative',
    'items' => [
        ['name' => 'item1'],
        ['name' => 'item2'],
    ],
    'options' => ['count' => 3],
]);

Batched (without replacement):

<?php
$result = $draw->execute([
    'method' => 'batched',
    'items' => [
        ['name' => 'item1'],
        ['name' => 'item2'],
        ['name' => 'item3'],
    ],
    'options' => ['count' => 2, 'withReplacement' => false],
]);

Time Based:

<?php
$result = $draw->execute([
    'method' => 'timeBased',
    'items' => [
        ['name' => 'item1', 'weight' => 10, 'time' => 'daily'],
        ['name' => 'item2', 'weight' => 20, 'time' => 'weekly'],
    ],
    'options' => ['count' => 2],
]);

Weighted Batch:

<?php
$result = $draw->execute([
    'method' => 'weightedBatch',
    'items' => [
        ['name' => 'item1', 'weight' => 10],
        ['name' => 'item2', 'weight' => 20],
    ],
    'options' => ['count' => 3],
]);

Sequential:

<?php
$result = $draw->execute([
    'method' => 'sequential',
    'items' => [
        ['name' => 'item1'],
        ['name' => 'item2'],
    ],
    'options' => ['count' => 3],
]);

Range Weighted:

<?php
$result = $draw->execute([
    'method' => 'rangeWeighted',
    'items' => [
        ['name' => 'item1', 'min' => 1, 'max' => 50, 'weight' => 10],
        ['name' => 'item2', 'min' => 5, 'max' => 25, 'weight' => 15],
    ],
    'options' => ['count' => 2],
]);