RequestData

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 the fields selected and validated by the rules passed to Request::validateObjectOrResponse(). An empty rule array produces an empty data array; it does not infer rules from the request object's constructor or forward the entire request.

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().
• Supply rules for every field the mapper needs. Unknown rules are not enforced, and optional null fields are omitted from the validated array; see Request for the exact validation boundaries.
• Required fields can rely on their validation rules; optional fields need defaults or explicit presence checks before array access.
• The mapper's class must exist and implement RequestData; invalid classes raise InvalidArgumentException. Exceptions thrown by fromArray() propagate to the caller rather than becoming field-validation errors.
• 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.