Request and Response Contract

Request and Response Contract#

Unified Request Envelope#

All draw calls use Draw::execute(array $request).

<?php
$result = $draw->execute([
    'method' => '...',
    'items' => [...],
    'candidates' => [...],
    'sourceFile' => '...',
    'options' => [...],
]);

Field Reference#

  • method (required): one of supported method names.

  • items (required except campaign.batch): method-specific payload.

  • candidates (required for grand and campaign.*): user IDs.

  • sourceFile (optional for grand): CSV alternative to candidates.

  • options (optional): method options.

Method-to-Required-Field Map#

  • lucky: items

  • flexible item methods: items

  • grand: items + (candidates or sourceFile)

  • campaign.run: items + candidates

  • campaign.batch: candidates + options.phases

  • campaign.simulate: items + candidates

Method Option Matrix#

lucky

  • options.count (default 1)

  • options.check (default true)

Flexible item methods

  • options.count (default 1)

  • options.check (default true)

  • options.withReplacement (batched only, default false)

grand

  • options.retryCount (compatibility metadata; pool-based logic is used)

campaign.run

  • options.rules

  • options.seed

  • options.cachePool

  • options.eligibility

  • options.auditSecret

  • options.withExplain (default false)

  • options.retryLimit (compatibility metadata)

campaign.batch

  • options.phases (required)

  • options.rules

  • options.seed

  • options.cachePool

  • options.eligibility

  • options.auditSecret

  • options.withExplain

  • options.retryLimit (compatibility metadata)

campaign.simulate

  • options.iterations (default 1000)

  • options.seed (default 0)

  • options.retryLimit (compatibility metadata)

Unified Response Envelope#

Every method returns:

<?php
[
    'method' => '...',
    'entries' => [
        [
            'itemId' => ?string,
            'candidateId' => ?string,
            'value' => mixed,
            'meta' => array,
        ],
    ],
    'raw' => mixed,
    'meta' => [
        'mode' => 'single|multi',
        'requestedCount' => int,
        'returnedCount' => int,
        'fulfilled' => bool,
        'partialReason' => ?string,
        'unfilledCount' => int,
        // method-specific extra metadata may be present
    ],
]

Meta Semantics#

  • requestedCount: requested slots/picks

  • returnedCount: produced entries

  • fulfilled: true when request is fully satisfied

  • partialReason: explanation when not fulfilled

  • unfilledCount: remaining slots not returned

Common partialReason values:

  • insufficient_unique_candidates

  • no_eligible_candidates

  • unfulfilled

raw Payload by Method Family#

lucky and flexible item methods

Usually list-like method output values.

grand

array<string, list<string>> keyed by item ID.

campaign.run

winners, slotPlan, optional explain, partialReason, audit.

campaign.batch

phases, partialReason, audit.

campaign.simulate

iterations, totalSlots, userDistribution, itemDistribution.