Grand Method

Grand Method#

Method Name#

  • grand

Purpose#

Allocates user winners to item counts using a user pool without replacement.

Input#

  • items: map of item IDs to non-negative integer counts

  • user source:

    • candidates: non-empty user ID array, or

    • sourceFile: path to CSV file containing user IDs

When both are present, sourceFile is used.

Options#

  • retryCount (int, default 10): kept in response meta for compatibility.

Selection Behavior#

  • Uses a shrinking candidate pool (no replacement).

  • A user can win at most once per draw execution.

  • If requested slots exceed unique users, response is partial.

  • Candidate IDs are trimmed, empty values are removed, and duplicates are deduplicated.

Partial Fulfillment Metadata#

When there are not enough unique users:

  • meta.fulfilled = false

  • meta.partialReason = ‘insufficient_unique_candidates’

  • meta.unfilledCount > 0

Example#

<?php
$result = $draw->execute([
    'method' => 'grand',
    'items' => ['gift_a' => 5, 'gift_b' => 2],
    'candidates' => ['u1', 'u2', 'u3', 'u4'],
    'options' => ['retryCount' => 50],
]);

CSV Source Example#

CSV format rules:

  • Comma-delimited CSV is expected.

  • The draw reads only the first column (column 0) from each row as the user ID.

  • Empty first-column values are ignored.

  • Duplicate user IDs are deduplicated.

  • There is no automatic header skip, so do not include a header row unless you want it treated as a user ID.

Example users.csv:

u1
u2
u3
u4

or multi-column CSV (only first column is used):

u1,active,US
u2,active,CA
u3,paused,UK

PHP usage:

<?php
$result = $draw->execute([
    'method' => 'grand',
    'items' => ['gift_a' => 2],
    'sourceFile' => '/path/to/users.csv',
]);