Pair framework: RequestData

Pair\Api\RequestData is a small contract for custom endpoint request objects.

Use it when a controller should validate input and map it into an explicit typed object before running domain logic.

Contract

interface RequestData {

    public static function fromArray(array $data): static;

}

fromArray() receives already-validated data from Request::validateObjectOrResponse().

Example

use Pair\Api\RequestData;

final readonly class CreateOrderRequest implements RequestData {

    public function __construct(
        public int $customerId,
        public float $amount,
        public string $currency
    ) {}

    public static function fromArray(array $data): static
    {
        return new self(
            (int)$data['customerId'],
            (float)$data['amount'],
            strtoupper((string)$data['currency'])
        );
    }

}

Controller usage:

$payload = $this->request->validateObjectOrResponse(CreateOrderRequest::class, [
    'customerId' => 'required|int',
    'amount' => 'required|numeric|min:0.01',
    'currency' => 'required|string|max:3',
]);

if ($payload instanceof \Pair\Api\ApiErrorResponse) {
    return $payload;
}

return \Pair\Api\ApiResponse::jsonResponse([
    'customerId' => $payload->customerId,
], 201);

Notes

• RequestData does not perform validation by itself.
• Keep normalization and type casting inside fromArray().
• validateObjectOrResponse() returns an ApiErrorResponse instead of terminating immediately when validation fails.
• Request::validate() remains the legacy terminate-on-error bridge.

See also: Request, ApiController, ApiResponse.